qa-plan

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow,qa.level,system_overrides

上記で解決済み — そのまま使用します。ブロックがない場合は .claude/docs/config-resolution.md のデフォルト値を使用します。

QA プラン

このスキルは、スプリント、機能、または個別のストーリー向けに構造化された QA プランを生成します。対象範囲内のすべてのストーリーファイルとそれらが参照する GDD を読み込み、各ストーリーをテストタイプ別に分類し、開発者に対して何を自動化すべきか、何を手動で検証すべきか、スモークテストの範囲はどこまでか、いつプレイテスターを招集すべきかを正確に示すプランを作成します。

スプリント開始前にこれを実行して、チームが事前に必要なテスト作業を把握できるようにしてください。実装後に書かれたテストプランはポストモーテムであり、プランではありません。

出力: production/qa/qa-plan-[sprint-slug]-[date].md

---

すべての AskUserQuestion 呼び出しは .claude/docs/automation-modes.md に従います （collaborative は常に確認 · guided は major のみ · autonomous はログを記録して続行。 automation_always_ask カテゴリは常にプロンプトを表示）。

ワークフローティア: 各 GDD を読み込むたびに、その GDD のシステムに応じて解決します （.claude/docs/workflow-modes.md に準拠）: workflow_overrides.system_overrides.<system> にブロックが記載されていればその値、そうでなければプロジェクト値を使用します。これは、 テストプランをどの GDD セクションから抽出するか（そのセクション数）を決定します — Phase 2 を参照。

qa.level: minimal の場合は最小限のスモークプランのみを生成します — 自動テスト必須の行とテストファイルの DoD を省略します。standard の場合は ストーリータイプごとの完全なプランを生成します。full の場合はさらに、システムごとの カバレッジ目標を追加します。workflow とは別の軸です（workflow は GDD セクションを いくつ抽出するかを設定します）。どのレベルでも Visual/Feel と UI スクリーンショットの行は 省略されません — minimal ではテストは免除されますが、見た目は免除されません （.claude/docs/coding-standards.md）。

フェーズ 1：スコープの解析

引数： $ARGUMENTS（空欄の場合は AskUserQuestion でユーザーに確認します）

引数からスコープを判定します。

• sprint — production/sprints/ にある最新のファイルを読み込み、参照されているすべてのストーリーファイルのパスを抽出します。production/sprint-status.yaml が存在する場合は、それを主要なストーリー一覧として使用し、ストーリーのメタデータはスプリント計画で補います。
• feature: [system-name] — production/epics/*/story-*.md を glob で検索し、ファイルパスまたはタイトルにシステム名が含まれるストーリーに絞り込みます。そのシステムのディレクトリにあるエピックのインデックスファイル（EPIC.md）も確認します。
• story: [path] — パスが存在することを確認し、そのファイルのみを読み込みます。
• 引数なし — AskUserQuestion を使用します。
  • 「この QA 計画のスコープは何ですか？」
  • 選択肢：「現在のスプリント」、「特定の機能（システム名を入力）」、 「特定のストーリー（パスを入力）」、「エピック全体」

スコープの解決後、次のように報告します：「[scope] 内の [N] 件のストーリーについて QA 計画を作成します。」

ストーリーファイルのパスが参照されていても、ファイルが存在しない場合は MISSING と記録し、残りのストーリーの処理を続行します。ファイルが1つ欠けているために計画全体を中止してはいけません。

解決されたスコープにストーリーが1件も含まれない場合は停止し、計画を作成しないでください。 NOT ASSESSED — no stories in scope と報告し、検索したスコープと空だったパスを明記して、次のように案内します。

• production/sprints/ にファイルがない → 「スプリント計画が見つかりません。/sprint-plan new を実行してください。」 workflow: minimal では設計上スプリントが存在しません。その場合は代わりに /qa-plan feature: [epic-slug] または /qa-plan story: [path] を案内します。
• スプリント計画は存在するものの、ストーリーを参照していない → 「スプリント計画 [path] にストーリーがありません。/create-stories [epic-slug] を実行してください。」
• feature:／story: のスコープで該当項目がない → 検索結果が空だった glob を明記します。

N=0 のガードは必須です。 これがないと、空のスコープに対して「0 件のストーリーについて QA 計画を作成します」と報告してフェーズ 4 まで進み、空の表を含む計画書が作成されます。そして、ストーリーが0件の QA 計画は、完成した QA 計画とまったく同じように見えます。 このスキルは手動 QA への引き継ぎを制御するため、ここで誤って問題なしと判断すると、何もテストしていない計画を根拠にビルドが QA に送られてしまいます。

このブロックの冒頭にあるルールは引き続き有効です。複数あるファイルのうち1つが欠けている場合は、MISSING と記録して処理を続行します。これは、そもそも複数のファイルがないという別のケースです。

---

フェーズ 2：入力の読み込み

まず分母を確定します。対象範囲内のストーリーファイルを glob で検索し、N 件を数えてから、以下のフィールドを収集します。各ストーリーをすべて読むのではなく、対象を絞ったセクションの grep を使ってください。QA 計画に必要なのは各ストーリーのタイプと受け入れ条件です。実装メモ、対象外の範囲、ADR の根拠は必要ありません。2 つのセクションを見つけるために N 件のストーリーを最初から最後まで読むことが、このフェーズのコストにつながります。

Grep pattern="^## Acceptance Criteria" glob="production/epics/**/story-*.md" output_mode="content" -A 15
Grep pattern="^> \*\*(Type|Status|Estimate)\*\*" glob="production/epics/**/story-*.md" output_mode="content"
Grep pattern="^## (Context|Dependencies)" glob="production/epics/**/story-*.md" output_mode="content" -A 8

