Back to Details

create-stories

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create Stories

创建Story

A story is a single implementable behaviour — small enough to complete in one focused session, self-contained, and fully traceable to a GDD requirement and an ADR decision. Stories are what developers pick up. Epics are what architects define.
Run this skill per epic, not per layer. Run it for Foundation epics first, then Core, and so on — matching the dependency order.
Output: 
production/epics/[epic-slug]/story-NNN-[slug].md
files
Previous step: 
/create-epics [system]
Next step after stories exist: 
/story-readiness [story-path]
then 
/dev-story [story-path]
Story是单个可实现的行为——小到可以在一个专注的工作时段内完成，具备独立性，并且可完全追溯到GDD需求和ADR决策。开发者承接的是Story，架构师定义的是Epic。
针对每个Epic运行此技能，而非针对每个层级。先针对Foundation类型的Epic运行，再处理Core类型，依此类推——遵循依赖顺序。
输出： 
production/epics/[epic-slug]/story-NNN-[slug].md
文件
上一步： 
/create-epics [system]
Story创建完成后的下一步： 
/story-readiness [story-path]
然后执行 
/dev-story [story-path]

1. Parse Argument

1. 解析参数

Extract 
--review [full|lean|solo]
if present and store as the review mode override for this run. If not provided, read 
production/review-mode.txt
(default 
full
if missing). This resolved mode applies to all gate spawns in this skill — apply the check pattern from 
.claude/docs/director-gates.md
before every gate invocation.
  • /create-stories [epic-slug]
    — e.g. 
    /create-stories combat
  • /create-stories production/epics/combat/EPIC.md
    — full path also accepted
  • No argument — ask: "Which epic would you like to break into stories?" Glob 
    production/epics/*/EPIC.md
    and list available epics with their status.
提取（如果存在）
--review [full|lean|solo]
，并将其存储为本次运行的评审模式覆盖值。如果未提供，则读取 
production/review-mode.txt
（若缺失则默认使用
full
）。解析后的模式将应用于本技能中的所有 gate 调用——在每次调用gate前，应用
.claude/docs/director-gates.md
中的检查规则。
  • /create-stories [epic-slug]
    —— 示例：
    /create-stories combat
  • /create-stories production/epics/combat/EPIC.md
    —— 也接受完整路径
  • 无参数 —— 询问："你想将哪个Epic拆分为Story？" 匹配 
    production/epics/*/EPIC.md
    并列出所有可用Epic及其状态。

2. Load Everything for This Epic

2. 加载当前Epic的所有相关内容

Read in full:
  • production/epics/[epic-slug]/EPIC.md
    — epic overview, governing ADRs, GDD requirements table
  • The epic's GDD (
    design/gdd/[filename].md
    ) — read all 8 sections, especially Acceptance Criteria, Formulas, and Edge Cases
  • All governing ADRs listed in the epic — read the Decision, Implementation Guidelines, Engine Compatibility, and Engine Notes sections
  • docs/architecture/control-manifest.md
    — extract rules for this epic's layer; note the Manifest Version date from the header
  • docs/architecture/tr-registry.yaml
    — load all TR-IDs for this system
ADR existence validation: After reading the governing ADRs list from the epic, confirm each ADR file exists on disk. If any ADR file cannot be found, stop immediately before decomposing any story:
"Epic references [ADR-NNNN: title] but 
docs/architecture/[adr-file].md
was not found. Check the filename in the epic's Governing ADRs list, or run 
/architecture-decision
to create it. Cannot create stories until all referenced ADR files are present."
Do not proceed to Step 3 until all referenced ADR files are confirmed present.
Report: "Loaded epic [name], GDD [filename], [N] governing ADRs (all confirmed present), control manifest v[date]."
完整读取以下内容：
  • production/epics/[epic-slug]/EPIC.md
    —— Epic概述、主导ADR、GDD需求表
  • Epic对应的GDD（
    design/gdd/[filename].md
    ）—— 读取全部8个章节，尤其关注验收标准、公式和边缘情况
  • Epic中列出的所有主导ADR——读取决策、实施指南、引擎兼容性和引擎说明章节
  • docs/architecture/control-manifest.md
    —— 提取当前Epic层级的规则；记录页眉中的清单版本日期
  • docs/architecture/tr-registry.yaml
    —— 加载本系统的所有TR-ID
