story-readiness

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

上記で解決済みのため、そのまま使用します。--review は review_mode を上書きします。ブロックがない場合は → .claude/docs/config-resolution.md の既定値を使用します。

質問ツールで質問してください。質問ツールがない場合は、選択肢に番号を付けて列挙し、ユーザーの回答を待つために応答を終了してください。スキップされた質問や閉じられた質問は回答ではありません。プレーンテキストでもう一度質問してください。

ストーリーの準備状況

コードを書き始める前に、開発者が必要とするすべての情報がストーリーファイルに記載されているかを確認します。 実装中に設計上の疑問が生じないこと、推測に頼らないこと、受け入れ基準が曖昧でないことを確認します。

読み取り専用です。 ファイルへの書き込みや編集は行いません。確認結果を報告し、修正案を会話内で作成することを提案します。

判定結果はストーリーごとに1つです。以下の順に、最初に該当したものを採用します。

1. BLOCKED：読み手が解消できる問題が見つかりました。参照先の ADR が存在しない、Proposed、Deprecated、または Superseded である、依存するストーリーが存在しないか Draft である、または基準に担当者のいない未解決の設計上の疑問が含まれています。
2. NEEDS WORK：必須チェック項目が不合格です。ストーリーは今すぐ修正できます。
3. NOT ASSESSED：ストーリーを評価できませんでした。ファイルが読み取れない、参照先の ADR に読み取り可能な ## Status がない、または指定された設計ドキュメントが見つかりません。読み取れなかったものを明記してください。READY にはなりません。確認できなかったストーリーは、準備完了と判断できないためです。既知のブロッカーは未知の問題より有用なため、上記2つの失敗判定より優先順位は低くなります。
4. READY：すべての項目に合格している、理由付きで N/A である、または助言事項です。助言事項に関する不足も引き続き一覧に含めます。

質問は .claude/docs/automation-modes.md に従います（collaborative は必ず質問し、guided は主要な選択肢について質問し、autonomous は記録して先に進みます。automation_always_ask のカテゴリは必ず質問します）。

フェーズ 1：対象範囲

対象範囲は、スキル名の後に入力されたテキストから、--review <mode> の組を取り除いたものです。残りは1つの値です。パスにはスペースを含めることができます。何も入力されていない場合は、ユーザーの依頼で指定されたストーリー、エピック、またはスプリントが対象範囲です。

• ストーリーパス：そのストーリー。
• sprint：現在のスプリントに記載されているストーリー（フェーズ2で読み取ります）。
• all：production/epics/ 以下のすべての story-*.md。
• エピック（スラッグまたはフォルダー）：そのフォルダー内の story-*.md ファイル。
• 未指定：次のように質問します。「何を確認しますか？」選択肢：特定のストーリーファイル / 現在のスプリント内のすべてのストーリー / production/epics/ 内のすべてのストーリー / 1つのエピックのストーリー。

対象範囲内のストーリーが0件の場合：NOT ASSESSED — 対象範囲にストーリーがありません として停止します。 対象範囲と、空だったパスを明記し、/create-stories に案内してください（standard および full の場合は、先に /create-epics）。空の一覧に対して Ready: 0 / Needs Work: 0 という概要を決して出力しないでください。問題なく完了したように見えてしまいます。sprint の場合は、「スプリント計画が見つからない」と「スプリント計画にストーリーが記載されていない」は別の報告です。どちらなのか明記してください。

続行する前に、「[N] 件のストーリーファイルを確認します。」と伝えてください。

フェーズ 2：実行中に一度だけ読み取る事実

1. ストーリー。 上記で解決した story_granularity を使って、対象範囲に対してストーリーヘルパーを実行します。

   bash .claude/scripts/story-facts.sh --lint --granularity <story_granularity> [--sprint | --all | <path> ...]
   

   各 STORY 行には、ストーリーのステータス、タイプ、レイヤー、見積もり、TR-ID、ADR、受け入れ条件の数、テストエビデンスの行、依存関係が記載されています。各 LINT 行は、そのストーリーに抵触するルールです。行は観察結果であり、判定はあなたが行います。終了コード 3 は、ファイルが見つからなかったことを意味します。NOT_FOUND 行がある場合、各行にはスプリントの file: エントリー、またはファイルではないパスが示されます。それぞれを見つからないストーリーとして報告し、残りも確認してください。NOT_FOUND 行がなく、--sprint が指定されている場合は、production/sprint-status.yaml がありません。「スプリント計画が見つかりません」と報告してください。各ストーリーファイルも読んでください。以下のテスト可能性、範囲、アセットの項目では、その記述内容が必要です。
