inkblot-jira-ticket

Inkblot Jira チケットの規約

チケットを作成または編集する際は、説明を以下のとおり正確に構成してください。 見出し名は固定です。名前を変更したり、順序を入れ替えたり、セクションを追加したりしないでください。

3つの厳守事項

1. チケットにPIIやPHIを記載しないでください。例外はありません。患者／クライアントの名前、メールアドレス、電話番号、健康カード番号、診断、セッション内容など、個人を特定できる情報は記載しないでください。人物については、役割＋不透明なIDで表記してください（例：「client user_id 12345」、「appointment 977096」、サポート参照番号「ATS-13371」）。スクリーンショット、ログ、スタックトレースを添付する前に、個人を特定できる詳細をマスキングしてください。これはEngineering Notesやコメントを含む、すべてのセクションに適用されます。
2. 受け入れ条件は、必ず説明本文の## Acceptance criteria見出しの下にチェックリスト形式で記載してください。説明はADF（contentFormat: "adf"）として作成し、条件は実際にチェックできるtaskListとして表示してください。方法については「Jira specifics」を参照してください。Jiraのサイドパネルにある「Acceptance criteria」チェックリストフィールドだけに記載してはいけません。QA、エクスポート、PRリンク、AIツールでは見落とされます。
3. ## Context、## Scope、## Acceptance criteria、および（存在する場合）## How to testは、技術に詳しくない読者（QA、PM、サポート）にも理解できる、平易でわかりやすい言葉で必ず記述してください。開発者にしか意味が通じない内容（コードパス、クラス／関数名、SQL、スタックトレース、アーキテクチャの詳細）は、---区切り線の下にある## Engineering Notesに記載してください。

テンプレート：タスク／ストーリー

## Context
Why this exists, 2–4 lines, in plain language. If there is a real end user, open with:
"As a <user>, I want <goal> so that <value>." Otherwise plain prose — never force a user story.

## Scope
What's in. What's explicitly out. Described as user/system behavior, not implementation.

## Acceptance criteria
* Testable, QA-facing statements written as observable behavior
* Include env / feature-flag prerequisites QA needs

## How to test
(Optional — include ONLY when the user explicitly asks for it. When present, follow
"How to test — writing guidance": numbered steps naming the exact app + URL, dev-tools
Network steps, the exact request/host, and the response field + expected values.
Omit by default.)

---

## Engineering Notes
(Optional, ALWAYS last, after the --- divider.)
Root cause analysis, code paths, PR/branch links, implementation ideas,
migration/rollback steps, log/NewRelic links. Nothing QA needs may live here.

テンプレート：バグ

## Steps to reproduce
1. ...

## Expected
What should happen.

## Actual
What happens instead (screenshots / errors).

## Environment
* Env:
* Browser / client:
* Account / feature flags:

## Acceptance criteria
* The observable behavior that proves the fix

## How to test
(Optional — include ONLY when the user explicitly asks for it. When present, follow
"How to test — writing guidance": exact app + URL, Network-tab steps, exact request/host,
response field + expected values.)

---

## Engineering Notes
(Optional, last — root cause, suspect code, links.)

人が再現できないバグ（インフラ／停止／競合状態）

再現条件が、人が任意のタイミングで実行できるものではない場合（上流サービスの停止、サーバーの再起動、タイミングによる競合、状態の破損など）、再現手順を無理に書かないでください。## Steps to reproduceを## What happenedに置き換え、インシデントとユーザーに見える影響を平易な言葉で簡潔に説明してください（「のX停止中、一部のユーザーに……が発生しました」など）。## Expected／## Actualでは症状に焦点を当ててください。## How to testには、QAが実際に実施できる確認項目だけを記載してください。技術的な発生条件や開発者専用の検証（ログ、Redis、メトリクス）は## Engineering Notesに記載してください。

テンプレート：スパイク

## Question
What we need to answer.

## Timebox
e.g. 2 days.

## Deliverable
Doc / decision / prototype / follow-up tickets.

How to test — 記述ガイド