ADR存在性验证：从Epic中读取主导ADR列表后，确认每个ADR文件都存在于磁盘上。如果任何ADR文件未找到，在拆分任何Story前立即停止：
"Epic引用了[ADR-NNNN: 标题]，但未找到
docs/architecture/[adr-file].md
文件。 请检查Epic的主导ADR列表中的文件名，或运行
/architecture-decision
来创建该文件。所有引用的ADR文件都存在后，才能创建Story。"
在确认所有引用的ADR文件都存在前，不要进入步骤3。
报告："已加载Epic [名称]、GDD [文件名]、[N]个主导ADR（均已确认存在）、控制清单v[日期]。"

3. Classify Stories by Type

3. 按类型分类Story

Story Type Classification — assign each story a type based on its acceptance criteria:
Story TypeAssign when criteria reference...
LogicFormulas, numerical thresholds, state transitions, AI decisions, calculations
IntegrationTwo or more systems interacting, signals crossing boundaries, save/load round-trips
Visual/FeelAnimation behaviour, VFX, "feels responsive", timing, screen shake, audio sync
UIMenus, HUD elements, buttons, screens, dialogue boxes, tooltips
Config/DataBalance tuning values, data file changes only — no new code logic
Mixed stories: assign the type that carries the highest implementation risk. The type determines what test evidence is required before 
/story-done
can close the story.
Story类型分类——根据验收标准为每个Story分配类型：
Story类型分配条件：当标准涉及...
Logic（逻辑）公式、数值阈值、状态转换、AI决策、计算
Integration（集成）两个或多个系统交互、跨边界信号、保存/加载往返流程
Visual/Feel（视觉/体验）动画行为、视觉特效、"响应流畅"、时序、屏幕震动、音频同步
UI（用户界面）菜单、HUD元素、按钮、屏幕、对话框、工具提示
Config/Data（配置/数据）平衡调优值、仅数据文件变更——无新代码逻辑
混合类型的Story：分配具有最高实施风险的类型。类型决定了在
/story-done
关闭Story前需要哪些测试证据。

4. Decompose the GDD into Stories

4. 将GDD拆分为Story

For each GDD acceptance criterion:
  1. Group related criteria that require the same core implementation
  2. Each group = one story
  3. Order stories: foundational behaviour first, edge cases last, UI last
Story sizing rule: one story = one focused session (~2-4 hours). If a group of criteria would take longer, split into two stories.
For each story, determine:
  • GDD requirement: which acceptance criterion(ia) does this satisfy?
  • TR-ID: look up in 
    tr-registry.yaml
    . Use the stable ID. If no match, use 
    TR-[system]-???
    and warn.
  • Governing ADR: which ADR governs how to implement this? 
    • Status: Accepted
      → embed normally
    • Status: Proposed
      → set story 
      Status: Blocked
      with note: "BLOCKED: ADR-NNNN is Proposed — run 
      /architecture-decision
      to advance it"
  • Story Type: from Step 3 classification
  • Engine risk: from the ADR's Knowledge Risk field
针对每个GDD验收标准：
  1. 将需要相同核心实现的相关标准分组
  2. 每个组对应一个Story
  3. Story排序：先基础行为，再边缘情况，最后是UI
