---
name: plan-feature
description: >
  当用户描述一个新需求、新功能或新模块时使用。
  通过多角度需求澄清 → 人工确认 → 自动产出 PRD 草稿，
  是开发流程的入口编排器，PRD 确认后自动衔接后续 skills。
  触发短语：我有个需求、我想做、新功能、需求分析、帮我规划、
  plan feature、analyze requirement、需求澄清。
  不触发：直接改代码（用 backend-main/frontend-main）、
  仅创建分支（用 start-feature）、仅写文档（用 docs-main）。
---

# plan-feature 技能

## 定位

需求驱动开发流程的**入口编排器**。

核心职责：
1. 先读懂项目现状，自主推断能推断的
2. 把推断不出来的疑问**一次性**列出来问用户
3. 用户回答后产出结构化需求分析摘要
4. 人工确认需求摘要后，自动调用后续 skills 完整跑完开发流程

## 流程

```
用户描述需求
    ↓
第 1 步：读取上下文（AI 自主执行）
    ↓
第 2 步：多角度需求审查 → 生成澄清问题（一次问完）
    ↓
用户回答问题
    ↓
第 3 步：产出需求分析摘要
    ↓
★ 人工确认摘要（唯一 gate）★
    ↓
第 4 步：自动编排后续 skills 完整执行
```

---

## 第 1 步：读取上下文（AI 自主执行，不等用户）

在提问前，先自主读取以下信息，尽量减少问用户的问题：

```bash
# 有哪些已有模块
ls docs/modules/

# 相关模块的 PRD 和数据模型
cat docs/modules/{相关模块}/01-prd.md
cat docs/modules/{相关模块}/06-data-model.md

# 相关模块的 API 定义
cat docs/modules/{相关模块}/07-api.md

# 现有权限/角色体系
grep -r "permission" backend/prisma/schema/ | head -30
```

**原则**：能从文档和代码推断出来的，不问用户。

---

## 第 2 步：多角度需求审查 → 生成澄清问题

### 七个审查维度

对用户描述的需求，从以下每个维度逐一审查，识别真正有歧义或信息不足的点：

#### 维度 1：业务目标与边界
- 这个功能要解决什么问题？谁的问题？
- 当前版本的 in-scope / out-of-scope 边界在哪？
- 成功的标准是什么？（可量化指标）
- 有没有明确不支持的场景？

#### 维度 2：用户与角色
- 哪些角色会用到这个功能？
- 不同角色的权限差异是什么？（谁能看、谁能操作、谁能审批）
- 有没有外部用户（非系统用户）的访问场景？

#### 维度 3：数据与状态
- 涉及哪些数据实体？和现有实体的关系？
- 有没有状态流转？状态可以回退吗？
- 现有数据怎么处理？有没有迁移风险？
- 数据的所有权归属（按组织隔离？按用户隔离？）

#### 维度 4：边界条件与异常场景
- 数据为空时怎么显示/处理？
- 并发操作（同时编辑、同时提交）怎么处理？
- 操作失败的回滚策略？
- 有没有批量操作场景？量级是多少？

#### 维度 5：与现有模块的关系
- 影响哪些已有功能？（读代码推断，确认后再问）
- 有没有需要复用的已有组件/服务？
- 有没有与其他模块的事件联动（触发通知、更新状态等）？

#### 维度 6：非功能性需求
- 有没有性能要求？（数据量级、响应时间）
- 需要审计日志吗？（谁在什么时间做了什么）
- 需要导出/报表功能吗？
- 有没有合规或数据安全要求？

#### 维度 7：交付优先级
- 这个功能的优先级？有没有硬 deadline？
- 有没有可以分阶段交付的拆分方式？
- 哪个子功能是 MVP 必须有的？

### 问题输出格式

对每个维度，只列出**推断不出来、真正有歧义**的问题。已能从代码/文档推断的不列。

输出格式：

```
我已读取 {相关模块} 的文档和代码，以下是我无法自行推断的问题，
请一次性回答，之后我会直接开始执行：

【业务边界】
1. {具体问题}

【角色与权限】
2. {具体问题}

【数据设计】
3. {具体问题}

（没有歧义的维度不列出）
```

