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. 受阻：读者可以解决的问题。引用的 ADR 缺失、状态为 Proposed、Deprecated 或 Superseded；依赖的故事缺失或状态为 Draft；或者某项标准包含尚无负责人解决的未解决设计问题。
2. 需要修改：某项阻断性检查未通过。现在可以修复该故事。
3. 未评估：无法评估该故事。文件无法读取；引用的 ADR 没有可读取的 ## Status；或找不到故事所指的设计文档。请指出无法读取的内容。此结果绝不会是“就绪”：无人能检查的故事尚未被证明已就绪。它的优先级低于前两种失败情况，因为已知的阻碍比未知情况更有用。
4. 就绪：每项均通过、说明原因后标为不适用，或属于建议项。仍会列出建议项中的缺漏。

提问方式遵循 .claude/docs/automation-modes.md（协作模式始终提问，引导模式在重大选择时提问，自主模式记录并继续；automation_always_ask 类别始终提问）。

阶段 1：范围

范围是技能名称之后输入的文本，移除任何 --review <mode> 参数对之后的剩余内容。剩余内容是一个值；路径可以包含空格。如果没有输入内容，范围就是用户请求中提到的故事、史诗或冲刺。

• 故事路径：该故事。
• sprint：当前冲刺列出的故事（阶段 2 会读取这些故事）。
• all：production/epics/ 下的所有 story-*.md。
• 史诗（slug 或其文件夹）：该文件夹中的 story-*.md 文件。
• 空白：提问：“你想检查什么？”选项：某个故事文件 / 当前冲刺中的所有故事 / production/epics/ 中的所有故事 / 某个史诗的故事。

范围内故事数为零：停止并报告 NOT ASSESSED — no stories in scope。 请指出范围和内容为空的路径，并引导至 /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 行，每行都指向一个 sprint file: 条目或一个并非文件的路径：请将每个都报告为缺失的故事，并检查其余内容。如果没有 NOT_FOUND 行且指定了 --sprint，则表示不存在 production/sprint-status.yaml：报告“未找到 sprint 计划”。也要读取每个故事文件：下文的可测试性、范围和资源条目需要依据其中的文字。
2. ADR。 一次调用即可获取每个 ADR 的状态和层级： bash .claude/scripts/adr-status.sh。no_status 或 UNFILLED 状态表示 ADR 格式错误：绝不能将缺少状态视为失败状态（路由： /architecture-decision retrofit [file]）。故事引用了但没有对应行的 ADR 即为缺失。
3. 控制清单。 只读取 docs/architecture/control-manifest.md 中的 Manifest Version 行。文件缺失：记录一次即可。
4. TR 注册表。 在 docs/architecture/tr-registry.yaml 中查找每个故事的 TR-ID 及其 status。文件缺失：记录一次即可；所有故事的 TR-ID 项均视为通过。
5. Sprint 优先级（sprint 范围）：查看 production/sprints/ 中最新计划里哪些故事为 Must Have，哪些为 Should Have。

每个故事的层级。 workflow 按故事解析：使用该故事所属系统的 system_overrides 行（即其 GDD: 路径中的 GDD 文件名主干；仅当没有 GDD 路径时，才使用 TR-[system]-NNN ID 中的 [system]），否则使用项目值。一次运行中的故事可以处于不同层级。

阶段 3：检查清单

检查每个故事的每个项目。层级决定哪些组会阻止通过：

组	full	standard	minimal
设计完整性	阻止通过	阻止通过	阻止通过；design/game-brief.md 代替 GDD
架构完整性	阻止通过	ADR 状态项阻止通过；其余项仅供参考，除非涉及关键 ADR	N/A，ADR 状态项除外
范围明确性	阻止通过	阻止通过	阻止通过，但估算项仅供参考（没有 sprint 计划可供估算）
未决问题	阻止通过	阻止通过	阻止通过
资源引用	阻止通过	阻止通过	阻止通过
完成定义	阻止通过	阻止通过	阻止通过；测试证据项遵循 qa.level

未通过的参考项会连同修复方法列在 Gaps 下，且本身绝不会降低 READY。

设计完整性

