Back to Details

story-done

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Story Done

故事完成

This skill closes the loop between design and implementation. Run it at the end of implementing any story. It ensures every acceptance criterion is verified before the story is marked done, GDD and ADR deviations are explicitly documented rather than silently introduced, code review is prompted rather than forgotten, and the story file reflects actual completion status.
Output: Updated story file (Status: Complete) + surfaced next story.
该技能打通了设计与实现之间的闭环。在完成任意故事的实现后运行它，可确保故事标记为完成前所有验收标准均已验证，GDD和ADR的偏离会被明确记录而非悄然引入，代码审查会被触发而非遗忘，且故事文件能反映实际完成状态。
输出： 更新后的故事文件（状态：已完成）+ 展示下一个就绪故事。

Phase 1: Find the Story

阶段1：查找故事

Resolve the review mode (once, store for all gate spawns this run):
  1. If 
    --review [full|lean|solo]
    was passed → use that
  2. Else read 
    production/review-mode.txt
    → use that value
  3. Else → default to 
    lean
See 
.claude/docs/director-gates.md
for the full check pattern.
If a file path is provided (e.g., 
/story-done production/epics/core/story-damage-calculator.md
): read that file directly.
If no argument is provided:
  1. Check 
    production/session-state/active.md
    for the currently active story.
  2. If not found there, read the most recent file in 
    production/sprints/
    and look for stories marked IN PROGRESS.
  3. If multiple in-progress stories are found, use 
    AskUserQuestion
    :
    • "Which story are we completing?"
    • Options: list the in-progress story file names.
  4. If no story can be found, ask the user to provide the path.
确定审查模式（本次运行中所有 gate 生成均使用该模式）：
  1. 如果传入了 
    --review [full|lean|solo]
    → 使用该模式
  2. 否则读取 
    production/review-mode.txt
    → 使用其中的值
  3. 否则 → 默认使用 
    lean
查看 
.claude/docs/director-gates.md
获取完整检查模式。
如果提供了文件路径（例如：
/story-done production/epics/core/story-damage-calculator.md
）： 直接读取该文件。
如果未提供参数：
  1. 检查 
    production/session-state/active.md
    获取当前活跃的故事。
  2. 如果未找到，读取 
    production/sprints/
    中最新的文件，查找标记为 IN PROGRESS 的故事。
  3. 如果找到多个进行中的故事，使用 
    AskUserQuestion
    ：
    • 问题：“我们要完成哪个故事？”
    • 选项：列出进行中的故事文件名。
  4. 如果找不到任何故事，请用户提供路径。

Phase 2: Read the Story

阶段2：读取故事

Read the full story file. Extract and hold in context:
  • Story name and ID
  • GDD Requirement TR-ID(s) referenced (e.g., 
    TR-combat-001
    )
  • Manifest Version embedded in the story header (e.g., 
    2026-03-10
    )
  • ADR reference(s) referenced
  • Acceptance Criteria — the complete list (every checkbox item)
  • Implementation files — files listed under "files to create/modify"
  • Story Type — the 
    Type:
    field from the story header (Logic / Integration / Visual/Feel / UI / Config/Data)
  • Engine notes — any engine-specific constraints noted
  • Definition of Done — if present, the story-level DoD
  • Estimated vs actual scope — if an estimate was noted
Also read:
  • docs/architecture/tr-registry.yaml
    — look up each TR-ID in the story. Read the current 
    requirement
    text from the registry entry. This is the source of truth for what the GDD required — do not use any requirement text that may be quoted inline in the story (it may be stale).
  • The referenced GDD section — just the acceptance criteria and key rules, not the full document. Use this to cross-check the registry text is still accurate.
  • The referenced ADR(s) — just the Decision and Consequences sections
  • docs/architecture/control-manifest.md
    header — extract the current 
    Manifest Version:
    date (used in Phase 4 staleness check)
完整读取故事文件，提取并保留以下上下文信息：
  • 故事名称和ID
  • 引用的GDD需求TR-ID（多个）（例如：
    TR-combat-001
    ）
  • 故事标题中嵌入的Manifest Version（例如：
    2026-03-10
    ）
  • 引用的ADR参考（多个）
  • 验收标准 — 完整列表（每个复选框项）
  • 实现文件 — “需创建/修改的文件”下列出的文件
  • 故事类型 — 故事标题中的
    Type:
    字段（逻辑/集成/视觉体验/UI/配置/数据）
  • 引擎说明 — 任何引擎特定约束说明
  • 完成定义 — 如果存在，故事级别的DoD
  • 预估范围 vs 实际范围 — 如果记录了预估信息
