test-evidence-review

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

自動化モード：modes.automation を解決します（project.local.yaml → project.yaml → デフォルトの collaborative）。すべての AskUserQuestion 呼び出しと すべてのファイル書き込みは、.claude/docs/automation-modes.md に従います （collaborative は常に質問 · guided は主要な項目のみ · autonomous は記録して続行； automation_always_ask カテゴリーでは常に確認します）。

qa.level と testing.strict（上で解決済み）によって、このレビューでブロッカーと 判定できる内容が決まります。これは /story-done がストーリーを完了する際に適用する ルールと同じです。そのため、ここでの BLOCKING 項目は /story-done を妨げる項目です。

• qa.level: minimal ではテストが免除されます。テストの証拠がない Logic、Integration、Config/Data ストーリー （Config/Data の場合はスモークレポートがないもの）は WAIVED (qa.level: minimal) となり、MISSING ではありません。また、BLOCKING 項目も発生しません。存在するテストは引き続きレビューされますが、その不足点は ADVISORY となります。Visual/Feel および UI の証拠（保持されたスクリーンショットと Visual/Feel の承認）は免除されません。
• ストーリータイプごとのゲートレベル：解決済みブロックから testing.strict.<type> を取得します（Logic→logic、Integration→integration、Visual/Feel→visual、UI→ui、Config/Data→config）：true → BLOCKING、false → ADVISORY、unset → 単純なブール値の testing.strict: true|false（レガシー形式）がすべてのタイプに適用されます。それ以外の場合は、 .claude/docs/coding-standards.md のデフォルトゲートレベル（Logic、Integration、Visual/Feel、UI は BLOCKING、Config/Data は ADVISORY）が適用されます。以下の「BLOCKING」はすべて、そのストーリータイプのゲートレベルを指します。

テスト証拠レビュー

/smoke-check はテストファイルの存在と成功を確認します。このスキルではさらに踏み込み、テストと証拠ドキュメントの品質をレビューします。 存在して成功するテストファイルでも、重要な動作がカバーされていない場合があります。 存在する手動証拠ドキュメントでも、完了に必要な承認が不足している場合があります。

**出力：**サマリーレポート（会話内）＋任意の production/qa/evidence-review-[date].md

実行するタイミング：

• QA への引き継ぎ承認前（/team-qa フェーズ 5）
• テスト品質に疑問があるストーリー
• Logic および Integration ストーリーの品質監査を行うマイルストーンレビューの一環

---

1. 引数を解析する

モード：

• /test-evidence-review [story-path] — 1 つのストーリーの証拠をレビューします
• /test-evidence-review sprint — 現在のスプリントにあるすべてのストーリーをレビューします
• /test-evidence-review [system-name] — エピック／システム内のすべてのストーリーをレビューします
• 引数なし — 対象範囲を確認します：「単一のストーリー」、「現在のスプリント」、「1 つのシステム」

---

2. 対象範囲のストーリーを読み込む

引数に基づいて、次のように処理します。

単一のストーリー：ストーリーファイルを直接読みます。次の項目を抽出します：ストーリータイプ、Test Evidence セクション、ストーリースラッグ、システム名。

スプリント：production/sprints/ 内で最終更新日時が最も新しいファイルを読み、スプリント計画からストーリーファイルのパス一覧を抽出します。

システム：production/epics/[system-name]/story-*.md を Glob します。

解決された対象範囲にストーリーが 1 件も含まれない場合は、ここで停止してください。
NOT ASSESSED — no stories in scope と報告し、検索した対象範囲と空だったパスを示して、次のように案内します：スプリントファイルがない場合 → /sprint-plan new（workflow: minimal ではスプリントがないため、代わりに /test-evidence-review [epic-slug]）；ストーリーの記載がないスプリント計画の場合 → /create-stories [epic-slug]；[system-name] の Glob で一致するものがない場合 → Glob を明記します。セクション 3 には進まないでください。

ストーリーごとの不明だけでなく、対象範囲が空であることにも対処してください。 判定語彙の ADEQUATE／INCOMPLETE／MISSING には「確認できなかった」ことを示す値が必要です。そうでなければ、検証できないストーリーに、誰かが検証したかのような判定が付いてしまいます。そのためにあるのが NOT ASSESSED です。しかし、ストーリーごとの不明に対処しても、対象範囲が空であることによる不明には何の対処にもなりません。 ストーリーがない場合、セクション 6 のレポートでは Summary テーブルが空のままになり、末尾に BLOCKING items: 0 / ADVISORY items: 0 と表示されます。これは「すべてレビュー済みで、問題なし」と受け取られます。このスキルはストーリーの完了を判断するゲートであり、coding-standards.md では Logic、Integration、Visual/Feel、UI のエビデンスを BLOCKING としているため、誤って問題なしと判断すると、誰にもレビューされていないストーリーが完了扱いになります。