Story规模规则：一个Story对应一个专注工作时段（约2-4小时）。如果一组标准所需时间更长，则拆分为两个Story。
针对每个Story，确定：
  • GDD需求：该Story满足哪些验收标准？
  • TR-ID：在
    tr-registry.yaml
    中查找。使用稳定ID。如果无匹配项，使用
    TR-[system]-???
    并发出警告。
  • 主导ADR：哪个ADR指导该Story的实施？ 
    • Status: Accepted
      → 正常嵌入
    • Status: Proposed
      → 将Story状态设置为
      Blocked
      ，并添加备注："已阻塞：ADR-NNNN处于提议状态——运行
      /architecture-decision
      推进其状态"
  • Story类型：来自步骤3的分类
  • 引擎风险：来自ADR的Knowledge Risk字段

4b. QA Lead Story Readiness Gate

4b. QA负责人Story就绪Gate

Review mode check — apply before spawning QL-STORY-READY:
  • solo
    → skip. Note: "QL-STORY-READY skipped — Solo mode." Proceed to Step 5 (present stories for review).
  • lean
    → skip (not a PHASE-GATE). Note: "QL-STORY-READY skipped — Lean mode." Proceed to Step 5 (present stories for review).
  • full
    → spawn as normal.
After decomposing all stories (Step 4 complete) but before presenting them for write approval, spawn 
qa-lead
via Task using gate QL-STORY-READY (
.claude/docs/director-gates.md
).
Pass: the full story list with acceptance criteria, story types, and TR-IDs; the epic's GDD acceptance criteria for reference.
Present the QA lead's assessment. For each story flagged as GAPS or INADEQUATE, revise the acceptance criteria before proceeding — stories with untestable criteria cannot be implemented correctly. Once all stories reach ADEQUATE, proceed.
After ADEQUATE: for every Logic and Integration story, ask the qa-lead to produce concrete test case specifications — one per acceptance criterion — in this format:
Test: [criterion text]
  Given: [precondition]
  When: [action]
  Then: [expected result / assertion]
  Edge cases: [boundary values or failure states to test]
For Visual/Feel and UI stories, produce manual verification steps instead:
Manual check: [criterion text]
  Setup: [how to reach the state]
  Verify: [what to look for]
  Pass condition: [unambiguous pass description]
These test case specs are embedded directly into each story's 
## QA Test Cases
section. The developer implements against these cases. The programmer does not write tests from scratch — QA has already defined what "done" looks like.
评审模式检查——在调用QL-STORY-READY前应用：
  • solo
    → 跳过。备注："QL-STORY-READY已跳过——单人模式。" 进入步骤5（展示Story供评审）。
  • lean
    → 跳过（非阶段Gate）。备注："QL-STORY-READY已跳过——精简模式。" 进入步骤5（展示Story供评审）。
  • full
    → 正常调用。
完成所有Story拆分（步骤4完成）后，在提交写入批准前，通过任务调用
qa-lead
并使用QL-STORY-READY gate（
.claude/docs/director-gates.md
）。
传递内容：完整的Story列表（含验收标准、Story类型和TR-ID）；供参考的Epic的GDD验收标准。
展示QA负责人的评估结果。对于每个被标记为GAPS（存在缺口）或INADEQUATE（不充分）的Story，在继续前修订验收标准——无法测试的标准无法正确实施。所有Story达到ADEQUATE（充分）状态后，再继续。
达到ADEQUATE状态后：针对每个Logic和Integration类型的Story，要求qa-lead生成具体的测试用例规范——每个验收标准对应一个，格式如下：
Test: [标准文本]
  Given: [前置条件]
  When: [操作]
  Then: [预期结果/断言]
  Edge cases: [要测试的边界值或故障状态]
针对Visual/Feel和UI类型的Story，生成手动验证步骤：
Manual check: [标准文本]
  Setup: [如何进入该状态]
  Verify: [需要检查的内容]
  Pass condition: [明确的通过描述]
这些测试用例规范将直接嵌入每个Story的
## QA Test Cases
章节。开发者将根据这些用例进行开发。程序员无需从零编写测试——QA已定义了“完成”的标准。