同时读取：
  • docs/architecture/tr-registry.yaml
    — 查找故事中的每个TR-ID，读取注册表条目中当前的
    requirement
    文本。这是GDD需求的真实来源 — 不要使用故事中可能引用的任何过时需求文本。
  • 引用的GDD章节 — 仅读取验收标准和关键规则，而非完整文档。用此交叉验证注册表文本是否仍准确。
  • 引用的ADR（多个） — 仅读取决策和影响章节
  • docs/architecture/control-manifest.md
    标题 — 提取当前的
    Manifest Version:
    日期（用于阶段4的过时性检查）

Phase 3: Verify Acceptance Criteria

阶段3：验证验收标准

For each acceptance criterion in the story, attempt verification using one of three methods:
对故事中的每个验收标准，尝试使用以下三种方法之一进行验证：

Automatic verification (run without asking)

自动验证（无需询问直接运行）

  • File existence check: 
    Glob
    for files the story said would be created.
  • Test pass check: if a test file path is mentioned, run it via 
    Bash
    .
  • No hardcoded values check: 
    Grep
    for numeric literals in gameplay code paths that should be in config files.
  • No hardcoded strings check: 
    Grep
    for player-facing strings in 
    src/
    that should be in localization files.
  • Dependency check: if a criterion says "depends on X", check that X exists.
  • 文件存在性检查：对故事中提到的需创建文件执行
    Glob
    查找。
  • 测试通过检查：如果提到了测试文件路径，通过
    Bash
    运行它。
  • 无硬编码值检查：对游戏玩法代码路径执行
    Grep
    ，查找应在配置文件中的数值字面量。
  • 无硬编码字符串检查：对
    src/
    执行
    Grep
    ，查找应在本地化文件中的玩家可见字符串。
  • 依赖项检查：如果标准说明“依赖于X”，检查X是否存在。

Manual verification with confirmation (use 
AskUserQuestion
)

需确认的手动验证（使用
AskUserQuestion
）

  • Criteria about subjective qualities ("feels responsive", "animations play correctly")
  • Criteria about gameplay behaviour ("player takes damage when...", "enemy responds to...")
  • Performance criteria ("completes within Xms") — ask if profiled or accept as assumed
Batch up to 4 manual verification questions into a single 
AskUserQuestion
call:
question: "Does [criterion]?"
options: "Yes — passes", "No — fails", "Not tested yet"
  • 关于主观质量的标准（“响应流畅”、“动画播放正常”）
  • 关于游戏玩法行为的标准（“玩家在...时受到伤害”、“敌人对...作出响应”）
  • 性能标准（“在Xms内完成”） — 询问是否已分析或假设通过
将最多4个手动验证问题批量到一个
AskUserQuestion
调用中：
question: "[标准内容]是否满足？"
options: "是 — 通过", "否 — 不通过", "尚未测试"

Unverifiable (flag without blocking)

无法验证（标记但不阻塞）

  • Criteria that require a full game build to test (end-to-end gameplay scenarios)
  • Mark as: 
    DEFERRED — requires playtest session
  • 需要完整游戏构建才能测试的标准（端到端游戏玩法场景）
  • 标记为：
    DEFERRED — 需要游戏测试会话

Test-Criterion Traceability

测试-标准可追溯性

After completing the pass/fail/deferred check above, map each acceptance criterion to the test that covers it:
For each acceptance criterion in the story:
  1. Ask: is there a test — unit, integration, or confirmed manual playtest — that directly verifies this criterion?
    • Unit test: check 
      tests/unit/
      for a test file or function name that matches the criterion's subject (use 
      Glob
      and 
      Grep
      )
    • Integration test: check 
      tests/integration/
      similarly
    • Manual confirmation: if the criterion was verified via 
      AskUserQuestion
      above with a "Yes — passes" answer, count that as a manual test
  2. Produce a traceability table:
| Criterion | Test | Status |
|-----------|------|--------|
| AC-1: [criterion text] | tests/unit/test_foo.gd::test_bar | COVERED |
| AC-2: [criterion text] | Manual playtest confirmation | COVERED |
| AC-3: [criterion text] | — | UNTESTED |
  1. Apply these escalation rules:
    • If >50% of criteria are UNTESTED: escalate to BLOCKING — test coverage is insufficient to confirm the story is actually done. The verdict in Phase 6 cannot be COMPLETE until coverage improves.
    • If some (≤50%) criteria are UNTESTED: remain ADVISORY — does not block completion, but must appear in Completion Notes.
    • If all criteria are COVERED: no action needed beyond including the table in the report.
  2. For any ADVISORY untested criteria, add to the Completion Notes in Phase 7: 
    "Untested criteria: [AC-N list]. Recommend adding tests in a follow-up story."
完成上述通过/不通过/延迟检查后，将每个验收标准映射到覆盖它的测试：
对故事中的每个验收标准：
  1. 询问：是否有单元测试、集成测试或已确认的手动游戏测试直接验证此标准？
    • 单元测试：检查
      tests/unit/
      中是否有与标准主题匹配的测试文件或函数名（使用
      Glob
      和
      Grep
      ）
    • 集成测试：类似地检查
      tests/integration/
    • 手动确认：如果标准通过
      AskUserQuestion
      验证且回答为“是 — 通过”，则计为手动测试
  2. 生成可追溯性表格：