（sprint モードでは、スプリント計画に記載されたストーリーパスに glob の範囲を限定してください。）それらのファイルから、以下を取得します。

• ストーリーのタイトルとストーリー ID — ファイル名とパスから取得します。読み込みは不要です
• Story Type フィールド — ヘッダーの grep から取得します（例：Type: Logic）
• 受け入れ条件 — 最初の grep から、番号付きまたは箇条書きのリスト全体を取得します
• GDD / ADR の参照と依存関係 — ## Context の grep から取得します
• 見積もり — 存在する場合は、ヘッダーの grep から取得します
• 実装ファイルとエンジンに関する注記 — テスト計画で必要になるストーリーに限って取得します。その個別のストーリーを全体まで読み込んでください

セクションが見つからないことを、ストーリーが存在しないことと決して見なさないでください。 ## Acceptance Criteria に一致するものがなかったストーリーは、その 1 件を全体まで読み込み、その旨を記載してください。テスト可能な条件がないストーリー自体が QA 上の指摘事項であり、スキップする対象ではありません。

ストーリーを読んだ後、補足コンテキストを一度だけ（ストーリーごとではなく）読み込みます。

• design/gdd/systems-index.md — システムの優先度と、承認済みの GDD を把握するため
• すべてのストーリーで参照されている GDD ごとに、そのシステムのワークフロー階層（上記で確定済み）に応じてテスト材料を抽出します。full では 8 セクションすべてを抽出し、standard では必須セクションのうちテストに関連する部分を抽出します（Acceptance Criteria と Edge Cases は常に対象とし、数値ルールを定義するシステムでは Formulas も対象とします）。minimal では Acceptance Criteria のみを抽出します。GDD 全文を読み込まないでください。Grep ツールでセクション見出しを検索し（パターン ^#、content モード）、Read で offset と limit を指定して該当範囲を読み込みます。これらのセクションには、テスト可能な要件、検証すべき計算式、テストで網羅する境界条件が記載されています。Edge Cases セクションがない場合（または minimal では想定されていない場合）は、GDD ごとに「Edge Cases セクションが見つかりません — エッジケースの網羅性は受け入れ条件のみから推定します。」と記載します。
• docs/architecture/control-manifest.md — 自動テストで防止すべき禁止パターンを確認します（ファイルが存在する場合）

ストーリーで GDD が参照されていない場合は、ギャップとして記載しますが、計画を止めないでください。そのストーリーは、受け入れ条件のみを使って分類します。

---

フェーズ 3：各ストーリーを分類する

各ストーリーにストーリータイプを割り当てます。

• ストーリーのヘッダーにすでに Type: フィールドがある場合：そのまま採用します。以下の基準に照らして再分類または検証してはいけません。Type はストーリー作成時にリードプログラマーが設定したもので、正式なものです。そのまま記録します。
• Type: フィールドがない場合：以下の表を使用し、受け入れ条件からタイプを推定します。レポートには、タイプを推定した（宣言されたものではない）ことを記載します。これは不足事項としてフラグを立てます。実装開始前に、ストーリーの Type を明示的に宣言する必要があります。