2. ADR。 1 回の呼び出しで、すべての ADR のステータスとレイヤーを取得します。 bash .claude/scripts/adr-status.sh。no_status または UNFILLED のステータスは、不正な ADR を示します。ステータスがないことを失敗として扱ってはいけません（対応先： /architecture-decision retrofit [file]）。ストーリーが参照している ADR に行がない場合、その ADR は見つかりません。
3. コントロールマニフェスト。 docs/architecture/control-manifest.md の Manifest Version 行だけを確認します。ファイルがない場合は、1 回だけ記載してください。
4. TR レジストリ。 各ストーリーの TR-ID とその status を、docs/architecture/tr-registry.yaml で確認します。ファイルがない場合は、1 回だけ記載してください。その場合、すべてのストーリーで TR-ID 項目は合格となります。
5. スプリント優先度（sprint の対象範囲）：production/sprints/ にある最新の計画から、どのストーリーが Must Have で、どのストーリーが Should Have かを確認します。

ストーリーごとのティア。 workflow はストーリーごとに解決します。そのストーリーのシステムに対応する system_overrides の行（GDD: パスの GDD ファイル名の先頭部分。GDD パスがない場合に限り、TR-[system]-NNN ID の [system]）を使い、それがなければプロジェクトの値を使います。同じ実行内でも、ストーリーごとに異なるティアになることがあります。

フェーズ 3：チェックリスト

各ストーリーについて、すべての項目を確認します。どのグループがブロッカーになるかは、ティアによって決まります。

グループ	full	standard	minimal
設計の完全性	ブロッカー	ブロッカー	ブロッカー。GDD の代わりに design/game-brief.md を使用
アーキテクチャの完全性	ブロッカー	ADR ステータス項目はブロッカー。それ以外は、クリティカルな ADR に関するものを除き、参考項目	N/A。ただし ADR ステータス項目を除く
スコープの明確さ	ブロッカー	ブロッカー	ブロッカー。ただし Estimate は参考項目（規模を見積もるスプリント計画がないため）
未解決の質問	ブロッカー	ブロッカー	ブロッカー
アセット参照	ブロッカー	ブロッカー	ブロッカー
完了の定義	ブロッカー	ブロッカー	ブロッカー。テストエビデンス項目は qa.level に従う

不合格となった参考項目は、修正方法とともに Gaps の下に記載します。それだけで READY を下げてはいけません。

設計の完全性

• 要件へのトレース：ストーリーに design/gdd/ ファイルが記載され、そのファイル名だけでなく、具体的なルールまたは基準が引用またはリンクされています。minimal の場合：design/game-brief.md と、ストーリーが実装する MVP 機能を記載します。記載された設計ドキュメントが存在しない場合：未評価（NOT ASSESSED）。
• 自己完結性：受け入れ条件には、GDD を開かなくても完了の定義が記載されています。
• テスト可能性：各基準は具体的で、観察可能な条件です。「ジャンプのメカニクスを実装する」は不可。「押し続けると、0.3 秒以内に 5 単位の高さまでジャンプする」は可です。単体テストで設定できる基準は（どのような入力値でも）、リリース時のデータでそのケースに到達しない場合でも、テスト可能です。
• 判断の余地がないこと：「反応がよい」「見た目がよい」は、Logic、Integration、UI、Config/Data では不合格です。Visual/Feel では、このような基準が想定されています。production/qa/evidence/[slug]-evidence.md のようなエビデンスファイルが基準に記載されていれば合格、記載がなければ NEEDS WORK です。

アーキテクチャの完全性

• ADR のステータス：すべての階層で、ストーリーが参照する各 ADR を Phase 2 の表で確認します。
  • Accepted：合格です。
  • Proposed：BLOCKED です。修正方法：BLOCKED: ADR-NNNN is Proposed — accept it with /architecture-decision accept ADR-NNNN once decided。
  • Deprecated または Superseded：BLOCKED です。修正方法：BLOCKED: ADR-NNNN is [status] — point the story at [successor] (edit its ADR field; /create-stories never rewrites an existing story)。
  • 該当する ADR ファイルがない：BLOCKED です。
  • ステータスを読み取れない：この項目は NOT ASSESSED とし、ファイル名を記載します。 standard では、critical な ADR（layer が Foundation、または未指定）が存在しないか Proposed の場合はブロックされます。それ以外の ADR については、以下の項目は参考情報です。
