brief-generator

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

要求：

• .specs/ 整目录已 git-ignored，是 feature 临时工作目录；详见 .specs/README.md。
• feature 名称使用英文 kebab-case，与 .specs/ 目录约定一致。
• 若用户未提供 feature 名称，从需求内容提取候选并向用户确认后再创建目录。
• 首次创建目录时，用脚本初始化机器拥有的阶段状态文件 state.yaml（取代旧的手维护 feature_info.md）：

  python scripts/acceptance/flow-guard.py init <feature-name> --lane <L2|L3>
  

  该文件由 scripts/acceptance/flow-guard.py 校验，记录 phase、各 artifact 的 frozen、verified 等阶段不变量；人类可读的产物清单 / 推荐阅读顺序写入其 notes 字段。不再手维护 feature_info.md。
• 若目录已存在 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 最小实现思路除外）