| 标准 | 测试 | 状态 |
|-----------|------|--------|
| AC-1: [标准文本] | tests/unit/test_foo.gd::test_bar | 已覆盖 |
| AC-2: [标准文本] | 手动游戏测试确认 | 已覆盖 |
| AC-3: [标准文本] | — | 未测试 |
  1. 应用以下升级规则：
    • 如果超过50%的标准未测试：升级为阻塞 — 测试覆盖率不足以确认故事实际完成。在覆盖率提升前，阶段6的结论不能是COMPLETE。
    • 如果部分（≤50%）标准未测试：保持为建议 — 不阻塞完成，但必须在完成说明中列出。
    • 如果所有标准均已覆盖：除了在报告中包含表格外无需其他操作。
  2. 对于任何建议级别的未测试标准，在阶段7的完成说明中添加：
    "未测试标准：[AC-N列表]。建议在后续故事中添加测试。"

Test Evidence Requirement

测试证据要求

Based on the Story Type extracted in Phase 2, check for required evidence:
Story TypeRequired EvidenceGate Level
LogicAutomated unit test in 
tests/unit/[system]/
— must exist and pass		BLOCKING
IntegrationIntegration test in 
tests/integration/[system]/
OR playtest doc		BLOCKING
Visual/FeelScreenshot + sign-off in 
production/qa/evidence/
ADVISORY
UIManual walkthrough doc OR interaction test in 
production/qa/evidence/
ADVISORY
Config/DataSmoke check pass report in 
production/qa/smoke-*.md
ADVISORY
For Logic stories: first read the story's Test Evidence section to extract the exact required file path. Use 
Glob
to check that exact path. If the exact path is not found, also search 
tests/unit/[system]/
broadly (the file may have been placed at a slightly different location). If no test file is found at either location:
  • Flag as BLOCKING: "Logic story has no unit test file. Story requires it at 
    [exact-path-from-Test-Evidence-section]
    . Create and run the test before marking this story Complete."
For Integration stories: read the story's Test Evidence section for the exact required path. Use 
Glob
to check that exact path first, then search 
tests/integration/[system]/
broadly, then check 
production/session-logs/
for a playtest record referencing this story. If none found: flag as BLOCKING (same rule as Logic).
For Visual/Feel and UI stories: glob 
production/qa/evidence/
for a file referencing this story.
  • If none: flag as ADVISORY — "No manual test evidence found. Create 
    production/qa/evidence/[story-slug]-evidence.md
    using the test-evidence template and obtain sign-off before final closure."
  • If found: read the file and check the sign-off table for unchecked boxes. Grep for lines matching 
    | .* | .* | .* | \[ \] Approved
    (a sign-off row with an unchecked checkbox). If any unchecked sign-off rows are found: flag as ADVISORY — "Evidence file found at 
    [path]
    but [N] sign-off(s) are still pending (shown as 
    [ ] Approved
    in the sign-off table). Obtain required sign-offs before final closure. Note: for solo developers, all roles may be signed off by the same person."
  • If all sign-off rows show 
    [x] Approved
    or equivalent: note "Evidence file found and all sign-offs complete — ADVISORY passed."
For Config/Data stories: check for any 
production/qa/smoke-*.md
file. If none: flag as ADVISORY — "No smoke check report found. Run 
/smoke-check
."
If no Story Type is set: flag as ADVISORY — "Story Type not declared. Add 
Type: [Logic|Integration|Visual/Feel|UI|Config/Data]
to the story header to enable test evidence gate enforcement in future stories."
Any BLOCKING test evidence gap prevents the COMPLETE verdict in Phase 6.
根据阶段2提取的故事类型，检查所需证据：
故事类型所需证据Gate级别
逻辑
tests/unit/[system]/
中的自动化单元测试 — 必须存在且通过		阻塞
集成
tests/integration/[system]/
中的集成测试或游戏测试文档		阻塞
视觉体验
production/qa/evidence/
中的截图+签字确认		建议
UI
production/qa/evidence/
中的手动走查文档或交互测试		建议
配置/数据
production/qa/smoke-*.md
中的冒烟测试通过报告		建议
对于逻辑故事：首先读取故事的测试证据部分，提取确切的所需文件路径。使用
Glob
检查该确切路径。如果未找到确切路径，也广泛搜索
tests/unit/[system]/
（文件可能放置在略有不同的位置）。如果在两个位置都未找到测试文件：
  • 标记为阻塞：“逻辑故事无单元测试文件。故事要求在
    [测试证据部分的确切路径]
    创建测试。在标记此故事为完成前，请创建并运行测试。”
