Preamble (run first)
# 检查方案设计目录
# 检查前置文档
echo "📊 正在检查前置文档..."
if [ -f "docs/02-方案设计/PRD产品需求文档.md" ]; then
echo "✅ PRD文档 - 已找到"
else
echo "⏳ PRD文档 - 未找到"
fi
if [ -f "docs/02-方案设计/功能细节拆解.md" ]; then echo "✅ 功能细节拆解 - 已找到" else echo "⏳ 功能细节拆解 - 未找到" fi
---
## 写入时边界
只讨论时不写文件，启动检查不创建目录。用户要求保存产物时，先确认当前产品、精确输出路径及已有文件的覆盖/追加选择；确认后**仅在实际 Write 前**创建该输出文件的父目录。完整安装可参见 `skills/_shared/artifact-policy.md`，单独安装本 skill 也按本段执行。
---
## 跨 Agent 交互规则
当流程要求与用户交互时：
1. 如果当前环境支持 AskUserQuestion，使用 AskUserQuestion（最佳体验）。
2. 如果当前环境不支持 AskUserQuestion，必须用普通聊天消息提出同样问题。
3. 一次只问一个问题。
4. 提问后必须停止当前回合，等待用户回答（STOP and WAIT）。
5. 不得在用户回答前生成文档、写入 docs。
6. 已有 docs 文件不能替代本轮用户回答。
---
## 执行流程
### 步骤 1: 选择用户故事范围
使用 AskUserQuestion 询问：
> 您需要编写哪方面的用户故事？
>
> A) 全部功能用户故事（基于PRD功能列表）
> B) 单个模块的用户故事（请指定模块）
> C) 单个功能的用户故事（请指定功能）
> D) Epic级用户故事（高层次需求）
> E) 其他（请手动输入）
>
> 💡 提示：
> - Sprint规划 → 推荐单个模块的用户故事
> - 产品规划 → 推荐Epic级用户故事
> - 开发准备 → 推荐全部功能用户故事
记录到变量 `STORY_SCOPE`
---
### 步骤 2: 读取前置数据
根据范围读取相应文档：
**必需文档**：
- PRD产品需求文档（如果存在）
- 功能细节拆解（如果存在）
**可选文档**：
- MVP方案
- 用户画像
**读取失败处理**：
如果 PRD 文档不存在：
> ⚠️ 未找到 PRD 文档
>
> 用户故事需要明确的功能需求作为输入。
>
> 您可以选择：
> A) 执行 /pm-docs 生成 PRD
> B) 使用功能细节拆解作为输入
> C) 手动输入功能需求（快速模式）
---
### 步骤 3: 用户故事编写原则
> 📝 用户故事标准格式：
>
> ```
> 作为 <角色>
> 我想要 <功能>
> 以便于 <价值>
> ```
>
> **验收标准（BDD格式）**：
> ```
> GIVEN <前置条件>
> WHEN <触发操作>
> THEN <预期结果>
> ```
>
> 是否继续编写？
>
> A) 理解了，开始编写
> B) 我需要更多示例
> C) 我有特定的编写规范
---
### 步骤 4: Epic级用户故事
#### 4.1 识别Epic
基于PRD识别出Epic：
| Epic ID | Epic名称 | 描述 | 包含Story数 |
|---------|---------|------|------------|
| E001 | 用户管理 | 用户注册、登录、信息管理 | 5 |
| E002 | 商品浏览 | 商品列表、搜索、详情 | 4 |
| E003 | 购物车管理 | 加入购物车、编辑、结算 | 3 |
| E004 | 订单管理 | 订单创建、支付、查看 | 6 |
> 是否需要调整Epic划分？
>
> A) 划分合理，继续
> B) 需要调整
> C) 我有其他划分方式
#### 4.2 Epic详细描述
对每个Epic进行描述：
Epic: E001 User Management
As a product system I want to provide user management functionality So that users can register and log in, and manage personal information
Business value:
- Users can have personal accounts
- Support personalized services
- Provide user data for data analysis
Includes Stories: US001-US005 Priority: P0 Estimated effort: 5 person-days
逐个对每个Epic确认后继续。
---
### 步骤 5: Story级用户故事
#### 5.1 逐个编写Story
对每个功能，按以下模板编写用户故事：
> **US001: 用户注册**
>
> ```
> 作为 新用户
> 我想要 通过手机号注册账号
> 以便于 拥有个人账号，享受个性化服务
> ```
>
> **验收标准 - 场景1：正常注册**
> ```
> GIVEN 用户未注册过，打开注册页面
> WHEN 用户输入手机号、验证码、密码，点击"注册"
> THEN 创建账号成功，自动登录，跳转到首页
> ```
>
> **场景2：手机号已注册**
> ```
> GIVEN 手机号已注册
> WHEN 用户输入该手机号
> THEN 提示"已注册，请直接登录"
> ```
>
> **场景3：验证码错误**
> ```
> GIVEN 用户已获取验证码
> WHEN 输入错误验证码
> THEN 提示"验证码错误"，允许重新输入
> ```
>
> **技术备注**：验证码5分钟有效，密码bcrypt加密
> **依赖**：无
> **风险**：验证码发送失败 → 提供邮箱注册备选
>
> 这个用户故事是否完整？
>
> A) 完整，继续下一个Story
> B) 需要调整
> C) 需要补充更多场景
逐个Story编写，直到功能列表完成。
#### 5.2 Subagent 并行编写（v2.0 增强）
如果有大量Story（>10个），使用 Agent 工具并行生成：
```markdown
使用 Agent 工具并行派发：
Agent 1: 编写Epic1的所有Story
- 输入：Epic1 描述 + 功能列表
- 输出：完整用户故事（含验收标准）
Agent 2: 编写Epic2的所有Story
- 输入：Epic2 描述 + 功能列表
- 输出：完整用户故事（含验收标准）
Agent 3: 编写Epic3的所有Story
- 输入：Epic3 描述 + 功能列表
- 输出：完整用户故事（含验收标准）
Agent 4: 验收标准生成
- 输入：所有 Story 列表
- 输出：每个 Story 的 BDD 验收标准
主 agent 等待所有 subagent 完成，合并汇总输出最终文档。
Version comparison (v1 vs v2)
| Dimension | v1 (serial) | v2 (Subagent parallel) |
|---|---|---|
| Story writing | Write one by one | Subagents write in parallel by Epic |
| Acceptance criteria | Write manually item by item | Subagent batch generation |
| Token usage | All Stories occupy the main context | Subagents have independent contexts |
| Execution efficiency | Linear sequence | 3-4x parallel speedup |
Step 6: Story breakdown
For complex Stories (Story Point > 8 or too many acceptance criteria), perform breakdown:
🔍 Story breakdown suggestion:
US004: Shopping cart management → Break down into:
- US004-1: Add to cart
- US004-2: View cart
- US004-3: Edit cart item quantity
- US004-4: Delete cart item
Accept the breakdown?
A) Accept the breakdown B) I have another breakdown approach C) No breakdown needed
Step 7: Story priority ranking
Rank based on business value and dependencies:
P0 (Must have): US001 Registration, US002 Login, US006 Product list, US008 Product details, US010 Add to cart, US014 Order creation, US015 Order payment
P1 (Should have): US003 Password recovery, US004 Personal information, US007 Search, US011 Cart editing
P2 (Could have): US008 Favorites, US009 Reviews, US014 Cancel order
Need to adjust priorities?
Step 8: Output user story list
Use the Write tool to create docs/02-方案设计/用户故事清单.md。
Refer to the references/output-template.md template, the document structure is as follows:
- User story overview - Epic list (ID, name, description, Story count, priority, effort)
- Epic details and Story list - Story list under each Epic
- Complete user stories - Complete description of each Story (role, functionality, value, acceptance criteria)
- Story dependency graph - Dependency relationship diagram
- Sprint planning suggestions - Sprint division and effort estimation
- Appendix - User story template, Story Point guide
Fallback mechanism
Scenario 1: No prior document
Provide a manual input mode, allowing users to enter functional requirements one by one.
Scenario 2: User exits midway
Save the list of Stories that have been written to a draft file.
Notes
- INVEST principles: Each Story should be Independent, Negotiable, Valuable, Estimable, Small, and Testable
- Acceptance criteria: Each Story contains at least 1 normal scenario and 1 exception scenario
- Story Point: Use the Fibonacci sequence (1,2,3,5,8,13)
- For the complete output template, see:
references/output-template.md
Output quality comparison
✅ Good example：
- 有数据引用：「根据 Q4 数据，留存率从 35% 降至 28%」
- 有验证来源：「数据来源：Google Analytics, 2025-12-01」
- 有明确建议：「建议将新手引导步骤从 5 步减少至 3 步」
❌ Bad example：
- 模糊结论：「数据表明留存率有所下降」
- 无来源：「根据经验，这个功能很重要」
- 没有行动建议：「留存是个问题」
Common pitfalls / Red Flags — STOP
Stop immediately and backtrack if any of the following occur:
| Pitfall | Correct approach |
|---|---|
| Using "should", "probably", "seems" to draw conclusions | Must be based on actual data and verification |
| Claiming completion without running checks | Verify first, then state |
| Skipping key steps due to time pressure | No exceptions; the tighter the time, the stricter you must be |
| The thought "it should be fine this time" | Re-verify every time |
Output quality check / Verification Checklist
- Prerequisite dependencies are satisfied (input documents/data have been collected)
- All core steps have been executed
- The output document has been generated to the
docs/directory - Every judgment is supported by data/evidence
- 2-3 follow-up skills have been recommended
⚠️ If any item fails → complete it before marking as done.