planning-stories

规划故事

将用户故事拆分为可独立测试的任务。每项任务都是一个小型、可验证的工作单元，完成后会推动整个故事的完成。

---

⚠️ 两种模式——请先阅读

此技能有两种模式。开始操作前，请确认当前所处的模式。

1. 默认模式——故事规划（通常使用）

生成一个**STORY.<name>.md** 规划文件（也可选择生成 STORY.<name>.TECH-SPEC.md）。这是供人阅读的规划产物。它不会被自动执行。用户要求规划、拆解或分解故事时，均使用此模式。

2. 仅在明确要求时使用——Ralph 任务生成

生成 Ralph 循环文件（<task-name>.TASK.md + <task-name>.progress.txt），由 ralph.sh 脚本每次迭代自主运行一个故事。

重要规则

**除非用户明确要求，否则绝不要生成 Ralph 任务文件。**仅在用户直接提出以下要求时触发：

• “将此故事拆分为 Ralph 任务”
• “生成 .TASK.md 文件”
• “让 Ralph 能够运行此任务”／“通过 ralph 运行此任务”
• “为 Ralph 循环创建任务拆解”

在常规故事创建过程中，不要生成 .TASK.md／.progress.txt 文件。生成 STORY.<name>.md 规划任务（见下方步骤 1–5）是允许且符合预期的——这是规划，不是 Ralph 执行。

明确要求使用模式 2 时，请遵循完整工作流，参见 ralph-tasks.md。

---

工作内容

默认模式（故事规划）：

1. 接收用户的故事描述
2. 如有需要，提出澄清问题
3. 将故事拆分为小型、可测试的任务
4. 保存到 STORY.<name>.md
5. 启动 writing-tech-specs 子 Agent，创建 STORY.<name>.TECH-SPEC.md

**Ralph 模式（仅在明确要求时使用）：**遵循 ralph-tasks.md——在故事文件旁生成 <task-name>.TASK.md + <task-name>.progress.txt。除非用户明确要求（见上方重要规则），否则不要进入此模式。

---

核心原则

任务独立性

每项任务都必须：

• 可独立完成——不依赖尚未完成的任务
• 可测试——具有明确的验证标准
• 不会造成破坏——每项任务完成后，应用仍可正常运行
• 规模小——可在一个上下文窗口内完成（约 10 分钟的 AI 工作）

任务排序（重要）

务必按依赖关系排序，以避免破坏性变更：

1. 数据库／架构变更——迁移、新增列、新增表
2. 后端／仓库层——数据访问、查询、变更
3. API／服务层——端点、业务逻辑
4. 前端／UI——组件、屏幕、表单

顺序错误会导致构建失败！

---

步骤 1：分析故事

理解用户的需求：

• 新功能：添加新功能
• 更新／修改：更改现有行为
• 错误修复：纠正错误行为
• 重构：改进代码但不改变行为

以下情况需提出澄清问题：

• 范围不明确
• 可能存在多种解释
• 存在破坏性变更风险
• 测试策略不明确

澄清问题示例

- "What should happen when [edge case]?"
- "Is this a breaking change, or should existing behavior still work?"
- "Are there any constraints on [field/feature]?"
- "Should this work for all users or just [specific role]?"
- "What's the rollback strategy if something goes wrong?"

---

步骤 2：拆分任务

详细的拆分模式请参见 examples.md。

快速参考

故事类型	任务顺序
新增字段	数据库 → 仓库 → API → 前端
更新字段	并行添加 → 后端 → 前端 → 移除旧字段
新增实体	数据库 → 仓库 → API → 列表 UI → 详情 UI
错误修复	找出原因 → 添加测试 → 修复 → 验证

---

步骤 3：定义验证标准

每项任务都必须有可测试的验证标准。

良好的标准（可验证）

- [ ] Migration runs successfully
- [ ] Unit test: new column exists with correct type
- [ ] Typecheck passes
- [ ] App starts without errors

不良的标准（含糊不清）

- [ ] Works correctly
- [ ] User can see the change
- [ ] Good UX

每项任务都必须具备的标准

- [ ] Typecheck passes
- [ ] All tests pass
- [ ] App runs without errors

BDD 格式（可选，适用于复杂流程）

Given [context]
When [action]
Then [expected result]

---

步骤 4：生成 STORY..md

文件命名