对于集成故事：读取故事的测试证据部分获取确切的所需路径。首先使用
Glob
检查该确切路径，然后广泛搜索
tests/integration/[system]/
，再检查
production/session-logs/
中是否有引用此故事的游戏测试记录。 如果均未找到：标记为阻塞（与逻辑故事规则相同）。
对于视觉体验和UI故事：在
production/qa/evidence/
中查找引用此故事的文件。
  • 如果未找到：标记为建议 — “未找到手动测试证据。使用测试证据模板创建
    production/qa/evidence/[story-slug]-evidence.md
    并在最终关闭前获取签字确认。”
  • 如果找到：读取文件并检查签字确认表格中的未勾选框。使用
    Grep
    查找匹配
    | .* | .* | .* | \[ \] Approved
    的行（签字确认行中的未勾选复选框）。如果找到任何未勾选的签字确认行：标记为建议 — “在
    [路径]
    找到证据文件，但仍有[N]个签字确认待处理（在签字确认表格中显示为
    [ ] Approved
    ）。在最终关闭前获取所需签字确认。注意：对于独立开发者，所有角色可由同一人签字确认。”
  • 如果所有签字确认行均显示
    [x] Approved
    或等效标记：记录“找到证据文件且所有签字确认已完成 — 建议级别通过。”
对于配置/数据故事：检查是否存在
production/qa/smoke-*.md
文件。 如果未找到：标记为建议 — “未找到冒烟测试报告。运行
/smoke-check
。”
如果未设置故事类型：标记为建议 — “未声明故事类型。在故事标题中添加
Type: [Logic|Integration|Visual/Feel|UI|Config/Data]
，以便在未来故事中启用测试证据 gate 强制检查。”
任何阻塞级别的测试证据缺口都会阻止阶段6得出COMPLETE结论。

Phase 4: Check for Deviations

阶段4：检查偏离情况