5. Present Stories for Review

5. 展示Story供评审

Before writing any files, present the full story list:
undefined
在写入任何文件前，展示完整的Story列表：
undefined

Stories for Epic: [name]

对应Epic的Story: [名称]

Story 001: [title] — Logic — ADR-NNNN Covers: TR-[system]-001 ([1-line summary of requirement]) Test required: tests/unit/[system]/[slug]_test.[ext]
Story 002: [title] — Integration — ADR-MMMM Covers: TR-[system]-002, TR-[system]-003 Test required: tests/integration/[system]/[slug]_test.[ext]
Story 003: [title] — Visual/Feel — ADR-NNNN Covers: TR-[system]-004 Evidence required: production/qa/evidence/[slug]-evidence.md
[N stories total: N Logic, N Integration, N Visual/Feel, N UI, N Config/Data]

Use `AskUserQuestion`:
- Prompt: "May I write these [N] stories to `production/epics/[epic-slug]/`?"
- Options: `[A] Yes — write all [N] stories` / `[B] Not yet — I want to review or adjust first`

---
Story 001: [标题] — Logic — ADR-NNNN 覆盖需求: TR-[system]-001 ([需求的一行摘要]) 所需测试: tests/unit/[system]/[slug]_test.[ext]
Story 002: [标题] — Integration — ADR-MMMM 覆盖需求: TR-[system]-002, TR-[system]-003 所需测试: tests/integration/[system]/[slug]_test.[ext]
Story 003: [标题] — Visual/Feel — ADR-NNNN 覆盖需求: TR-[system]-004 所需证据: production/qa/evidence/[slug]-evidence.md
[共N个Story：N个Logic、N个Integration、N个Visual/Feel、N个UI、N个Config/Data]

使用`AskUserQuestion`：
- 提示："我可以将这[N]个Story写入`production/epics/[epic-slug]/`吗？"
- 选项：`[A] 是 —— 写入全部[N]个Story` / `[B] 暂不——我想先评审或调整`

---

6. Write Story Files

6. 写入Story文件

For each story, write 
production/epics/[epic-slug]/story-[NNN]-[slug].md
:
markdown
undefined
针对每个Story，写入
production/epics/[epic-slug]/story-[NNN]-[slug].md
：
markdown
undefined

Story [NNN]: [title]

Story [NNN]: [标题]

Epic: [epic name] Status: Ready Layer: [Foundation / Core / Feature / Presentation] Type: [Logic | Integration | Visual/Feel | UI | Config/Data] Manifest Version: [date from control-manifest.md header]
Epic: [Epic名称] 状态: Ready 层级: [Foundation / Core / Feature / Presentation] 类型: [Logic | Integration | Visual/Feel | UI | Config/Data] 清单版本: [来自control-manifest.md页眉的日期]

Context

上下文

GDD: 
design/gdd/[filename].md
Requirement: 
TR-[system]-NNN
(Requirement text lives in 
docs/architecture/tr-registry.yaml
— read fresh at review time)
ADR Governing Implementation: [ADR-NNNN: title] ADR Decision Summary: [1-2 sentence summary of what the ADR decided]
Engine: [name + version] | Risk: [LOW / MEDIUM / HIGH] Engine Notes: [from ADR Engine Compatibility section — post-cutoff APIs, verification required]
Control Manifest Rules (this layer):
  • Required: [relevant required pattern]
  • Forbidden: [relevant forbidden pattern]
  • Guardrail: [relevant performance guardrail]
GDD: 
design/gdd/[filename].md
需求: 
TR-[system]-NNN
(需求文本位于
docs/architecture/tr-registry.yaml
中——评审时请重新读取)
主导实施的ADR: [ADR-NNNN: 标题] ADR决策摘要: [1-2句话总结ADR的决策内容]
引擎: [名称 + 版本] | 风险: [LOW / MEDIUM / HIGH] 引擎说明: [来自ADR的引擎兼容性章节——需注意过期API、需要验证的内容]
控制清单规则（当前层级）:
  • 必填: [相关必填模式]
  • 禁用: [相关禁用模式]
  • 防护规则: [相关性能防护规则]