対象となるストーリーについて、以下のフィールドを収集します。各ストーリーをすべて読むのではなく、対象を絞ったセクション検索を行ってください：

Grep pattern="## Test Evidence" glob="production/epics/**/story-*.md" output_mode="content" -A 8
Grep pattern="## Acceptance Criteria" glob="production/epics/**/story-*.md" output_mode="content" -A 15

• ストーリータイプ（Logic／Integration／Visual/Feel／UI／Config/Data）と、指定されたエビデンスのパス。どちらも ## Test Evidence 内にあるため、最初の grep の -A 8 で取得できます。
• 受け入れ条件の一覧。2 つ目の grep から ## Acceptance Criteria ブロックを取得します。
• ストーリースラッグ（ファイル名から）とシステム（ディレクトリパスから）。読み込みは不要です。 ## Test Evidence セクションがない、または内容が曖昧な場合に限り、ストーリー全体を読みます。 （スプリントモードでは、Glob の対象をスプリント計画に記載されたストーリーパスに限定します。）

---

3. エビデンスファイルを特定する

各ストーリーについて、エビデンスを探します。最初にストーリーで指定されたエビデンスのパスを確認してください。これはセクション 2 で ## Test Evidence セクションから取得したパスです。存在する場合は、それを使用します。パスが指定されていない場合、または見つからない場合に限り、検索に切り替えます。

Logic ストーリー：エンジンのユニットテストルート（Godot は tests/unit/[system]/、Unity は Assets/Tests/EditMode/、Unreal は Source/<Module>/Private/Tests/）を検索します。.claude/docs/directory-structure.md を参照し、ファイル名にストーリースラッグまたはシステム名が含まれるファイルを探します。テストファイルは .claude/rules/test-standards.md に従って命名されるため、必ずしも [story-slug]_test.* という名前ではありません。

Integration ストーリー：同じ方法で、インテグレーションのルート（tests/integration/[system]/、Assets/Tests/PlayMode/、または Unreal のテストルート）を検索します。

• ストーリーに言及しているプレイテスト記録がないか、production/qa/playtests/ も確認します。

Visual/Feel および UI ストーリー：production/qa/evidence/ を Glob し、このストーリーに対応する保存済み画像（*.png、*.jpg、*.gif）と [story-slug]-evidence.* を探します。

Config/Data ストーリー：production/qa/smoke-*.md（任意のスモークチェックレポート）を Glob します。

各ストーリーについて、見つかったファイルのパス、または見つからなかった場合の不足事項を記録します。

---

4. 自動テストの品質をレビューする（Logic／Integration）

見つかった各テストファイルを読み、評価します。

アサーションのカバレッジ

個別のアサーション数（assert、expect、 check、verify、またはエンジン固有のアサーションパターンを含む行の数）を数えます。アサーション数が少ないことは、品質上のシグナルです。テスト関数ごとのアサーションが1つだけのテストでは、期待される動作の範囲を網羅できていない可能性があります。

しきい値：

• テスト関数あたり3個以上のアサーション → 通常
• テスト関数あたり1〜2個のアサーション → カバレッジが不十分な可能性があるとして記録
• アサーションなし（テストは存在するが、assert がない） → BLOCKING としてフラグ（ストーリータイプのゲートレベル。qa.level: minimal の場合は ADVISORY）— テストは空虚に成功しており、何も証明していません

エッジケースのカバレッジ

数値、しきい値、または「X が発生した場合」という条件を含むストーリー内の各受け入れ基準について、テスト関数名またはテスト本体にその具体的なケースへの言及があるか確認します。

ヒューリスティック：

• テストファイルで「zero」、「max」、「null」、「empty」、「min」、「invalid」、「boundary」、「edge」を Grep します。いずれかがあれば、肯定的なシグナルです
• ストーリーに具体的な境界値を示す Formulas セクションがある場合：テストで最小値／最大値を少なくとも検証しているか確認します

命名の品質

テスト関数名は、シナリオと期待される結果を説明する必要があります。エンジンごとのパターン（.claude/rules/test-standards.md）：Godot は test_[scenario]_[expected]、Unity は [Scenario]_[Expected]、Unreal は <Project>.[System].[Scenario] です。

汎用的な名前の関数（test_1、test_run、testBasic など）は命名の問題としてフラグを付けます。こうした名前では、失敗の診断が難しくなります。

数式の追跡可能性

GDD に Formulas セクションがあるロジックストーリーの場合：テストファイルに、数式名または数式の値に言及する名前やコメントを持つテストが少なくとも1つ含まれているか確認します。数式を名前で言及せずに検証するテストは、数式が変更されたときに保守しにくくなります。