• 需求可追溯：故事指出其 design/gdd/ 文件，并引用或链接其中一条具体规则或标准，而不只是文件名。对于 minimal：需指出 design/game-brief.md 以及故事所实现的 MVP 功能。指定的设计文档不存在：未评估。
• 内容自包含：验收标准说明了完成的含义，无需打开 GDD。
• 可测试：每条标准都是具体、可观察的条件。反例：“实现跳跃机制。”正例：“按住时，跳跃在 0.3 秒内达到 5 个单位。”只要单元测试能够设置某条标准（任意输入值），该标准就是可测试的，即使已发布的数据永远不会触及该情况。
• 无主观判断：“感觉灵敏”或“看起来不错”对于 Logic、Integration、UI 和 Config/Data 均不合格。Visual/Feel 类标准预期会出现此类表述：标准指定了证据文件（例如 production/qa/evidence/[slug]-evidence.md）时判定为通过；未指定时判定为 NEEDS WORK。

架构完整性

• ADR 状态，适用于每个层级：根据 Phase 2 表格，检查说明中引用的每个 ADR。
  • Accepted：通过。
  • Proposed：受阻。修复方法：BLOCKED: ADR-NNNN is Proposed — accept it with /architecture-decision accept ADR-NNNN once decided。
  • Deprecated 或 Superseded：受阻。修复方法：BLOCKED: ADR-NNNN is [status] — point the story at [successor] (edit its ADR field; /create-stories never rewrites an existing story)。
  • 不存在此类 ADR 文件：受阻。
  • 状态无法读取：此项未评估；注明文件名。 在 standard 级别，缺失或处于 Proposed 状态的关键 ADR（其 layer 为 Foundation 或缺失）会导致受阻；对于其他 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（是否加引号均可）：需要处理，修复方法：将说明指向当前需求。不在注册表中：需要处理（该说明可能早于注册表，也可能需要运行 /architecture-review 更新注册表）。没有 TR-ID 或没有注册表时通过。
• Manifest Version 为最新版本：将说明中的 Manifest Version 与清单中的版本进行比对。较旧的版本意味着存在差距，因为此后添加的规则可能适用。即使新规则看似无关，仍需标记为差距：说明发生了哪些变化，并将是否处理留给用户。在 full 级别，无论新规则涉及什么，都需要处理；在 standard 级别，仅供参考。修复方法，按以下三个步骤全部完成：“Review the manifest rules added since [story's date]; update the story's rules if any apply; then set its Manifest Version to [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 状态的依赖说明会导致此说明受阻。Story NNN 表示同一 epic 文件夹中的该编号说明；路径则唯一指定一个说明。

资源引用

• 说明使用的资源均存在：检查说明读取或基于其构建的 assets/ 下的路径，或扩展名为 .png、.jpg、.svg、.wav、.ogg、.mp3、.glb、.gltf、.tres、.tscn 或 .res 的文件。说明中注明将创建的文件（例如新场景、新数据文件）无需检查。缺失：需要处理；注明路径。报告“Referenced assets verified: [N] found”或“No asset references”。仅检查是否存在。

完成定义

• 验收标准充足：没有 ac_below_min 行。最低数量根据 story_granularity 确定，因为 /create-stories 会写入该值：

  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：汇报并结束

一个故事：

## 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]

每次都要用以下确切名称列出全部六组。没有通过项的组要写“none — see Gaps”，让读者知道该组已检查。

Gaps 只列出未通过的检查项：不要列出通过或 N/A 的项目，也不要列出检查清单以外的观察（例如 sprint 状态、其他文档）。

多个故事：先给出摘要，然后为每个非 READY 故事提供单个故事的区块。

## 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.

然后，对于一个故事： 查找其他可以开始的故事。在 production/sprints/ 中最新的计划里，最多找出 3 个符合以下条件的故事：Ready 或 Not Started；不是当前故事；没有待完成的依赖项；优先级为 Must Have 或 Should Have。每个故事都要列出一行描述和估算值。如果没有符合条件的故事，请说明是哪种情况： Next ready stories: no sprint file found 或 Next ready stories: none ready in [sprint]。

提供帮助。 询问：“Would you like me to draft the missing parts for any of these stories?” 选项：Yes, draft them / No, that's all。用户选 Yes 时，只在对话中起草缺少的部分。由用户或 /create-stories 写入。

重定向：

• 故事文件缺失：运行 /create-stories [epic-slug]（在 standard 和 full 模式下，先运行 /create-epics）。
• 没有设计参考且改动较小（约一周以内）：运行 /quick-design [description]，并在故事中引用该规范。
• 范围超出估算：拆分故事，或向 producer 提出。

以以下内容结束回复：

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