## How to testは任意です（ユーザーから求められた場合にのみ含めてください）。ただし、含める場合は、コードを見たことがないQAテスターでも手順に沿って確認できるほど具体的に記述する必要があります。番号付きリストで記述してください。曖昧な表現は避け、具体的に書いてください。「ウェブアプリを開く」だけの記述はしないでください。

UIまたはAPIレスポンスで確認できる動作については、次のパターンに従ってください。

1. テスターが開くアプリの正確な名前とそのURLを記載してください（例：https://practice.inkblottherapy.comにあるPracticeアプリ、クライアント向けウェブアプリ、またはビルド番号を指定したモバイルアプリ）。使用する環境（stagingまたはprod）と、必要であればテストアカウント／ロールも記載してください。
2. セットアップを記載してください。選択するデータ（不透明なIDで指定）、切り替える機能フラグ、事前条件などです。
3. ネットワークレスポンスを確認する場合は、ブラウザーの開発者ツールを開き（右クリック→Inspect／F12）、Networkタブを開いて再読み込みするよう案内してください。
4. 正確なリクエスト（メソッド＋完全なパス、およびアクセス先のホスト。例：https://api.inkblottherapy.com/api/appointments/{id}）と、その見つけ方（フィルターボックスに入力するキーワード）を明記してください。その後、Response／Previewタブを開くよう案内してください。
5. 確認する具体的なフィールドと、各状態での期待値を記載してください（例：フラグがオンの場合はvideo_provider = vonage、オフの場合はtwilio）。
6. 検証の流れを記載してください。フラグを切り替える／入力を変更する、再読み込みする、値が期待どおりに変わることを確認する、という手順です。可能であれば、関連エンドポイントが200を返す場合と404を返す場合のような、独立した別の確認方法も追加してください。

上記の各手順はすべて---より上に、QAが理解できる言葉で記載してください。開発者専用の検証（ログ、Redis、メトリクス、DBクエリ）は## Engineering Notesに記載してください。

作成ルール

• QA は上から順に読み、--- の区切り線で止まります。それより上の内容は、コードを読んだりコードベースについて知っていたりしなくても理解できるようにしてください。
• Engineering Notes は技術的な詳細を記載する場所です。技術的な詳細はすべてここに記載し、チケット内に散在させないでください。技術的すぎるか迷った場合は、Engineering Notes に移してください。
• Summary（タイトル）：簡潔で、命令形で、具体的にしてください。末尾にピリオドを付けないでください。
• 古いチケットやクローズ済みのチケットをまとめて遡及更新しないでください。担当者から依頼があった場合は、オープン中で未着手のチケットを整形して構いません。

Jira 固有の情報（inkblottherapy.atlassian.net）

• プロジェクトは会社管理のクラシックプロジェクトです（POD2 のプロジェクト ID は 10013）。
• POD2 の Story Points フィールドは customfield_10033 です（customfield_10016 ではありません）。他のプロジェクトでポイントを設定する前に、createmeta で各プロジェクトの Story Points フィールドを確認してください。
• チェックボックス（標準）：説明は必ず ADF（contentFormat: "adf"）として作成または編集し、## Acceptance criteria は taskItem ノードの taskList としてレンダリングしてください（各ノードに attrs.localId と state: "TODO" を設定します）。これにより、Jira で実際にチェックできるチェックボックスが確実に作成されます（書き込み後の読み戻しで検証済み）。Markdown の - [ ] 形式には頼らないでください。動作が一定せず、実際のタスクリストになる場合もあれば、文字列 [ ] のままになる場合もあります。ADF を本当に利用できない場合に限り、通常の * 箇条書きにフォールバックしてください。
• 折りたたみ可能な Engineering Notes（任意）：技術的な詳細をデフォルトで折りたたんでおくには、## Engineering Notes を通常の見出しではなく ADF の expand ノードとしてレンダリングできます — { "type": "expand", "attrs": { "title": "Engineering Notes" }, "content": [ ...block content... ] }。--- の区切り線より下に配置してください。この方法を使う場合、expand の title が見出しの代わりになるため、## Engineering Notes の見出しと同じタイトルの expand の両方を出力しないでください。contentFormat: "adf" が必要です。Markdown 形式では expand が暗黙にフラット化され、折りたたみのラッパーが失われてコンテンツがインラインに移動します。折りたたみは Jira の Web UI 上での表示のみを変えるものです。API からはコンテンツ全体が常に返されます（ADF の取得ではそのまま、Markdown の取得ではインラインに展開されます）。そのため、チケットを読む AI エージェントには引き続きメモが表示されます。responseContentFormat: "adf" を指定して再取得し、保存状態を確認してください（ツールは保存された説明を Markdown として返すため、expand はフラット化されます。したがって、Markdown のエコーだけではノードが保存されたことを確認できません）。