---

5. 手動で用意した証拠の品質を確認する（ビジュアル／操作感／UI）

見つかった各証拠ドキュメントを読み、以下のチェック項目を評価します。

UI ストーリーには証拠ドキュメントは必要ありません。 ドキュメントがない場合は、保持されたスクリーンショットが証拠となります。適用するのは、スクリーンショット／成果物の完全性（ストーリーによって変更される各画面の画像。Quit 後のタイトル画面など、基準が遷移のみを求める画面は、その画面自体の画像は不要です）と日付のカバレッジ（画像の日付）のみです。この2点を満たす UI ストーリーは ADEQUATE です。ドキュメントや基準との関連付け、承認がないことを理由に INCOMPLETE としてはいけません。

基準との関連付け

証拠ドキュメントでは、ストーリーの各受け入れ基準に言及する必要があります。確認事項：証拠ドキュメントには、各基準そのもの、または明確な言い換えが記載されていますか？基準が欠けている場合、その基準は一度も検証されていません。

承認の完全性

ストーリーを完了とする条件は、.claude/docs/coding-standards.md の証拠表に従います。これは、/story-done がすべての qa.level に適用するのと同じルールです。

• ビジュアル／操作感：証拠ドキュメント（テスト証拠テンプレートを使用）では、承認欄がすべて [x] Approved になっている必要があります。空欄または欄自体の欠落は INCOMPLETE です。
• UI：承認は不要です。保持されたスクリーンショットで完了とします。承認がある場合は記録します。承認がないことを理由に UI ストーリーを INCOMPLETE としてはいけません。

スクリーンショット／成果物の完全性

ビジュアル／操作感ストーリーの場合：production/qa/evidence/ を Glob し、このストーリーに属する保持画像（*.png、*.jpg、*.gif）があるか確認します。ビジュアルチェックについて記述していても画像が保持されていないドキュメントは INCOMPLETE です。デフォルトでは、このゲートは BLOCKING です。記述はアサーションであり、証拠ではありません。

UI ストーリーの場合：変更された各画面について、同様に保持されたスクリーンショットを求めます。ウォークスルーログは歓迎されますが、必須ではありません。

コードより古い証拠

保持画像がある各ストーリーについて、次を実行します。 bash .claude/scripts/review-receipts.sh check production/qa/evidence/[story-slug]/stamp.txt CHANGED: または GONE: の各ファイルを POTENTIALLY STALE として列挙します。証拠の取得後に変更されています。RECEIPT: NONE の場合は「スタンプなし」と伝え、以下の日付チェックを使用します。レポートに記載するだけで、ストーリーの判定は変わりません。

日付の網羅範囲

エビデンス文書には日付を記載する必要があります。その日付がストーリーの最後の大きな変更より前の場合（目安：スプリント計画のスプリント開始日と比較）、POTENTIALLY STALE としてフラグを付けてください。エビデンスが最終実装を網羅していない可能性があります。

---

6. レビューレポートを作成する

各ストーリーに判定を割り当てます。

判定	意味
ADEQUATE	テスト／エビデンスがあり、品質チェックに合格し、すべての基準を網羅しています
INCOMPLETE	テスト／エビデンスはありますが、品質面で不足があります（アサーションが不十分、承認が不足など）
MISSING	この qa.level でテストが必要なストーリーの種類について、テストもエビデンスも見つかりません
NOT ASSESSED	以下に示す理由により、このストーリーのレビューを実施できませんでした
WAIVED (qa.level: minimal)	qa.level: minimal でテストエビデンスがない Logic、Integration、Config/Data ストーリーです。テストは不要なため、不足とはみなさず、免除として記載します

NOT ASSESSED は必須であり、より軽い MISSING ではありません。 ほかの3つの判定は、いずれもレビューを実際に実施したことを前提とします。MISSING は「確認したが、何もなかった」という意味であり、実際に報告すべき問題です。「確認できなかった」という意味で使ってはいけません。それはストーリーについての所見ではありません。次の場合は NOT ASSESSED を使用してください。

• ストーリーの種類を判定できないため、必要なエビデンスが不明な場合（.claude/docs/coding-standards.md の種類→エビデンスの対応関係が、ほかの判定を意味のあるものにします）。
• エビデンスのパスは記載されているものの、読み取り不能またはこの実行の対象範囲外である場合。
• ストーリーファイル自体を解析できなかった場合。

ストーリーごとに、該当する理由を記載してください。 NOT ASSESSED だけでは、読者は対応できません。これを MISSING と区別する要点は、それぞれ必要な対応が異なることです。一方はテストの作成が必要で、もう一方はレビュアーへのアクセス権付与、またはストーリーの分類が必要です。