Acceptance Criteria

验收标准

From GDD 
design/gdd/[filename].md
, scoped to this story:
  • [criterion 1 — directly from GDD]
  • [criterion 2]
  • [performance criterion if applicable]
来自GDD 
design/gdd/[filename].md
，已限定到当前Story:
  • [标准1 —— 直接来自GDD]
  • [标准2]
  • [若适用则添加性能标准]

Implementation Notes

实施说明

Derived from ADR-NNNN Implementation Guidelines:
[Specific, actionable guidance from the ADR. Do not paraphrase in ways that change meaning. This is what the programmer reads instead of the ADR.]
源自ADR-NNNN的实施指南:
[来自ADR的具体、可执行的指导内容。请勿以改变原意的方式转述。这是程序员将阅读的内容，替代直接查看ADR。]

Out of Scope

范围外内容

Handled by neighbouring stories — do not implement here:
  • [Story NNN+1]: [what it handles]
由相邻Story处理——请勿在此实现:

QA Test Cases

QA测试用例

Written by qa-lead at story creation. The developer implements against these — do not invent new test cases during implementation.
[For Logic / Integration stories — automated test specs]:
  • AC-1: [criterion text]
    • Given: [precondition]
    • When: [action]
    • Then: [assertion]
    • Edge cases: [boundary values / failure states]
[For Visual/Feel / UI stories — manual verification steps]:
  • AC-1: [criterion text]
    • Setup: [how to reach the state]
    • Verify: [what to look for]
    • Pass condition: [unambiguous pass description]
在Story创建时由qa-lead编写。开发者需根据这些用例实现——请勿在开发过程中自行创建新测试用例。
[针对Logic / Integration类型Story——自动化测试规范]:
  • AC-1: [标准文本]
    • Given: [前置条件]
    • When: [操作]
    • Then: [断言]
    • Edge cases: [边界值/故障状态]
[针对Visual/Feel / UI类型Story——手动验证步骤]:
  • AC-1: [标准文本]
    • Setup: [如何进入该状态]
    • Verify: [需要检查的内容]
    • Pass condition: [明确的通过描述]

Test Evidence

测试证据

Story Type: [type] Required evidence:
  • Logic: 
    tests/unit/[system]/[story-slug]_test.[ext]
    — must exist and pass
  • Integration: 
    tests/integration/[system]/[story-slug]_test.[ext]
    OR playtest doc
  • Visual/Feel: 
    production/qa/evidence/[story-slug]-evidence.md
    + sign-off
  • UI: 
    production/qa/evidence/[story-slug]-evidence.md
    or interaction test
  • Config/Data: smoke check pass (
    production/qa/smoke-*.md
    )
Status: [ ] Not yet created
Story类型: [类型] 所需证据:
  • Logic: 
    tests/unit/[system]/[story-slug]_test.[ext]
    —— 必须存在且通过测试
  • Integration: 
    tests/integration/[system]/[story-slug]_test.[ext]
    或游戏测试文档
  • Visual/Feel: 
    production/qa/evidence/[story-slug]-evidence.md
    + 签字确认
  • UI: 
    production/qa/evidence/[story-slug]-evidence.md
    或交互测试
  • Config/Data: 冒烟测试通过 (
    production/qa/smoke-*.md
    )
状态: [ ] 尚未创建

Dependencies

依赖关系

  • Depends on: [Story NNN-1 must be DONE, or "None"]
  • Unlocks: [Story NNN+1, or "None"]
undefined
  • 依赖于: [Story NNN-1必须完成，或“无”]
  • 解锁: [Story NNN+1，或“无”]