提出前のセルフチェック

1. スクリーンショット、ログ、Engineering Notes を含め、チケットに PII/PHI（氏名、メールアドレス、電話番号、健康データ、セッション内容）が含まれていませんか？
2. 説明本文に ## Acceptance criteria があり、ADF の taskList（実際にチェックできるチェックボックス。ADF を利用できない場合のみ通常の * 箇条書き）として記述され、テスト可能な項目が 1 つ以上ありますか？
3. --- より上の内容は、## How to test がある場合はそれも含めて、技術者ではない読者（QA、PM、サポート担当者）にもすべて理解できますか？
4. ## How to test がある場合、各手順に、正確なアプリ名と URL、確認対象の正確なリクエスト／ホスト、期待値を含むレスポンスフィールドが記載されていますか（「How to test — writing guidance」に従ってください）？ユーザーから求められていない場合は省略されていますか？
5. 技術的な詳細（コードのパス、PR、根本原因、開発者向けの専門用語）はすべて --- より下の ## Engineering Notes に記載されていますか？
6. Task/Story：実際のエンドユーザーが存在する場合に限り、ユーザーストーリー形式の冒頭文を使っていますか？

レビューパス

作成する前に、セルフチェックを単なる頭の中での「はい／いいえ」ではなく、評価を伴うレビューとして実施してください。これにより、作成者が気づかないうちに見落とすミスを防げます。

2 つの方法があります。

• セルフレビュー（必須）。 下書きの作成後、セルフチェックの各項目を確認し、評価してください。
• 独立レビュー（重要度の高いチケットでは推奨）。 別のエージェント／コンテキストに、同じ基準を使って下書きを厳しくレビューしてもらってください。チケットを作成した本人は内容を安易に承認しがちですが、新たな視点でのレビューによってこそ、本当の問題が見つかります。レビュー担当者には、このスキルのルールと下書きを渡し、以下の形式で出力するよう依頼してください。

レビュー出力の形式：

1. コンプライアンスチェックリスト — 6 つのセルフチェック項目それぞれについて、PASS / FAIL / N/A と 1 行の理由を記載します。
2. 検出した問題 — それぞれに重要度を付け、必要に応じて具体的な修正案を示します。
   • blocker — ハードルールに違反している（本文のどこかに PII/PHI がある、受け入れ条件が本文に taskList として記載されていない、--- より上に開発者専用の詳細がある）、または事実に誤りがある場合です。作成前に必ず修正してください。
   • should-fix — 規約や明確さが不足しており、QA を誤解させたり、対象範囲を誤って伝えたりするおそれがある場合です（例：要約が示す内容と受け入れ条件でテストする内容が食い違っている）。意図的にそうしている理由がない限り、修正してください。
   • nice-to-have — 表現や仕上げに関する改善点です。任意で対応してください。
3. 判定 — 「このまま作成してよい」または、先に必要な最小限の修正を示します。

繰り返し見落とされやすい点として、次の項目を明示的に確認してください（実際のチケットで問題になったことがあります）。

• 隠れた PII。 ブランチ名、PR／コミットへのリンク、貼り付けられたログなどに人名が含まれているケースもあります。ハードルール 1 は Engineering Notes を含むすべてのセクションに適用されます。
• タイトルと受け入れ条件の不一致。 要約が示す内容と、受け入れ条件で実際に確認する内容の範囲が異なっていないか確認してください。
• 実装を言い換えただけの受け入れ条件（「RuboCop を実行する CI ジョブを追加する」など）ではなく、観察可能な動作（「…のときにチェックが失敗する」など）を記述してください。
• 依頼されていない ## How to test の記載、またはコードを見たことがない QA 担当者には分からないほど曖昧なテスト手順。