Compare the implementation against the design documents.
Run these checks automatically:
  1. GDD rules check: Using the current requirement text from 
    tr-registry.yaml
    (looked up by the story's TR-ID), check that the implementation reflects what the GDD actually requires now — not what it required when the story was written. 
    Grep
    the implemented files for key function names, data structures, or class names mentioned in the current GDD section.
  2. Manifest version staleness check: Compare the 
    Manifest Version:
    date embedded in the story header against the 
    Manifest Version:
    date in the current 
    docs/architecture/control-manifest.md
    header.
    • If they match → pass silently.
    • If the story's version is older → flag as ADVISORY: 
      ADVISORY: Story was written against manifest v[story-date]; current manifest is v[current-date]. New rules may apply. Run /story-readiness to check.
    • If control-manifest.md does not exist → skip this check.
  3. ADR constraints check: Read the referenced ADR's Decision section. Check for forbidden patterns from 
    docs/architecture/control-manifest.md
    (if it exists). 
    Grep
    for patterns explicitly forbidden in the ADR.
  4. Hardcoded values check: 
    Grep
    the implemented files for numeric literals in gameplay logic that should be in data files.
  5. Scope check: Did the implementation touch files outside the story's stated scope? (files not listed in "files to create/modify")
For each deviation found, categorize:
  • BLOCKING — implementation contradicts the GDD or ADR (must fix before marking complete)
  • ADVISORY — implementation drifts slightly from spec but is functionally equivalent (document, user decides)
  • OUT OF SCOPE — additional files were touched beyond the story's stated boundary (flag for awareness — may be valid or scope creep)
对照设计文档检查实现情况。
自动运行以下检查：
  1. GDD规则检查：使用
    tr-registry.yaml
    中的当前需求文本（通过故事的TR-ID查找），检查实现是否符合GDD当前的实际要求 — 而非故事编写时的要求。对实现文件执行
    Grep
    ，查找当前GDD章节中提到的关键函数名、数据结构或类名。
  2. Manifest版本过时性检查：将故事标题中嵌入的
    Manifest Version:
    日期与当前
    docs/architecture/control-manifest.md
    标题中的
    Manifest Version:
    日期进行比较。
    • 如果匹配 → 静默通过。
    • 如果故事版本更旧 → 标记为建议： 
      建议：故事是基于manifest v[story-date]编写的；当前manifest是v[current-date]。可能适用新规则。运行/story-readiness进行检查。
    • 如果control-manifest.md不存在 → 跳过此检查。
  3. ADR约束检查：读取引用ADR的决策章节。检查
    docs/architecture/control-manifest.md
    （如果存在）中的禁止模式。对ADR中明确禁止的模式执行
    Grep
    。
  4. 硬编码值检查：对实现文件执行
    Grep
    ，查找游戏玩法逻辑中应在数据文件中的数值字面量。
  5. 范围检查：实现是否触及了故事规定范围之外的文件？（未在“需创建/修改的文件”中列出的文件）
对每个找到的偏离情况进行分类：
  • 阻塞 — 实现与GDD或ADR矛盾（在标记为完成前必须修复）
  • 建议 — 实现与规范略有偏差但功能等效（记录下来，由用户决定）
  • 超出范围 — 触及了故事规定边界之外的额外文件（标记以引起注意 — 可能合理也可能是范围蔓延）

Phase 4b: QA Coverage Gate

阶段4b：QA覆盖率Gate

Review mode check — apply before spawning QL-TEST-COVERAGE:
  • solo
    → skip. Note: "QL-TEST-COVERAGE skipped — Solo mode." Proceed to Phase 5.
  • lean
    → skip (not a PHASE-GATE). Note: "QL-TEST-COVERAGE skipped — Lean mode." Proceed to Phase 5.
  • full
    → spawn as normal.
After completing the deviation checks in Phase 4, spawn 
qa-lead
via Task using gate QL-TEST-COVERAGE (
.claude/docs/director-gates.md
).
Pass:
  • The story file path and story type
  • Test file paths found during Phase 3 (exact paths, or "none found")
  • The story's 
    ## QA Test Cases
    section (the pre-written test specs from story creation)
  • The story's 
    ## Acceptance Criteria
    list
The qa-lead reviews whether the tests actually cover what was specified — not just whether files exist.
Apply the verdict:
  • ADEQUATE → proceed to Phase 5
  • GAPS → flag as ADVISORY: "QA lead identified coverage gaps: [list]. Story can complete but gaps should be addressed in a follow-up story."
  • INADEQUATE → flag as BLOCKING: "QA lead: critical logic is untested. Verdict cannot be COMPLETE until coverage improves. Specific gaps: [list]."
Skip this phase for Config/Data stories (no code tests required).
审查模式检查 — 在生成QL-TEST-COVERAGE前应用：
  • solo
    → 跳过。记录：“QL-TEST-COVERAGE已跳过 — 独立模式。” 进入阶段5。
  • lean
    → 跳过（非阶段Gate）。记录：“QL-TEST-COVERAGE已跳过 — 精简模式。” 进入阶段5。
  • full
    → 正常生成。
完成阶段4的偏离检查后，通过任务生成
qa-lead
并使用Gate QL-TEST-COVERAGE（
.claude/docs/director-gates.md
）。
传递：
  • 故事文件路径和故事类型
  • 阶段3中找到的测试文件路径（确切路径或“未找到”）
  • 故事的
    ## QA测试用例
    部分（故事创建时预先编写的测试规范）
  • 故事的
    ## 验收标准
    列表
qa-lead会审查测试是否实际覆盖了指定内容 — 而非仅检查文件是否存在。
应用结论：
  • 充分 → 进入阶段5
  • 存在缺口 → 标记为建议：“QA负责人发现覆盖率缺口：[列表]。故事可完成但缺口应在后续故事中解决。”
  • 不足 → 标记为阻塞：“QA负责人：关键逻辑未测试。在覆盖率提升前，结论不能是COMPLETE。具体缺口：[列表]。”
对于配置/数据故事跳过此阶段（无需代码测试）。

Phase 5: Lead Programmer Code Review Gate

阶段5：首席程序员代码审查Gate

Review mode check — apply before spawning LP-CODE-REVIEW:
  • solo
    → skip. Note: "LP-CODE-REVIEW skipped — Solo mode." Proceed to Phase 6 (completion report).
  • lean
    → use 
    AskUserQuestion
    before proceeding:
    • Prompt: "Code review is skipped in lean mode. Did you run 
      /code-review
      on the implemented files?"
    • Options: 
      • Yes — /code-review passed or was approved with suggestions
      • No — skipping code review for this story
      • No — I'll run /code-review before the sprint close-out
    • Record the answer in the completion notes (Phase 7). All three options proceed to Phase 6.
  • full
    → spawn as normal.
Spawn 
lead-programmer
via Task using gate LP-CODE-REVIEW (
.claude/docs/director-gates.md
).
Pass: implementation file paths, story file path, relevant GDD section, governing ADR.
Present the verdict to the user. If CONCERNS, surface them via 
AskUserQuestion
:
  • Options: 
    Revise flagged issues
    / 
    Accept and proceed
    / 
    Discuss further
    If REJECT, do not proceed to Phase 6 verdict until the issues are resolved.
If the story has no implementation files yet (verdict is being run before coding is done), skip this phase and note: "LP-CODE-REVIEW skipped — no implementation files found. Run after implementation is complete."
审查模式检查 — 在生成LP-CODE-REVIEW前应用：
  • solo
    → 跳过。记录：“LP-CODE-REVIEW已跳过 — 独立模式。” 进入阶段6（完成报告）。
  • lean
    → 在进入前使用
    AskUserQuestion
    ：
    • 提示：“精简模式下跳过代码审查。你是否对实现文件运行了
      /code-review
      ？”
    • 选项： 
      • 是 — /code-review已通过或已带着建议获批
      • 否 — 跳过此故事的代码审查
      • 否 — 我会在迭代结束前运行/code-review
    • 将答案记录在完成说明中（阶段7）。所有三个选项均可进入阶段6。
  • full
    → 正常生成。
通过任务生成
lead-programmer
并使用Gate LP-CODE-REVIEW（
.claude/docs/director-gates.md
）。
传递：实现文件路径、故事文件路径、相关GDD章节、主导ADR。
向用户展示结论。如果有问题，通过
AskUserQuestion
展示：
  • 选项：
    修改标记的问题
    / 
    接受并继续
    / 
    进一步讨论
    如果被拒绝，在问题解决前不要进入阶段6结论。
如果故事尚无实现文件（在编码完成前运行结论），跳过此阶段并记录：“LP-CODE-REVIEW已跳过 — 未找到实现文件。在实现完成后运行。”

Phase 6: Present the Completion Report

阶段6：展示完成报告

Before updating any files, present the full report:
markdown
undefined
在更新任何文件前，展示完整报告：
markdown
undefined

Story Done: [Story Name]

故事完成：[故事名称]

Story: [file path] Date: [today]
故事：[文件路径] 日期：[今日]

Acceptance Criteria: [X/Y passing]

验收标准：[X/Y通过]

  • [Criterion 1] — auto-verified (test passes)
  • [Criterion 2] — confirmed
  • [Criterion 3] — FAILS: [reason]
  • [?] [Criterion 4] — DEFERRED: requires playtest
  • [标准1] — 自动验证（测试通过）
  • [标准2] — 已确认
  • [标准3] — 不通过：[原因]
  • [?] [标准4] — 延迟：需要游戏测试

Test-Criterion Traceability

测试-标准可追溯性

CriterionTestStatus
AC-1: [text][test file::test name]COVERED
AC-2: [text]Manual confirmationCOVERED
AC-3: [text]—UNTESTED
标准测试状态
AC-1: [文本][测试文件::测试名称]已覆盖
AC-2: [文本]手动确认已覆盖
AC-3: [文本]—未测试

Test Evidence

测试证据

Story Type: [Logic | Integration | Visual/Feel | UI | Config/Data | Not declared] Required evidence: [unit test file | integration test or playtest | screenshot + sign-off | walkthrough doc | smoke check pass] Evidence found: [YES — 
[path]
| NO — BLOCKING | NO — ADVISORY]
故事类型：[逻辑 | 集成 | 视觉体验 | UI | 配置/数据 | 未声明] 所需证据：[单元测试文件 | 集成测试或游戏测试 | 截图+签字确认 | 走查文档 | 冒烟测试通过] 找到的证据：[是 — 
[路径]
| 否 — 阻塞 | 否 — 建议]

Deviations

偏离情况

[NONE] OR:
  • BLOCKING: [description] — [GDD/ADR reference]
  • ADVISORY: [description] — user accepted / flagged for tech debt
[无] 或：
  • 阻塞：[描述] — [GDD/ADR参考]
  • 建议：[描述] — 用户已接受 / 标记为技术债务

Scope

范围

[All changes within stated scope] OR:
  • Extra files touched: [list] — [note whether valid or scope creep]
[所有变更均在规定范围内] 或：
  • 额外触及的文件：[列表] — [说明是否合理或范围蔓延]

Verdict: COMPLETE / COMPLETE WITH NOTES / BLOCKED

结论：COMPLETE / COMPLETE WITH NOTES / BLOCKED


**Verdict definitions:**
- **COMPLETE**: all criteria pass, no blocking deviations
- **COMPLETE WITH NOTES**: all criteria pass, advisory deviations documented
- **BLOCKED**: failing criteria or blocking deviations must be resolved first

If the verdict is **BLOCKED**: do not proceed to Phase 7. List what must be
fixed. Offer to help fix the blocking items.

---

**结论定义：**
- **COMPLETE**：所有标准通过，无阻塞性偏离
- **COMPLETE WITH NOTES**：所有标准通过，已记录建议性偏离
- **BLOCKED**：存在不通过的标准或阻塞性偏离，必须先解决

如果结论是**BLOCKED**：不要进入阶段7。列出必须修复的内容。主动提出帮助修复阻塞项。

---

Phase 7: Update Story Status

阶段7：更新故事状态

Use 
AskUserQuestion
before writing anything:
  • Prompt: "Verification complete. How do you want to proceed?"
  • Options: 
    • Close the story — update file, mark Complete, log notes (Recommended)
    • Close and log advisory deviations as tech debt in docs/tech-debt-register.md
    • There are issues I want to fix first — don't close yet
    • Accept deviations as-is and close anyway
If "Close", "Close and log tech debt", or "Accept deviations": edit the story file. If "Close and log tech debt": after updating the story file, also append the advisory deviations to 
docs/tech-debt-register.md
(create the file if it does not exist). If "Fix first": stop here and list what the user flagged. Do not write any files.
  1. Update the status field: 
    Status: Complete
  2. Update the 
    Last Updated:
    field in the story header to today's date (format: 
    YYYY-MM-DD
    ). If the field does not exist, add it after the 
    Status:
    line.
  3. Add a 
    ## Completion Notes
    section at the bottom:
markdown
undefined
在写入任何内容前使用
AskUserQuestion
：
  • 提示：“验证完成。你想如何继续？”
  • 选项： 
    • 关闭故事 — 更新文件，标记为已完成，记录说明（推荐）
    • 关闭并将建议性偏离作为技术债务记录在docs/tech-debt-register.md中
    • 存在我想先修复的问题 — 暂不关闭
    • 接受偏离情况并关闭故事
如果选择“关闭”、“关闭并记录技术债务”或“接受偏离情况”：编辑故事文件。 如果选择“关闭并记录技术债务”：更新故事文件后，将建议性偏离追加到
docs/tech-debt-register.md
（如果文件不存在则创建）。 如果选择“先修复”：在此停止并列出用户标记的问题。不要写入任何文件。
  1. 更新状态字段：
    Status: Complete
  2. 将故事标题中的
    Last Updated:
    字段更新为今日日期（格式：
    YYYY-MM-DD
    ）。如果该字段不存在，添加在
    Status:
    行之后。
  3. 在底部添加
    ## 完成说明
    部分：
markdown
undefined

Completion Notes

完成说明

Completed: [date] Criteria: [X/Y passing] ([any deferred items listed]) Deviations: [None] or [list of advisory deviations] Test Evidence: [Logic: test file at path | Visual/Feel: evidence doc at path | None required (Config/Data)] Code Review: [Pending / Complete / Skipped]