• 使用大写的 STORY 前缀和 kebab-case 名称：STORY.add-user-profile-picture.md
• 去掉冠词：“the”、“a”、“an”
• 描述清晰、简洁

模板结构

# Story: [Title]

## Overview

[Brief description of what this story accomplishes]

## Dependencies

- [List any existing features/systems this depends on]
- [None if standalone]

---

## Tasks

### Task 1: [Title]

**Layer:** database | backend | api | frontend | cleanup

**Description:**
[What this task does]

**Changes:**
- [Specific file/table/function being changed]

**Verification:**
- [ ] [Specific testable criterion]
- [ ] Typecheck passes
- [ ] All tests pass
- [ ] App runs without errors

---

### Task 2: [Title]

[Same structure as Task 1]

---

## Completion Criteria

The story is complete when:

- [ ] All tasks are verified complete
- [ ] End-to-end flow works as expected
- [ ] No breaking changes to existing functionality

## Rollback Plan

[If something goes wrong, how to revert]

---

## Notes

[Any additional context, assumptions, or decisions made]

---

步骤 5：启动 writing-tech-specs 子 Agent

创建 STORY.<name>.md 后，启动一个子 Agent 来编写技术规格说明。

子 Agent 提示词模板

Read the file STORY.<name>.md and use the writing-tech-specs skill to create a detailed technical specification.

The tech-spec should include:
1. Model changes (database schema)
2. Flow diagrams (backend/frontend flows)
3. API endpoints
4. Happy path description
5. Backwards compatibility notes

Save the output to STORY.<name>.TECH-SPEC.md

**注意：**技术规格文件使用与故事文件相同的 <name>，并附加 .TECH-SPEC.md。例如，如果故事文件是 STORY.add-user-auth.md，技术规格文件则为 STORY.add-user-auth.TECH-SPEC.md。

**注意：**如果 writing-tech-specs 技能不可用，请跳过此步骤，并在故事文件中注明。

---

步骤 6（可选——仅在明确要求时）：生成 Ralph 任务文件

**仅当用户明确要求生成 Ralph-loop 任务文件时，才执行此步骤。**如果用户没有要求，请在此处停止——故事规划已完成。

收到明确要求后，切换到 ralph-tasks.md 中记载的 Ralph 工作流，并生成：

• <task-name>.TASK.md — 任务拆分文档
• <task-name>.progress.txt — 空的进度跟踪文件

默认情况下，这两个文件都创建在故事文件旁边，并且 <task-name> 必须遵循 task-<number>-<description> 命名约定（例如 task-1-add-currency-table.TASK.md）。随后，用户运行 ralph.sh <task-name>.TASK.md 来执行。

**提醒：**此步骤为主动选择加入。普通故事规划过程中绝不要生成这些文件。

---

不应拆分的情况

如果故事符合以下条件，则可作为一个完整的单项任务：

• 只涉及单个文件／组件变更
• 不涉及数据库变更
• 不涉及 API 变更
• 可在 30 分钟内完成
• 只有一种验证方式

在这种情况下，只需创建故事文件，无需拆分为子任务。

---

应避免的反模式

反模式	问题
过于细碎	“创建文件”“添加导入”——都不是真正的任务
过于宽泛	“实现功能”——无法在一次工作中验证
混合层级	在同一任务中同时处理数据库和前端
验证方式模糊	“正常运行”——如何确认？
缺少回滚方案	无法撤销数据库迁移
存在前向依赖	任务 2 依赖任务 5

---

常见模式

详细模式请参阅 patterns.md：

• 添加新字段
• 更新现有字段
• 添加新实体
• 添加新关系

---

故障排除

问题	解决方案
故事似乎过于庞大	拆分为更小的子任务，或拆分成多个故事
检测到破坏性变更	先添加并行字段／端点，更新前端，然后移除旧内容
测试策略不明确	请用户澄清，并添加手动验证步骤

---

保存前检查清单

• 故事已拆分为小型、可测试的任务
• 每项任务都标明了清晰的层级（数据库／后端／API／前端）
• 任务已按依赖关系排序（不存在前向依赖）
• 每项任务都有明确的验证标准
• 每项任务都包含类型检查、测试和应用运行检查
• 破坏性变更采用并行字段或分阶段发布
• 完成标准涵盖整个故事
• 已制定回滚方案
• 文件命名为 STORY.<name>.md
• 未生成 Ralph .TASK.md／.progress.txt 文件（除非用户明确要求）