**原则**：
- 宁可多问也不要漏问——初始阶段问清楚成本最低
- 但不问能推断的——不让用户重复已知信息
- 一次全部列出，不分多轮

---

## 第 3 步：产出需求分析摘要

用户回答后，整合所有信息，输出结构化摘要：

```markdown
## 需求分析摘要：{功能名称}

### 一句话描述
{用一句话概括这个功能}

### 功能边界
**In-scope**：
- {功能点 1}
- {功能点 2}

**Out-of-scope**：
- {不做的 1}（原因）

### 涉及角色与权限
| 角色 | 可查看 | 可操作 | 可审批 |
|------|:---:|:---:|:---:|
| {角色} | ✓ | ✓ | - |

### 数据影响
- 新增实体：{列表}
- 修改实体：{列表}
- 数据迁移：{有/无，说明}

### 关键边界条件
- {边界 1}
- {边界 2}

### 影响的现有模块
- {模块 1}：{影响说明}

### 非功能性要求
- 审计日志：{是/否}
- 性能要求：{说明或无特殊要求}

### 复杂度评估
- 预计涉及：数据库变更 / 后端 API / 前端页面
- 复杂度：{低/中/高}，原因：{说明}

### 分阶段建议（如适用）
- Phase 1（MVP）：{最小可交付}
- Phase 2：{后续扩展}

---
请确认以上需求分析是否准确？确认后我将开始执行完整开发流程。
```

---

## 第 4 步：人工确认后，自动编排执行

用户确认摘要后，按以下顺序自动调用 skills：

```
1. @start-feature     → 创建 worktree + 分支（如需要）
                         填写 TASK.md（将需求摘要写入背景和目标）
2. @contract-check    → 契约面识别 + 文档对齐状态盘点（决定后续是否需要补文档）
3. @docs-main         → 产出 PRD 全文 + API 草稿 + 数据模型草稿（按 contract-check 缺口补齐）
4. @doc-review        → 4-lens 实现就绪度审查（新模块 / ≥3 份文档大改时强制；🔴 ≤ 1 + 🟡 ≤ 2 才进入下一步）
5. @database-main     → schema 变更 + 迁移
6. @backend-main      → 后端 API 实现
7. @frontend-main     → 前端页面实现
8. @test-main         → 三层测试（L0→L1→L2）
9. @git-main          → 提交、推送、创建 PR
```

**执行规则**：
- 每个 skill 完成后才调用下一个，不并行（保证依赖顺序）
- 如果某一步失败，停下来告知用户，不自动跳过
- `@docs-main` 产出文档后，不需要再次人工确认（已在摘要阶段确认）
- **`@doc-review` 闸门**：新模块 / ≥3 份文档大改时**必跑**。报告中 🔴 数量 ≤ 1 且 🟡 ≤ 2 才允许进入 `@database-main`；否则停下来由用户决策（修文档 / 接受风险 / 收窄范围）。单文档小改可跳过此步。
- 最终 PR 创建完成后，通知用户 review + merge

### 执行前的 worktree 判断

在调用 `@start-feature` 前，按以下标准判断是否需要 worktree：

| 条件 | 建议 |
|------|------|
| 涉及新增模块 | 需要 worktree |
| 涉及数据库 schema 变更 | 需要 worktree |
| 当前分支有未提交改动 | 需要 worktree |
| 小改动（单文件/无 schema 变更）| 当前分支直接开发 |

---

## 适用场景示例

**触发示例**：
```
用户：我想加一个「审批委托」功能，就是当我出差的时候可以把审批权限临时转给同事
AI：触发 plan-feature，读文档→问问题→确认→自动执行
```

**不适用**：
```
用户：帮我修一下登录页的样式   → 直接 frontend-main
用户：把这个 API 的响应加一个字段 → 直接 backend-main
用户：写一下会议模块的文档   → 直接 docs-main
```

---

## 注意事项

- **不要在摘要确认前开始任何实现工作**——哪怕看起来很明确
- **需求有重大歧义时宁可多问一轮**——比在实现到一半时发现方向错了成本低得多
- **每个 skill 执行完都要汇报结果**——不要静默跑完整个链路
- **测试失败时停下来**——不要跳过测试直接创建 PR