4. If the user chose "Close and log tech debt": append each advisory deviation to `docs/tech-debt-register.md` in this format:
  • [date] ([story title]): [deviation description] — tracked from [story file path]
Create the file with a `# Tech Debt Register` heading if it does not exist.

5. **Update `production/sprint-status.yaml`** (if it exists):
- Find the entry matching this story's file path or ID
- Set `status: done` and `completed: [today's date]`
- Update the top-level `updated` field
- This is a silent update — no extra approval needed (already approved in step above)

6. **Suggest a git commit**: Output a ready-to-use commit command covering the implementation files from the dev-story summary and the updated story file:
Suggested commit: git add [src/ and tests/ files changed during implementation] [story-file-path] git commit -m "feat: [story title] ([TR-ID])"

The `validate-commit.sh` hook will verify design doc references and check for hardcoded values automatically.
完成日期：[日期] 标准情况：[X/Y通过]（[列出任何延迟项]） 偏离情况：[无] 或 [建议性偏离列表] 测试证据：[逻辑：路径中的测试文件 | 视觉体验：路径中的证据文档 | 无需（配置/数据）] 代码审查：[待处理 / 已完成 / 已跳过]

4. 如果用户选择“关闭并记录技术债务”：将每个建议性偏离以以下格式追加到`docs/tech-debt-register.md`：
  • [日期] ([故事标题]): [偏离描述] — 来自[故事文件路径]
如果文件不存在，创建并添加`# 技术债务注册表`标题。

5. **更新`production/sprint-status.yaml`**（如果存在）：
- 找到与此故事文件路径或ID匹配的条目
- 设置`status: done`和`completed: [今日日期]`
- 更新顶层`updated`字段
- 此更新为静默操作 — 无需额外批准（已在上述步骤中获得批准）

6. **建议git提交**：输出一个可直接使用的提交命令，涵盖开发故事摘要中的实现文件和更新后的故事文件：
建议提交： git add [实现过程中更改的src/和tests/文件] [故事文件路径] git commit -m "feat: [故事标题] ([TR-ID])"

`validate-commit.sh`钩子会自动验证设计文档引用并检查硬编码值。

Session State Update

会话状态更新

After updating the story file, silently append to 
production/session-state/active.md
:
## Session Extract — /story-done [date]
- Verdict: [COMPLETE / COMPLETE WITH NOTES / BLOCKED]
- Story: [story file path] — [story title]
- Tech debt logged: [N items, or "None"]
- Next recommended: [next ready story title and path, or "None identified"]
If 
active.md
does not exist, create it with this block as the initial content. Confirm in conversation: "Session state updated."
更新故事文件后，静默追加到
production/session-state/active.md
：
## 会话提取 — /story-done [日期]
- 结论: [COMPLETE / COMPLETE WITH NOTES / BLOCKED]
- 故事: [故事文件路径] — [故事标题]
- 记录的技术债务: [N项，或“无”]
- 下一步建议: [下一个就绪故事的标题和路径，或“未识别到”]
如果
active.md
不存在，创建它并以此块作为初始内容。 在对话中确认：“会话状态已更新。”

Phase 8: Surface the Next Story

阶段8：展示下一个故事