ストーリータイプ	分類の指標
Logic	受け入れ条件に、計算、数式、数値のしきい値、状態遷移、AI の判断、データ検証、バフ／デバフのスタック、経済取引、またはテスト可能な計算処理への言及がある
Integration	条件に、2 つ以上のシステム間の相互作用、システム間でのシグナルやイベントの伝播、セーブ／ロードの往復、ネットワーク同期、または永続化が含まれる
Visual/Feel	条件に、アニメーションの動作、VFX、シェーダーの出力、「応答性がよく感じられること」、体感上のタイミング、画面の揺れ、パーティクル効果、オーディオ同期、またはビジュアルフィードバックの品質への言及がある
UI	条件に、メニュー、HUD 要素、ボタン、画面、ダイアログボックス、インベントリパネル、ツールチップ、またはプレイヤー向けのインターフェース要素への言及がある
Config/Data	変更がバランス調整値、データファイル、または設定に限られ、新しいコードロジックを伴わない

複合ストーリー（例：数式と UI 表示の両方を追加するストーリー）の場合： 受け入れ条件のうち、実装リスクが最も高いものに基づいて主タイプを割り当て、二次タイプも記載します。Logic+Integration と Visual+UI の組み合わせが最も一般的です。

すべてのストーリーを分類したら、フェーズ 4 に進む前に、会話内で分類の概要表を作成します。これにより、テストをどのように割り当てるかをユーザーが確認できます。

---

フェーズ 4：テスト計画を作成する

以下の構成に従って、QA 計画書全体をまとめます。

# QA Plan: [Sprint/Feature Name]
**Date**: [date]
**Generated by**: /qa-plan
**Scope**: [N stories across [N systems]]
**Engine**: [engine name — `engine.name` from project.yaml if present and non-empty, else the Engine field from .claude/docs/technical-preferences.md, else "Not configured"]
**Sprint File**: [path to sprint plan if applicable]

---

## Test Summary

| Story | Type | Automated Test Required | Manual Verification Required |
|-------|------|------------------------|------------------------------|
| [story title] | Logic | Unit test — `tests/unit/[system]/` | None |
| [story title] | Integration | Integration test — `tests/integration/[system]/` | Smoke check |
| [story title] | Visual/Feel | None (not automatable) | Screenshot + lead sign-off |
| [story title] | UI | None (verified by its screenshots) | Retained screenshot of each screen touched |
| [story title] | Config/Data | Data validation test | Spot-check in-game values |

---

## Automated Tests Required

*(At `qa.level: minimal`, omit this entire section and blank the Test Summary's
"Automated Test Required" column — automated tests are not required there; list
manual/smoke verification only.)*

### [Story Title] — [Type]
**Test file path**: `tests/[unit|integration]/[system]/[story-slug]_test.[ext]`
**What to test**:
- [Specific formula or rule from the GDD Formulas section]
- [Each named state transition or decision branch]
- [Each side effect that should or should not occur]

**Edge cases to cover**:
- Zero/minimum input values (e.g., 0 damage, empty inventory)
- Maximum/boundary input values (e.g., max level, stat cap)
- Invalid or null input (e.g., missing target, dead entity)
- [Any edge case explicitly called out in the GDD Edge Cases section]

**Estimated test count**: ~[N] unit tests

[If no GDD formula reference was found for this story, note:]
*No formula found in referenced GDD — test cases must be derived from acceptance
criteria directly. Review the GDD Formulas section before writing tests.*

---

## Manual QA Checklist

### [Story Title] — [Type]
**Verification method**: [Screenshot + designer sign-off | Playtest session |
Manual step-through | Comparison against reference footage]
**Who must sign off**: [designer / lead-programmer / qa-lead / art-director]
**Evidence to capture**: [screenshot of X | video clip of Y | written playtest
notes | side-by-side comparison]

Checklist:
- [ ] [Specific observable condition — concrete and falsifiable]
- [ ] [Another condition]
- [ ] [Every acceptance criterion translated into a manual check item]

*If any criterion uses subjective language ("feels", "looks", "seems"), it must
be supplemented with a specific benchmark or a playtest protocol note.*

---

## Smoke Test Scope

Critical paths to verify before any QA hand-off for this sprint:

1. Game launches to main menu without crash
2. New game / new session can be started
3. [Primary mechanic introduced or changed this sprint]
4. [Any system with a regression risk from this sprint's changes]
5. Save / load cycle completes without data loss (if save system exists)
6. Performance is within budget on target hardware (no new frame spikes)

*Smoke tests are verified by the developer via `/smoke-check`. Reference this
list when running that skill.*

---

## Playtest Requirements

| Story | Playtest Goal | Min Sessions | Target Player Type |
|-------|--------------|--------------|-------------------|
| [story] | [What question must the session answer?] | [N] | [new player / experienced] |

**Sign-off requirement**: Playtest notes must be written with `/playtest-report` to
`production/qa/playtests/` (naming the story) and reviewed by
the [designer / qa-lead] before the story can be marked COMPLETE.

If no stories require playtest validation: *No playtest sessions required for
this sprint.*

---

## Definition of Done — This Sprint

A story is DONE when ALL of the following are true (at `qa.level: minimal`, drop
the test-file and smoke rows below — tests are waived there; the screenshot and
sign-off rows stay at every level, because the look is not):

- [ ] All acceptance criteria verified — via automated test result OR documented
      manual evidence (screenshot, video, or playtest notes with sign-off)
- [ ] Test file exists at the specified path for all Logic and Integration stories *(qa.level standard/full)*
- [ ] Retained screenshot of each screen touched, in `production/qa/evidence/`, for all Visual/Feel and UI stories *(every qa.level)*
- [ ] Signed-off evidence doc at `production/qa/evidence/[story-slug]-evidence.md` for all Visual/Feel stories *(every qa.level)*
- [ ] Smoke check passes (run `/smoke-check sprint` before QA hand-off) *(qa.level standard/full)*
- [ ] No regressions introduced
- [ ] Code reviewed (via `/code-review` or documented peer review)
- [ ] Story file updated to `Status: Complete` (via `/story-done`)

内容を生成する際は、フェーズ 2 で抽出した実際のストーリータイトル、GDD の数式テキスト、受け入れ条件を使用します。プレースホルダーテキストは使用しないでください。各テスト項目には、これらのストーリー固有の実際の要件を反映させます。

---

フェーズ 5：出力する

計画全体を会話内に表示し（計画が非常に長い場合は概要を表示し）、その後 AskUserQuestion を使って 2 つの質問をまとめて行います。

question: "Ready to write the QA plan. Choose output options:"
multiSelect: true
options:
  - "Write QA plan to production/qa/qa-plan-[sprint-slug]-[date].md"
  - "Also back-fill test case specs into each story file's ## QA Test Cases section (Recommended — enables /dev-story and /code-review traceability)"

「Write QA plan」が選択された場合：生成したとおりに計画ファイルを書き込みます。途中で切り詰めてはいけません。

「Also back-fill story files」が選択された場合：対象範囲内の各 Logic および Integration ストーリーについて、パスにあるストーリーファイルを編集します。## QA Test Cases セクションを見つけ、その内容を、そのストーリー用にフェーズ 4 で生成したテストケース仕様に置き換えます。ストーリーに ## QA Test Cases セクションがない場合は、## Test Evidence の前に追加します。Visual/Feel および UI ストーリーについては、テスト仕様の代わりに手動検証手順を書き込みます。

書き込み後：

「QA 計画を production/qa/qa-plan-[sprint-slug]-[date].md に書き込みました。

次のステップ：

• スプリントの実装を開始する前に、この計画をチームと共有します
• すべてのスプリントストーリーが実装されたら、QA への引き継ぎ判定として /smoke-check sprint を実行します。まだ実行せず、実装完了後に実行してください
• Logic／Integration ストーリーについては、完了としてマークする前に、記載されたパスにテストファイルを作成します。/story-done で確認されます」

production/session-state/active.md に（ファイルが存在しない場合は作成して）次の内容を、ユーザーに知らせず追記します。

次の判定で締めくくります：COMPLETE — QA 計画を作成しました（書き込みを辞退した場合は COMPLETE — QA 計画を表示しましたが、書き込みはしていません）。他にあり得る結果は、フェーズ 1 の NOT ASSESSED — no stories in scope の場合のみです。

---

コラボレーションプロトコル

collaborative モード（デフォルト）で適用されます。 guided モードと autonomous モードについては、.claude/docs/automation-modes.md を参照してください。以下のルールは コラボレーションモードで必要な動作を定めたものであり、すべてのモードに共通する動作ではありません。

• 確認せずにプランを書かないでください — フェーズ 5 では明示的な承認が必要です。
• 保守的に分類してください：ストーリーが Logic と Integration のどちらか曖昧な場合は、Integration に分類してください — ユニットテストと 統合テストの両方が必要です。
• 受け入れ基準と GDD の数式で裏付けられていないテストケースを 作り出さないでください。GDD に数式がない場合は、推測せずにその旨を指摘してください。
• プレイテスト要件は助言にとどまります：境界線上にある Visual／Feel のストーリーでプレイテストが妥当かどうかは、ユーザーが判断します。該当するケースを指摘し、必須にはしないでください。
• 引数が指定されていない場合は、スコープの選択に AskUserQuestion を使用してください。 それ以外のすべてのフェーズは対話形式にせず、調査結果を提示してから、書き込みを承認するかどうかを一度だけ尋ねてください。