undefined

Also update 
production/epics/[epic-slug]/EPIC.md

同时更新 
production/epics/[epic-slug]/EPIC.md

Replace the "Stories: Not yet created" line with a populated table:
markdown
undefined
将“Stories: Not yet created”行替换为填充后的表格：
markdown
undefined

Stories

Stories

#StoryTypeStatusADR
001[title]LogicReadyADR-NNNN
002[title]IntegrationReadyADR-MMMM

---
#Story类型状态ADR
001[标题]LogicReadyADR-NNNN
002[标题]IntegrationReadyADR-MMMM

---

7. After Writing

7. 写入完成后

Use 
AskUserQuestion
to close with context-aware next steps:
Check:
  • Are there other epics in 
    production/epics/
    without stories yet? List them.
  • Is this the last epic? If so, include 
    /sprint-plan
    as an option.
Widget:
  • Prompt: "[N] stories written to 
    production/epics/[epic-slug]/
    . What next?"
  • Options (include all that apply): 
    • [A] Start implementing — run /story-readiness [first-story-path]
      (Recommended)
    • [B] Create stories for [next-epic-slug] — run /create-stories [slug]
      (only if other epics have no stories yet)
    • [C] Plan the sprint — run /sprint-plan
      (only if all epics have stories)
    • [D] Stop here for this session
Note in output: "Work through stories in order — each story's 
Depends on:
field tells you what must be DONE before you can start it."
使用
AskUserQuestion
根据上下文提供下一步选项：
检查：
  • production/epics/
    中是否还有其他未创建Story的Epic？列出它们。
  • 这是否是最后一个Epic？如果是，将
    /sprint-plan
    作为选项之一。
交互组件：
  • 提示："已将[N]个Story写入
    production/epics/[epic-slug]/
    。下一步做什么？"
  • 选项（包含所有适用项）： 
    • [A] 开始实施——运行 /story-readiness [首个Story路径]
      （推荐）
    • [B] 为[next-epic-slug]创建Story——运行 /create-stories [slug]
      （仅当存在其他未创建Story的Epic时显示）
    • [C] 规划迭代——运行 /sprint-plan
      （仅当所有Epic都已创建Story时显示）
    • [D] 本次会话到此结束
输出备注："按顺序处理Story——每个Story的
Depends on:
字段会告诉你开始前必须完成的内容。"

Collaborative Protocol

协作协议

  1. Read before presenting — load all inputs silently before showing the story list
  2. Ask once — present all stories for the epic in one summary, not one at a time
  3. Warn on blocked stories — flag any story with a Proposed ADR before writing
  4. Ask before writing — get approval for the full story set before writing files
  5. No invention — acceptance criteria come from GDDs, implementation notes from ADRs, rules from the manifest
  6. Never start implementation — this skill stops at the story file level
After writing (or declining):
  • Verdict: COMPLETE — [N] stories written to 
    production/epics/[epic-slug]/
    . Run 
    /story-readiness
    → 
    /dev-story
    to begin implementation.
  • Verdict: BLOCKED — user declined. No story files written.
  1. 展示前先读取——在展示Story列表前，静默加载所有输入内容
  2. 一次性询问——一次性展示当前Epic的所有Story摘要，而非逐个展示
  3. 标记阻塞的Story——在写入前标记任何关联提议状态ADR的Story
  4. 写入前询问——在写入文件前获得完整Story集的批准
  5. 不自行创造内容——验收标准来自GDD，实施说明来自ADR，规则来自清单
  6. 绝不启动实施——本技能仅到生成Story文件为止
写入完成（或被拒绝）后：
  • 结论: COMPLETE——已将[N]个Story写入
    production/epics/[epic-slug]/
    。运行
    /story-readiness
    → 
    /dev-story
    开始实施。
  • 结论: BLOCKED——用户已拒绝。未写入任何Story文件。