After completion, help the developer keep momentum:
  1. Read the current sprint plan from 
    production/sprints/
    .
  2. Find stories that are:
    • Status: READY or NOT STARTED
    • Not blocked by other incomplete stories
    • In the Must Have or Should Have tier
Present:
undefined
完成后，帮助开发者保持推进节奏：
  1. 从
    production/sprints/
    读取当前迭代计划。
  2. 查找以下故事：
    • 状态：READY或NOT STARTED
    • 未被其他未完成故事阻塞
    • 属于Must Have或Should Have层级
展示：
undefined

Next Up

下一步

The following stories are ready to pick up:
  1. [Story name] — [1-line description] — Est: [X hrs]
  2. [Story name] — [1-line description] — Est: [X hrs]
Run 
/story-readiness [path]
to confirm a story is implementation-ready before starting.

If no more Must Have stories remain in this sprint (all are Complete or Blocked):
以下故事已就绪可开始：
  1. [故事名称] — [1行描述] — 预估: [X小时]
  2. [故事名称] — [1行描述] — 预估: [X小时]
在开始实现前，运行
/story-readiness [路径]
确认故事已准备好实现。

如果此迭代中所有Must Have故事均已完成（全部为Complete或Blocked）：

Sprint Close-Out Sequence

迭代收尾流程

All Must Have stories are complete. QA sign-off is required before advancing. Run these in order:
  1. /smoke-check sprint
    — verify the critical path still works end-to-end
  2. /team-qa sprint
    — full QA cycle: test case execution, bug triage, sign-off report
  3. /retrospective
    — capture what went well, what didn't, and action items for the next sprint
  4. /gate-check
    — advance to the next phase once QA approves (only if advancing a phase)
  5. /sprint-plan new
    — plan the next sprint, incorporating velocity data and retrospective action items
Do not run 
/gate-check
until 
/team-qa
returns APPROVED or APPROVED WITH CONDITIONS.

If there are Should Have stories still unstarted, surface them alongside the close-out sequence so the user can choose: close the sprint now, or pull in more work first.

If no more stories are ready but Must Have stories are still In Progress (not Complete):
"No more stories ready to start — [N] Must Have stories still in progress. Continue implementing those before sprint close-out."

---
所有Must Have故事已完成。在推进前需要QA签字确认。 按以下顺序运行：
  1. /smoke-check sprint
    — 端到端验证关键路径仍正常工作
  2. /team-qa sprint
    — 完整QA周期：测试用例执行、缺陷分类、签字确认报告
  3. /retrospective
    — 记录做得好的地方、待改进的地方以及下一个迭代的行动项
  4. /gate-check
    — 一旦QA批准就推进到下一阶段（仅在推进阶段时运行）
  5. /sprint-plan new
    — 规划下一个迭代，结合速度数据和回顾行动项
在
/team-qa
返回APPROVED或APPROVED WITH CONDITIONS前，不要运行
/gate-check
。

如果仍有未开始的Should Have故事，在展示收尾流程的同时列出这些故事，以便用户选择：立即关闭迭代，还是先拉入更多工作。

如果没有更多就绪故事但仍有Must Have故事在进行中（未完成）：“没有更多就绪故事可开始 — [N]个Must Have故事仍在进行中。在迭代收尾前继续完成这些故事。”

---

Collaborative Protocol

协作协议

  • Never mark a story complete without user approval — Phase 7 requires an explicit "yes" before any file is edited.
  • Never auto-fix failing criteria — report them and ask what to do.
  • Deviations are facts, not judgments — present them neutrally; the user decides if they are acceptable.
  • BLOCKED verdict is advisory — the user can override and mark complete anyway; document the risk explicitly if they do.
  • Use 
    AskUserQuestion
    for the code review prompt and for batching manual criteria confirmations.
  • 未经用户批准，切勿标记故事为完成 — 阶段7在编辑任何文件前需要明确的“是”。
  • 切勿自动修复不通过的标准 — 报告问题并询问处理方式。
  • 偏离情况是事实，而非判断 — 中立呈现；由用户决定是否可接受。
  • BLOCKED结论是建议性的 — 用户可覆盖并标记为完成；如果用户这样做，需明确记录风险。
  • 对代码审查提示和批量手动标准确认使用
    AskUserQuestion
    。

Recommended Next Steps

建议下一步操作

  • Run 
    /story-readiness [next-story-path]
    to validate the next story before starting implementation
  • If all Must Have stories are complete: run 
    /smoke-check sprint
    → 
    /team-qa sprint
    → 
    /gate-check
  • If tech debt was logged: track it via 
    /tech-debt
    to keep the register current
  • 运行
    /story-readiness [下一个故事路径]
    在开始实现前验证下一个故事
  • 如果所有Must Have故事已完成：运行
    /smoke-check sprint
    → 
    /team-qa sprint
    → 
    /gate-check
  • 如果已记录技术债务：通过
    /tech-debt
    跟踪以保持注册表最新