create-stories

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

上方已解析——直接使用；--review 会覆盖 review_mode。不阻止 → 默认值见 .claude/docs/config-resolution.md。

使用问题工具提问。没有问题工具时，列出带编号的选项并结束当前轮次 等待回答。跳过或关闭的问题不算回答：请改用纯文本再次提问。

创建故事

一个故事是一种可实现的行为：规模符合 story_granularity 的设定， 内容独立完整，并关联到一项需求及其依据的决策。每个史诗执行一次此技能， 并按依赖顺序进行：先是基础史诗，然后是核心、功能、呈现。

写入： production/epics/[epic-slug]/story-NNN-[slug].md、该史诗的 EPIC.md Stories 表，以及 production/epics/index.md 中对应的行。 下一步： workflow: minimal 时运行 /dev-story [story-path]；否则运行 /story-readiness [story-path]，然后运行 /dev-story。

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

清单（复制后逐项勾选）：

- [ ] Phase 1: epic found, tier resolved
- [ ] Phase 2: inputs loaded, each ADR's status reported
- [ ] Phase 3-4: stories drafted, typed, Ready or Blocked
- [ ] Phase 5: QA lead review run, or its skip noted
- [ ] Phase 6: story list shown, one ask to write
- [ ] Phase 7: stories, EPIC.md and index.md written (or index absence said)
- [ ] Phase 8: next step asked, closing block printed

阶段 1：史诗和设置

层级。 使用该史诗系统的 workflow：如果存在适用于该史诗 slug（其 GDD 系统）的 system_overrides 行，则使用该行；否则使用项目值。

story_granularity 决定每个故事的验收标准数量。对标准进行分组或拆分， 以符合设定：

story_granularity	每个故事的 AC 数量	大小
coarse（默认值，rigor: minimal）	5-10	一个完整功能，需要数天
balanced（rigor: standard）	2-4	一个任务，约一个工作时段
fine	1	一个标准；故事名称重述该标准

docs.density 决定每个故事说明文字的详尽程度（背景、实现说明、ADR 摘要）， 但不影响 AC 数量或 AC 文本：terse（默认值）＝项目符号说明，无前言； balanced＝简短的背景段落加说明；thorough＝完整背景、指导和 ADR 理由。 TR-ID、ADR Version 和验收标准绝不精简。

要处理哪个史诗。 技能名称后输入的文本，移除任何 --review <mode> 参数对后剩余的内容：史诗 slug（combat）或路径（production/epics/combat/EPIC.md）。 若未输入内容，则用户请求中提到的史诗（“战利品史诗”）视为已指定。