• ADR の記載、または N/A の明記：ADR、または理由を添えた明示的な N/A（ADR: N/A — [reason]、または N/A (minimal — no ADRs)）が必要です。空欄は不合格です。
• TR-ID が有効：各 TR-[system]-NNN がレジストリに存在し、status: active であること。deprecated または superseded-by（引用符の有無は問いません）の場合：NEEDS WORK。修正方法：ストーリーが現在の要件を参照するようにします。レジストリに存在しない場合：NEEDS WORK（ストーリーが登録前に作成されたか、レジストリに /architecture-review が必要な可能性があります）。TR-ID がない場合、またはレジストリがない場合は合格です。
• Manifest Version が最新：ストーリーの Manifest Version をマニフェストのものと照合します。古い場合、以降に追加されたルールが適用される可能性があるため、ギャップとなります。新しいルールが無関係に見えても、ギャップとして扱います。変更点を記載し、判断はユーザーに委ねます。full では、新しいルールの適用範囲にかかわらず NEEDS WORK です。standard では参考情報です。修正には次の 3 つの手順すべてが必要です：「ストーリーの日付以降に追加されたマニフェストのルールを確認し、該当するルールがあればストーリーを更新し、その後 Manifest Version を [current date] に設定します。」Manifest Version フィールドがない場合、またはマニフェストがない場合は合格です。
• エンジンに関する注記：ストーリーが扱うカットオフ後のエンジン API について、注記または検証手順があるか、ストーリーに「N/A — no engine API involved」と記載されていること。
• マニフェストのルールを記載：そのレイヤーのルールが列挙されているか、「N/A — manifest not yet created」と記載されていること。マニフェストがない場合は合格です。

スコープの明確さ

• 見積もり：時間、ポイント、または T シャツサイズが記載されていること。unfilled Estimate（テンプレートの角括弧がそのまま残っている状態）は不合格です。minimal では参考情報です。
• 対象外の明記：Out of Scope セクション、または境界が明確になる文言があること。
• 依存関係の列挙：このストーリーが必要とする各ストーリー、または「None」の記載があること。

未解決の質問

• 未解決マーカーがない：marker 行（単語全体が大文字の TBD、TODO、UNRESOLVED）がないこと。? はマーカーではありません。crit ? 2 : 1 のような式は合格です。受け入れ条件が未解決の質問として記述されている場合は、Testable で不合格になります。
• 依存ストーリーが存在し、Draft ではない：依存ストーリーが存在しない場合、または Draft の場合、ストーリーは BLOCKED になります。Story NNN は同じエピックフォルダー内のその番号のストーリーを指し、パスが記載されている場合はそのファイルを明確に指します。

アセット参照

• ストーリーが使用するアセットが存在する：ストーリーが読み取る、または基にする assets/ 配下のパス、あるいは .png、.jpg、.svg、.wav、.ogg、.mp3、.glb、.gltf、.tres、.tscn、.res のいずれかの拡張子を持つパスが対象です。ストーリーが作成すると記載しているファイル（新しいシーン、新しいデータファイルなど）は確認対象外です。見つからない場合：NEEDS WORK。パスを記載します。「Referenced assets verified: [N] found」または「No asset references」と報告します。存在のみを確認します。

完了の定義

• 受け入れ条件が十分にある：ac_below_min の行がありません。最小数は /create-stories が書き込む story_granularity に従います。

  story_granularity	ロジック、インテグレーション	ビジュアル／操作感、UI	設定／データ
  coarse	3	2	1
  balanced	2	2	1
  fine	1	1	1

• パフォーマンスへの言及がある：ゲームプレイループ、レンダリング、または物理に関わるストーリーでは、予算を明記するか、「パフォーマンスへの影響は想定されない — [理由]」と記載します。

• タイプが宣言されている：type_missing または type_unknown の行がありません。修正方法：ヘッダーに Type: [Logic|Integration|Visual/Feel|UI|Config/Data] を追加します。

