| name | brief-generator |
| description | 当用户提出新需求、口头想法、初步框架，或要求"写个 brief / 需求理解 / 业务分析 / 先理清楚需求"时激活；输出面向开发者的 brief.md，覆盖需求摘要、业务流程、涉及模块与影响面（含概念数据模型，但不到物理 schema 与 how）、风险、待确认问题五章；支持开发者审阅后通过对话迭代修订，直到开发者确认冻结，作为后续 acceptance.feature 生成的输入。若用户已基于 brief.md 提出修改、补充、疑问、回答待确认项，继续用本 skill 做迭代收敛。 |
| when_to_use | 在 flow-router 判为 L2/L3 后，或用户直接要求'写个 brief / 写个需求理解 / 搞清楚业务 / 看看影响哪些模块'时激活，把需求收敛成 brief.md。若用户只是抛出一个尚未分诊的改代码诉求（车道未定），应先经 flow-router 判级——判为 L1 的小改动不进本 skill，直接转 implementation-execution。若用户已拿到 brief.md 初稿继续回答待确认问题、补充范围、修正流程、要求继续完善，也继续使用本 skill。若用户已有冻结 brief 并明确要求'生成 acceptance / 生成验收 / 生成 Gherkin / 生成测试场景'，转 acceptance-generator。 |
Brief Generator
1. 定位
本 skill 把开发者的初始需求转化为一份面向另一个开发者的 brief.md。
brief.md 的目标读者是团队成员（包括未来的自己）。读完后应能在脑子里跑通这次需求：
- 做什么、为什么做、不做什么
- 业务流程怎么走（含主路径与关键异常）
- 涉及哪些模块、各自承担什么、复用什么、新增什么
- 哪些风险必须重视、哪些问题必须先确认
它回答"做什么、边界在哪、影响哪些模块、还有什么没定"，供开发者签字确认需求成立且圈定；它不回答"怎么实现"——how 归 technical-design。
它不是：
- 速览摘要——必要内容要写透
- 实现方案——不展开处理步骤、不做技术选型、不写接口字段/类名/方法签名，这些归
technical-design
- PRD 散文——不写产品营销话术、不写"用户体验"等无法验证的说辞
关于数据结构（强制）：凡涉及数据表变更（新增表、增/删/改列、改列语义）或对外消息契约（MQ 消息、关键事件 payload）的需求，brief 必须把变更确定到列级 / 字段级——列出新增表的列清单、改了哪张表的哪些列（含列的业务语义与大致类型）、新增消息的字段清单（字段、必填、来源、用途）。这是界定需求范围与确认数据契约的核心，不下放到 technical-design。
仍归 technical-design + alembic 的，只是更细的物理实现细节：列的精确长度、索引、唯一约束、默认值、外键、迁移顺序与回滚、字段校验规则、类名 / 方法签名。
一句话："动哪张表的哪些列、收发什么消息的哪些字段"在 brief 定死；"这些列在库里具体怎么建、怎么迁"留给 TD。
它的核心特性是可迭代。Agent 首次生成后，开发者审阅、提出疑问或修改意见，Agent 把修订写回原章节（而非追加在末尾），反复直到开发者明确说"冻结"。冻结后删除"待确认问题"章节，进入 acceptance-generator。
2. 触发边界
2.1 适合使用
- 用户口头描述需求、初步想法、粗略框架
- 用户要求"先分析一下"、"写个 brief"、"搞清楚业务"、"看看会影响哪些模块"
- 用户基于已有
brief.md 提出修改、补充、疑问
- 用户回答 brief 中"待确认问题"章节里的某个问题
2.2 不适合使用
- 用户已有冻结的 brief，明确要求"生成 acceptance / 生成 Gherkin / 生成验收"→ 转
acceptance-generator
- 用户已有 brief + acceptance.feature，要求技术方案 → 转
technical-design
- 用户只是要改本 skill 模板或工作规则本身
3. 工作原则
- 面向开发者读，少写说明，多写结论。
- 写到"另一个开发者能在脑子里跑通"为止。第 3 章只到影响面与可行性层，不展开实现步骤与选型；how 留给
technical-design（L3）。
- L2 例外：因 L2 跳过
technical-design，brief 第 3 章追加一个"最小实现思路"附录，够开发者直接编码即可；复杂到要写方法级方案时，说明该升 L3 走 TD，而非把 brief 撑大。
- 数据结构分层：第 3 章对不涉及表变更的实体写概念数据模型（关键实体 / 核心字段 / 关系）即可；但一旦涉及数据表变更或对外消息契约，必须给出列级 / 字段级变更清单（动哪张表的哪些列、收发什么消息的哪些字段）——这是强制项，见第 1 章「关于数据结构（强制）」。更细的物理实现（长度、索引、约束、默认值、迁移顺序）仍归
technical-design + alembic。
- 不预设篇幅上限：简单需求 1 页够，复杂需求 5-8 页合理。篇幅由内容必要性决定，不由模板预算决定。
- 模糊的部分进"待确认问题"章节，不要用"按需处理"、"适当判断"等模糊措辞掩盖。
- 表格只用于高密度清单（如风险表、待确认问题表）；流程详解优先用分步骤叙述。
- 迭代时把修订写回原章节，不要只追加在末尾或新建"修订记录"段落。
- 不暴露 skill 内部机制：状态元信息（草稿/迭代中）、推测/已确认/待确认分类、问答收敛说明、Agent 阅读指令——全部不进文档。
4. 输出位置
固定为：
.specs/<feature-name>/brief.md
要求：
5. 模板
# [需求名] Brief
## 1. 需求摘要
- **做什么**：[1-3 句话描述本次需求要解决的核心问题]
- **为什么做**：[业务动机、问题来源、上游诉求]
- **本次不做**：[明确排除的范围，避免后续扩展]
## 2. 业务流程
### 2.1 主流程图
```mermaid
flowchart TD
A["触发"] --> B["处理"]
B --> C{"判断"}
C -->|是| D["成功路径"]
C -->|否| E["异常处理"]
流程图只画主链路 + 关键异常分支，不要把所有细节塞进图里。
2.2 流程详解
对图中每个关键节点展开：
- 谁触发 / 系统做什么 / 依赖什么
- 状态如何变化 / 数据如何流转
- 用户或下游系统如何感知结果
异常分支单独成段，说明触发条件、影响范围、当前处理策略。
3. 涉及模块与影响面
按模块列出，每个模块独立一段。只到影响面与可行性层（how 归 technical-design）。每段回答：
- 位置：在现有项目的哪个目录 / 层（动不动它）
- 职责：本次承担什么业务责任
- 复用 / 新增：复用哪些现有能力（点名具体模块 / 服务），还是需要新增什么链路（影响面）
- 触碰的公共契约：是否动 ORM 模型 / MQ 消息 / 迁移 / parse_task 状态机 / HTTP 接口 / 错误码（这同时决定车道，是 L3 强信号）
- 关键数据结构：本模块新增 / 改动的关键实体、核心字段、实体关系。若涉及数据表变更或对外消息契约（强制）：用表格给出列级 / 字段级清单——对表写"增/删/改了哪张表的哪些列（列名 + 业务语义 + 大致类型）"，对消息写"字段 + 必填 + 来源 + 用途"。不涉及表/消息变更的实体到概念级即可。更细的物理实现（长度 / 索引 / 约束 / 默认值 / 迁移顺序）归
technical-design。
- 可行性与不确定性：实现上有没有坑 → 未定项写进第 5 章"待确认问题"
关于决策的归属：改变范围 / 用户拿到什么的决策留在本章（未定则进待确认）；纯实现取舍（如异步 vs 同步、MQ vs 轮询的技术选型）下沉 technical-design。
（仅 L2）最小实现思路：L2 不走 TD，本章末追加一段够开发者直接编码的实现要点（复用什么、新增什么链路、状态/数据如何流动）。但仍不写物理 schema / 类名 / 方法签名；复杂到要写方法级方案，说明该升 L3。
4. 风险与不确定性
| 风险 / 问题 | 触发条件 | 影响 | 当前判断 / 应对方向 |
|---|
| [具体场景] | [何时发生] | [对谁、对什么] | [当前思路或"待确认"] |
不写"需要注意稳定性"、"可能有性能问题"这种泛泛的话。每条要落到具体场景。
5. 待确认问题
仅在迭代期使用。所有问题收敛后，整章删除，不进入冻结版。
| 编号 | 问题 | 为什么影响判断 | 阻塞级别 |
|---|
| Q1 | [具体问题] | [影响哪个流程 / 模块 / 决策] | 阻塞 / 影响范围 / 可后置 |
## 6. 工作流程
### 步骤 1：理解原始需求
- 保留用户原话的关键信息
- 用 1-3 句整理成开发者能理解的描述
- 提炼核心目标、范围、非目标
- 标出明显缺失的信息
### 步骤 2：读取项目上下文
按需求关键词，最小化探索：
- README、已有同业务域的 brief / technical_design
- 相关模块目录、入口文件、状态枚举、消息契约
- 公共契约（`docs/api/**`、`docs/internals/naming_conventions.md` 等）
不做完整代码审查，**只读到能支撑模块草图为止**。不要把"读到了什么文件"写成独立章节，转化为对模块归属、复用边界的具体判断。
### 步骤 3：生成 brief 初稿
按模板 5 章生成。原则：
- 第 2 章业务流程要覆盖主链路 + 关键异常
- 第 3 章核心模块要写透实现思路（位置、职责、复用、新增、决策）
- 第 4 章风险写具体场景
- 第 5 章把所有不确定的、影响后续决策的问题列出
### 步骤 4：迭代收敛
进入开发者审阅—Agent 修订循环：
1. 把初稿展示给用户。
2. 默认聚焦"待确认问题"中 1 个最阻塞的问题向用户提问；同时罗列完整待确认清单。
3. 用户回答 / 提出修改 / 指出错误后：
- **读取当前 brief.md**（不要凭记忆）
- 把确认信息**回写到正文对应章节**（摘要 / 流程 / 模块 / 风险）
- 把已确认的问题从"待确认问题"删除
- 如果用户回答引入新问题或与旧结论冲突，把冲突加入"待确认问题"并标注来源
4. 不在文档中保留"问答记录"、"迭代记录"等过程章节。
5. 持续直到：
- 用户明确说"冻结" / "OK 这版可以" / "进入下一阶段"
- 或所有阻塞性问题已收敛
### 步骤 5：冻结
冻结时：
1. 删除"待确认问题"章节（如果还有非阻塞性的，需用户确认后保留或删除）
2. 回写 `state.yaml`：把 `artifacts.brief.frozen` 置为 `true`，`phase` 推进到 `acceptance`。冻结是被记录、被校验的显式动作——下游 `acceptance-generator` 会用 `flow-guard.py` 校验本字段。
3. 告知用户下一步：进入 `acceptance-generator` 生成 acceptance.feature
## 7. 输出质量标准
合格的 `brief.md` 必须做到：
- 另一个开发者读完不需要追问就能进入下一阶段
- 业务流程能在脑子里跑通，含关键异常
- 每个模块都有"位置 + 职责 + 复用/新增 + 触碰契约 + 关键数据结构 + 不确定性"
- **涉及数据表 / 对外消息契约变更的，已给出列级 / 字段级清单**（动哪张表的哪些列、收发什么消息的哪些字段）——这是冻结的硬门槛
- 风险落到具体场景，不是泛泛的"注意稳定性"
- 没有任何模糊措辞（"按需"、"适当"、"完善"、"相关逻辑"）
- 不含 skill 内部机制说明、状态元信息、问答过程记录
不合格的信号：
- 篇幅过短，模块章节只有 1-2 行
- 流程描述跳跃，关键步骤缺失
- 模块章节只写"做 X"，没写"在哪里、复用还是新增、触碰哪些契约、有无不确定"
- **涉及表变更 / 消息契约却只写概念级、没落到列级 / 字段级清单**（缺这一项不得冻结）
- 越界写了纯物理实现细节（索引 / 唯一约束 / 默认值 / 外键 / 迁移顺序 / 回滚）、类名、方法签名等 how（列级变更清单与 L2 最小实现思路除外）
- 风险表用泛泛措辞
- 出现"用户体验"、"系统应正确处理"等无法验证的描述
## 8. 与其他 skill 的衔接
- **进入前**：`flow-router` 判为 L2/L3，或用户直接要求写 brief（L1 小改动不进本 skill，由 flow-router 直转 implementation-execution）
- **车道差异**：L3 的第 3 章到影响面 + 表/消息列级契约（更细物理实现由 TD 承接）；L2 跳过 `technical-design`，第 3 章含"最小实现思路"附录，冻结后直接进编码
- **冻结后**：转入 `acceptance-generator` 生成 Gherkin 验收契约
- **不允许**：未经冻结直接跳到 `technical-design`；涉及表/消息变更却没在 brief 定到列级 / 字段级就冻结；在 brief 阶段写纯物理实现细节（索引/约束/迁移顺序）或类名/方法签名等代码层 how（列级变更清单与 L2 最小实现思路除外）