• 已指定，但该位置没有 EPIC.md： 在 standard 和 full 层级下停止，并提示：“在 production/epics/[slug]/EPIC.md 找不到史诗。运行 /create-epics 来创建，或使用 ls production/epics/ 检查 slug。”绝不可凭猜测拆分。在 minimal 层级下， 说明该层级不需要 /create-epics 史诗，采用阶段 2 的 minimal 分支，并指出所用的 slug。
• 未指定，且为 minimal： 采用阶段 2 的 minimal 分支。
• 未指定，且为 standard 或 full： 列出 production/epics/*/EPIC.md， 并注明每个史诗的状态，然后询问：“你想将哪个史诗拆分为故事？”每个史诗提供一个选项。 未找到史诗： 停止并提示：“在 production/epics/ 下未找到史诗。请先运行 /create-epics layer: foundation。”绝不可在没有选项时提问。

阶段 2：加载输入

minimal：根据简介构建史诗

1. 没有 design/game-brief.md： 停止。“目前还没有可据以构建故事的简介：请先运行 /brainstorm；它会编写一页简介。”如果代码根目录中已有游戏（10 个或更多源文件），则改为指定 /reverse-document design [code root]。
2. 完整阅读 design/game-brief.md（一页）。
3. 史诗。 <slug> 是简介中的暂定标题，经 slug 化处理（如果没有标题，则使用 mvp），或者是用户指定的史诗。
   • 如果 production/epics/<slug>/EPIC.md 已存在：它就是该史诗。依据其范围，并始终追溯至简介；绝不重写。
   • 如果不存在：仅在第 6 阶段的询问确认史诗名称后，才在第 7 阶段起草。目标 = 简介中的一句话推介；范围 = 其 MVP 功能列表；顺序 = 其构建顺序。保持简洁。
   • 如果文件夹中已有故事（再次访问）：绝不重写现有的 story-*.md。只为简介中尚未涵盖的项目或用户指定的新项目添加故事，并从最高的现有 story-NNN 继续编号。
4. 每个 MVP 功能对应一个故事，并按构建顺序排列，每个故事都要追溯至简介。没有故事会因 ADR 而受阻：此层级没有 ADR。

在 minimal 下，不读取 GDD、控制清单、TR 注册表或 ADR。前往第 3 阶段。

standard 和 full：史诗及其约束依据

1. 史诗： 完整读取 production/epics/[epic-slug]/EPIC.md（其中的层级、GDD、约束性 ADR，以及包含 TR-ID 的 GDD 需求表）。
2. GDD： 按标题读取相关章节，绝不读取整个文件： bash .claude/scripts/md-section.sh extract design/gdd/[file].md "Acceptance Criteria"，并对 Formulas、Edge Cases 和 Detailed Design 执行相同操作（退出码为 3 时，尝试 Detailed Rules；这是设计标准中同一章节的名称）；在 full 下也要读取其他必需章节（list 会显示标题）。
3. 控制清单： 仅读取史诗对应的层级，以及版本： bash .claude/scripts/md-section.sh extract docs/architecture/control-manifest.md "[Layer] Layer Rules"， 另加其 Manifest Version 行。
4. TR 注册表： 仅读取本系统的条目：在 docs/architecture/tr-registry.yaml 中，查找匹配 system: <slug>\s*$ 的行，并读取每个条目上方的 id 和下方的文本。锚点可避免 combat 匹配到 combat-ai；\s* 可匹配 Windows 换行符。
5. ADR： 读取史诗中提到的所有 ADR（包括约束性 ADR，以及需求表中列出的 ADR，也包括 Proposed 状态的 ADR），通过一次调用完成：

   bash .claude/scripts/adr-status.sh ADR-0001 ADR-0003 ...
   

   每行包含状态、层级、version（故事中的 ADR Version 印章）、depends_on 和缺失章节。然后仅使用 md-section.sh extract 读取每个 ADR 的 Summary、Decision（包括其中的 Implementation Guidelines）和 Engine Compatibility。Engine Notes 是故事中的一个字段，取自 Engine Compatibility，并非 ADR 章节。如果 ADR 没有上述任何章节，说明它早于模板；完整读取一次，并标记为需要运行 /architecture-decision retrofit [file]。

缺少文件的具名 ADR（NOT_FOUND）：

• full：在拆分任何故事之前停止。
• standard：仅当其为关键 ADR（Foundation 层）时停止；否则发出警告，继续执行，并将其约束的故事标记为 Blocked，直到该 ADR 存在。
• 停止时：“史诗引用了 [ADR-NNNN: title]，但在 docs/architecture/ 中找不到对应文件。请检查史诗的 Governing ADRs 列表，或运行 /architecture-decision 创建该文件。引用的 ADR 文件存在之前，无法创建故事。”

起草前先报告实际状态，并逐一列出每个 ADR 及其状态：

Loaded: epic [name] · GDD [file] · manifest v[date], [layer] rules
ADRs: ADR-0001 Accepted · ADR-0002 Accepted · ADR-0003 Accepted · ADR-0004 Proposed · [ADR-NNNN missing]

缺少文件时，绝不要说“全部存在”；没有清单版本时，绝不要报出清单版本。

阶段 3：为每个故事确定类型

类型	当其标准涉及
逻辑	公式、阈值、状态转换、AI 决策、计算
集成	两个或更多系统、跨边界的信号、保存/加载往返
视觉/手感	动画、VFX、“响应灵敏的感觉”、时序、屏幕震动、音频同步
UI	菜单、HUD、按钮、屏幕、对话框、工具提示
配置/数据	仅平衡数值和数据文件，不包含新逻辑

混合型故事采用实现风险最高的类型。类型决定 /story-done 需要哪些证据。

阶段 4：起草故事

将需要相同核心实现的需求归为一个故事，遵循 story_granularity 的要求。排序：先处理基础行为，再处理边缘情况，最后处理 UI。对于每个故事：

• 需求： 登记表中的 TR-ID，通过 Epic 的 GDD Requirements 表进行匹配。只有在没有匹配项时，才写 TR-[system]-??? 并说明这一点。
• ADR： 规定如何实现的 ADR（需求表会列出它）。
  • Accepted：将其纳入故事。
  • Proposed：Status: Blocked，并写明“BLOCKED: ADR-NNNN is Proposed — accept it with /architecture-decision accept ADR-NNNN once decided”。
  • Deprecated 或 Superseded：Status: Blocked，并写明“BLOCKED: ADR-NNNN is [status] — point the story at [successor] (edit its ADR field; /create-stories never rewrites an existing story) before implementing”。
  • Accepted ADR 的 depends_on 中列出的 ADR 若并非 Accepted：以相同方式阻止，注明该 ADR。
  • 适用多个 ADR：全部列出，最直接的放在最前。
  • 没有适用的 ADR：ADR: N/A — [reason]，例如“纯数据配置”。绝不能留空：留空表示尚未检查。
• ADR Version： 故事的 ADR Version 取 ADR 的 ## Last Verified 日期；若没有，则取其 ## Date；若仍没有，则取 unversioned（version 列）。只要此值与 ADR 相符，/dev-story 就会信任故事中的 ADR 摘要。
• 引擎风险： 取自 ADR 的 Engine Compatibility（其知识风险）。
• 估算： 根据标准和故事涉及的文件，提出一个 T 恤尺码：S（几小时）、M（约一天）或 L（几天）。这只是建议：阶段 6 会展示，用户可以修改。若故事的 Estimate 仍为模板中的方括号占位符，/story-readiness 会判定失败，因此绝不能留着它。

阶段 5：QA 负责人审核

阅读上方的 review_gate 行。skill-gates=skip（单人或精简模式）：不进行审核；在阶段 6 列表和收尾区块中注明“QL-STORY-READY skipped — [Solo | Lean] mode”。skill-gates=run：阅读 references/qa-lead-gate.md 和 .claude/docs/director-gates.md，并在阶段 6 提问前立即执行。跳过时，不要加载这些文件。

阶段 6：展示故事，只询问一次

## Stories for Epic: [name]
ADRs: ADR-0001 Accepted · ADR-0002 Accepted · ADR-0004 Proposed   (every ADR, from Phase 2)

Story 001: [title] — Logic — ADR-0001 — Ready — Estimate M
  Covers: TR-[system]-001 ([one-line requirement])
  Test required: tests/unit/[system]/[slug]_test.[ext]

Story 002: [title] — Integration — ADR-0004 — BLOCKED (ADR-0004 is Proposed) — Estimate L
  Covers: TR-[system]-002, TR-[system]-003
  Test required: tests/integration/[system]/[slug]_test.[ext]

Story 003: [title] — Visual/Feel — ADR-0001 — Ready — Estimate S
  Covers: TR-[system]-004
  Evidence required: retained screenshot + sign-off in production/qa/evidence/[slug]-evidence.md

[N stories: N Logic, N Integration, N Visual/Feel, N UI, N Config/Data; N Blocked]
QL-STORY-READY: [skipped — Solo mode | its verdicts]

在 minimal 模式下，每行都对应 Brief MVP feature N，不包含 ADRs 行，并且每个 MVP 功能对应一个故事：不得为 MVP 列表之外的简报条目添加额外故事。然后询问：“May I write these [N] stories to production/epics/[epic-slug]/, and [create | update] production/epics/[epic-slug]/EPIC.md and update production/epics/index.md?” 选项：Yes, write all [N] / Not yet, I want to adjust first；调整时可以更改任何估算。列出阶段 7 会处理的每个文件：只有在 EPIC.md 不存在时才创建它；若 index.md 不存在，则不要将其列入。得到肯定答复前，不要写入任何内容。

阶段 7：写入

故事文件

每个故事的路径为 production/epics/[epic-slug]/story-[NNN]-[slug].md，格式参照 .claude/docs/templates/story.md。故事编号绝不重复使用。每个文件都必须直接写入文件，绝不能通过 shell 命令写入：shell 写入会跳过项目的写入检查。

在 minimal 阶段，没有 GDD、ADR、TR 注册表或清单。以下字段必须按原样填写：

字段	minimal 阶段的值
GDD	design/game-brief.md
Requirement	Brief MVP feature N，绝不能使用 TR-ID
ADR Governing Implementation、ADR Decision Summary、ADR Version	N/A (minimal — no ADRs)
Manifest Version、Control Manifest Rules	N/A (minimal — no control manifest)
Engine	engine.name + engine.version
Risk	docs/engine-reference/<engine>/VERSION.md 中指定固定版本的风险等级（其时间线行或总体评级）。没有文件或没有等级时，填写 NOT ASSESSED (no VERSION.md risk rating)，绝不猜测。/dev-story 会将 NOT ASSESSED 视为 HIGH
Engine Notes	none (no ADR engine-compatibility analysis at minimal)
Acceptance Criteria	根据简介中的 Player goal & fail state 和 MVP 功能制定具体且可测试的标准；绝不能仅依据简单的项目符号自行编造

在任何阶段：

• **QA Test Cases：**如果跳过了评审，填写 *N/A — no qa-lead specs at this tier; implement against the Acceptance Criteria above*。 绝不临时编写测试用例。
• **Test Evidence：**由 qa.level 决定。在 qa.level: minimal 时，测试可免做（仅供参考），但 Visual/Feel 或 UI 故事保留的截图不在此列。
• **Estimate：**填写 Phase 6 中的规模，并反映用户做出的任何更改。
• **Dependencies：**按路径列出此故事所依赖的每个故事。
• **Files：**列出计划创建或更改的代码和测试文件，分别位于代码根目录和测试根目录下。/dev-story 会将其替换为实际文件列表。

EPIC.md

在 minimal 阶段，如果尚无文件，则根据 Phase 2 草案和下表填写。否则，将其中的 "Stories: Not yet created" 替换为表格；如果是再次访问，则为每个新故事追加一行，其余文件内容保持不变：

## Stories

| # | Story | Type | Status | ADR |
|---|-------|------|--------|-----|
| 001 | [title] | Logic | Ready | ADR-0001 |
| 002 | [title] | Integration | Blocked | ADR-0004 |

production/epics/index.md

将该 epic 的 Stories 单元格设置为 [N] stories，其中 N 为本次运行后的该 epic 故事总数。如果文件不存在，请说明： Epics index not updated: production/epics/index.md absent。

Phase 8：收尾

如果 production/epics/ 中还有其他没有故事的 epic，请列出。然后询问： "[N] 个故事已写入 production/epics/[epic-slug]/。接下来要做什么？" 可选项如下，适用时列出：

• 开始实现：在 minimal 阶段使用 /dev-story [first-story-path]，否则使用 /story-readiness [first-story-path]（推荐）
• 为 [next epic] 创建故事：/create-stories [slug]（仅当某个 epic 尚无故事时）
• 制定冲刺计划：/sprint-plan new（仅当每个 epic 都有故事时；minimal 阶段绝不使用，因为简介中的构建顺序就是计划）
• 本次会话到此为止

绝不开始实现或编写代码：此技能到故事文件为止。验收标准来自 GDD（minimal 阶段即简介），实现说明来自 ADR，规则来自清单；这些内容都不能自行编造。

本次运行的最后一条回复必须以此代码块结尾，且须先回答上面的问题（如果之前已展示过，则重复展示）：

Verdict: COMPLETE — [N] stories written to production/epics/[epic-slug]/ ([N] Ready, [N] Blocked)
Review: [QL-STORY-READY skipped — Solo mode | skipped — Lean mode | its verdicts]
Index: [production/epics/index.md updated | Epics index not updated: production/epics/index.md absent]
Next step: [/dev-story [first-story-path] | /story-readiness [first-story-path]]

如果用户拒绝写入：Verdict: BLOCKED — user declined. No story files written.