• テストの証跡が明確である：証跡の格納先を示す ## Test Evidence セクションがあります。Logic と Integration はテストファイル、UI は production/qa/evidence/ 内の各画面の保存済みスクリーンショット、Visual/Feel はそれに加えて production/qa/evidence/[story-slug]-evidence.md が必要です。

  • qa.level: minimal の場合、Logic、Integration、Config/Data は合格扱いとなり、テストは免除されます。不足項目は記載せず、テストファイル、tests/ フォルダー、テストランナーの不足についての注記も加えません。UI と Visual/Feel は引き続き確認対象となり、すべてのレベルでスクリーンショットが必要です。
  • それ以外の場合、上記の gate_level 行でストーリーのタイプごとのレベルが設定されます。blocking：セクションがない場合は NEEDS WORK です。advisory：不足項目としてのみ記載します。修正方法：ストーリーのタイプに応じた証跡の格納先を記載した ## Test Evidence を追加します。

Phase 4：判定

各ストーリーに対して、冒頭に記載された順序で適用します。BLOCKED のストーリーに NEEDS WORK の項目がある場合は、両方を記載します。

Phase 5：QA リードレビュー

上記の review_gate 行を確認します。skill-gates=skip（solo または lean）の場合はスキップし、返信に「QL-STORY-READY skipped — [Solo | Lean] mode」と記載します。skill-gates=run の場合は、references/qa-lead-gate.md と .claude/docs/director-gates.md を読み、報告前に実行します。スキップする場合は、これらを読み込まないでください。

Phase 6：報告して終了

ストーリーが1つの場合：

## Story Readiness: [story title]
File: [path]
Verdict: [READY / NEEDS WORK / BLOCKED / NOT ASSESSED]

### Passing Checks (N/[total])
Design Completeness: [passing items]
Architecture Completeness: [passing items, or "N/A at minimal (ADR status checked)"]
Scope Clarity: [passing items]
Open Questions: [passing items]
Asset References: [passing items, or "no asset references"]
Definition of Done: [passing items]

### Gaps
- [Checklist item]: [what is missing or wrong]
  Fix: [the text that resolves it]

### Blockers (if BLOCKED)
- [What blocks]: [the story, ADR or question that must clear first]

毎回、6つすべてのグループを正確にこの名前で記載します。合格項目がないグループには、確認したことがわかるように「none — see Gaps」と記載します。

Gaps には不合格のチェックリスト項目のみを記載します。合格または N/A の項目や、チェックリスト外の所見（スプリントのステータス、別のドキュメントなど）は記載しません。

ストーリーが複数ある場合：まず要約を記載し、その後、READY ではない各ストーリーについて1ストーリー用のブロックを記載します。

## Story Readiness Summary — [scope] — [date]
Ready: [N] · Needs Work: [N] · Blocked: [N] · Not Assessed: [N]

Ready: [title] ([path]), ...
Needs Work: [title]: [main gap]
Blocked: [title]: blocked by [story, ADR or question]
Not Assessed: [title]: [what could not be read]

sprint のスコープで、Must Have のストーリーが READY ではない場合は、最初に次の文を記載します。 WARNING: [N] Must Have stories are not ready to implement: [each with its main gap]. Fix them before the sprint starts, or replan with /sprint-plan update.

次に、ストーリーが1つの場合： ほかに着手できるストーリーを探します。production/sprints/ 内の最新の計画から、Ready または Not Started で、対象のストーリーではなく、未完了の依存関係を待っておらず、Must Have または Should Have に該当するものを最大3件見つけます。それぞれについて、1行の説明と見積もりを記載します。該当するものがない場合は、次のいずれかを記載します。 Next ready stories: no sprint file found または Next ready stories: none ready in [sprint]

サポートを提案します。 「これらのストーリーの不足部分を作成しましょうか？」と尋ねます。選択肢：はい、作成してください / いいえ、以上です。はいの場合は、会話内で不足部分のみを作成します。それらを記載するのはユーザーまたは /create-stories です。

リダイレクト：

• ストーリーファイルがない場合：/create-stories [epic-slug] を実行します（standard と full では、先に /create-epics を実行します）。
• デザイン参照がなく、変更が小規模（約1週間未満）の場合：/quick-design [description] を実行し、その仕様をストーリー内で参照します。
• スコープが見積もりを超えて拡大した場合：ストーリーを分割するか、プロデューサーに相談します。

返信の最後に次を記載します：

Review: [QL-STORY-READY skipped — Solo mode | skipped — Lean mode | its verdict]
Next ready stories: [up to 3 | no sprint file found | none ready in [sprint]]   (one-story scope)
Next step: [/dev-story [path] when READY | fix the gaps above, then /story-readiness [path]]
Files changed: none