スプリント／システム全体の判定は、該当するストーリー判定のうち最も悪いものになります。また、NOT ASSESSED は ADEQUATE より優先されます。対象範囲の一部を評価できなかった実行では、その範囲が十分であると確認できていません。ただし、INCOMPLETE や MISSING より優先されることはありません。既知の問題は不明な問題より対応しやすく、実際の問題をアクセス上の問題より低く評価すると、問題が埋もれてしまうためです。WAIVED は ADEQUATE より下位です。対象範囲の全ストーリーが免除された場合に限り、全体の判定は WAIVED となり、それ以外の場合も、レポートには免除されたストーリーをすべて記載します。

これが重要な理由：エビデンスレビューはストーリーの完了を左右し、coding-standards.md では Logic、Integration、Visual/Feel、UI のエビデンスが BLOCKING とされています。「確認できなかった」を表す方法のない判定体系では、確認できていないものがすべて、ストーリーについての3つの断定のいずれかに押し込まれます。その結果、誰も検証していないストーリーに、誰かが検証したかのような判定が付いてしまいます。

## Test Evidence Review

> **Date**: [date]
> **Scope**: [single story path | Sprint [N] | [system name]]
> **Stories reviewed**: [N]
> **Overall verdict**: ADEQUATE / INCOMPLETE / MISSING / NOT ASSESSED / WAIVED
> **qa.level**: [minimal | standard | full] — **testing.strict**: [the resolved per-type values, or "unset — coding-standards.md defaults"]

---

### Story-by-Story Results

#### [Story Title] — [Type] — [ADEQUATE/INCOMPLETE/MISSING/NOT ASSESSED/WAIVED]

**Test/evidence path**: `[path]` (found) / (not found)

**Automated test quality** *(Logic/Integration only)*:
- Assertion coverage: [N per function on average] — [adequate / thin / none]
- Edge cases: [covered / partial / not found]
- Naming: [consistent / [N] generic names flagged]
- Formula traceability: [yes / no — formula names not referenced in tests]

**Manual evidence quality** *(Visual/Feel/UI only)*:
- Criterion linkage: [N/M criteria referenced]
- Lead sign-off: [✓ approved | ✗ missing | deferred — reason] *(Visual/Feel only; a UI story needs none)*
- Artefacts: [screenshots present / missing / N/A]
- Freshness: [dated [date] — current / potentially stale]

**Issues**:
- BLOCKING: [description] *(prevents story-done)*
- ADVISORY: [description] *(should fix before release)*

---

### Summary

| Story | Type | Verdict | Issues |
|-------|------|---------|--------|
| [title] | Logic | ADEQUATE | None |
| [title] | Integration | INCOMPLETE | Thin assertions (avg 1.2/function) |
| [title] | Visual/Feel | INCOMPLETE | Lead sign-off missing |
| [title] | Logic | MISSING | No test file found |
| [title] | Logic | WAIVED | No test — waived at `qa.level: minimal` |

**BLOCKING items** (must resolve before story can be closed): [N]
**ADVISORY items** (should address before release): [N]

---

7. 出力を記述する（任意）

会話内でレポートを提示します。

次のように尋ねます：「このテストエビデンスレビューを production/qa/evidence-review-[date].md に書き込んでもよろしいですか？」

これは任意です。レポートは単独でも役立ちます。ユーザーが永続的な記録を希望する場合にのみ書き込みます。

レポートの後に、次のように伝えます。

• BLOCKING 項目について：「これらは /story-done でストーリーを Complete にする前に解決する必要があります。今すぐ対応しますか？」
• アサーションが不十分な場合：「一般的なケース向けに、スキャフォールドされたアサーションのパターンを確認するには、/test-helpers [system] の実行を検討してください。」
• 承認が不足している場合：「[role] による手動承認が必要です。承認を完了するには、[evidence-path] を共有してください。」

判定：COMPLETE — エビデンスレビューが完了しました。BLOCKING 項目が見つかった場合は、CONCERNS を使用してください。

---

協調プロトコル

• 品質上の問題を報告し、修正しないでください — このスキルは読み取りと評価を行います。テストファイルやエビデンス文書は変更しません
• ADEQUATE は完璧という意味ではなく、リリースに十分という意味です — 機能しており、信頼できるだけの包括性を備えたテストに対する細かな指摘は避けてください
• BLOCKING と ADVISORY の区別は重要です — 不足によってストーリーの基準が実際に未検証のままになる場合に限り、BLOCKING として指摘してください
• 書き込む前に確認してください — レポートファイルは任意です。書き込む前に必ず確認してください