| name | prd |
| description | PRD 头脑风暴与文档化——质疑→发散→收敛→产出 PRD；每个需求一个目录（不论大小）：OVERVIEW.md（背景/目标/子需求索引/整体端到端验证路径）+ 一份或多份小巧子需求文档（用户故事/用例/验收/子验证路径）+（如有）GLOSSARY.md 术语增量，互不引用、便于 agent 按需读取；术语只读复用 spec/GLOSSARY.md 权威源、新术语/新别名与用户对齐后随目录交付；写入 .bb-spec/docs/prd/ 供 /spec 消费，禁写技术方案。触发：/prd、头脑风暴需求、把想法整理成需求文档、拆解需求、写个 PRD。跳过：已有 spec 想改细节（→/revise）、纯技术方案讨论、要写实施计划（→/plan）。 |
PRD 需求头脑风暴与文档化
把模糊想法通过对话质疑 → 发散 → 收敛 → 文档化，产出一个工程师拿到就能跑 /spec 的 PRD 目录。
核心原则
- 质疑前置：先评判需求是否值得做，再讨论怎么做；结论允许是"不值得做"
- 锚定问题不锚定功能：PRD 围绕"谁的什么问题"展开，功能只是手段
- 禁写技术方案：不指定架构 / 库 / 表结构 / API 形态；技术疑问显式写进"开放问题"留给工程师——这是 PRD 与 spec 的边界线
- 用例必须具体可判定：有具体人物、具体操作序列、具体数据、明确预期结果；禁止"用户正常使用后得到正确结果"类空转描述
- 验证双层且可验证：每条用户故事配可验证验收；每个子需求文档末尾给该子需求的端到端验证路径，OVERVIEW 给跨子需求的整体验证路径——均须有序、可观察、从用户视角走完即证明功能达成，保持黑盒（用户可见行为），禁混入技术 / 测试步骤。禁止"好用 / 流畅 / 高性能"类无判定标准的表述
- 每个需求一个目录（不论大小）：一律产出目录
<主题>/，含 OVERVIEW.md（总览 + 子需求索引 + 整体验证路径）+ 一份或多份子需求文档 +（如有术语增量）GLOSSARY.md；每份子文档只讲一个子需求、保持小巧，方便 agent 按需读取；子文档之间互不引用，共享框架（背景 / 目标 / 非目标）统一由 OVERVIEW 承载、子文档不重复
- 自包含快照 + 消费后归档：PRD 是一次性需求快照，被
/spec 消费后由 /spec 把整个目录 git mv 到 ${DOCS_DIR}/prd/.archive/ 不再维护——规则现态由 spec 承载，不引入双源头；活动 PRD 与已归档 PRD 在目录层物理分离（.archive/ 一眼可辨为历史），决策记录 / 否决理由仍可追溯；以目录为自包含单元，读 OVERVIEW 即可索引全貌，不依赖目录外的链接
- 语言跟随用户：正文用用户的工作语言；产品术语用 GLOSSARY 登记的当前工作语言别名统一写法（未登记的按需对齐后使用），角色名保持用户原文
- 术语只读权威源、增量随目录交付：
${DOCS_DIR}/spec/GLOSSARY.md（英文锚点 + 可判定定义 + 多语言别名）是全项目术语唯一权威源，/prd 只读、禁写 spec/ 下任何文件；讨论与产出优先复用已登记术语；全新术语、或已登记术语缺当前工作语言别名时，与用户对齐后写入本 PRD 目录的 GLOSSARY.md（只装增量），由 /spec 消费时合入权威源；用户输入中混用的多语言写法（如同句出现「订单」与「注文」）一律经锚点归一理解，产出文档内同一术语只用当前工作语言的登记别名一种写法
工作流
步骤 0：读取配置 + 盘点既有能力与 PRD（冲突/重叠扫描）
cat .bb-spec.yaml 2>/dev/null
有 base_dir → 用其值作为 bb-spec 根目录；文件不存在或无该字段 → 缺省 .bb-spec。${DOCS_DIR} = <base_dir>/docs（spec / plan / prd / test 等交付物均在其下）。
并行扫描两个来源，建立"系统现态"视图：
cat ${DOCS_DIR}/spec/INDEX.md 2>/dev/null
cat ${DOCS_DIR}/spec/GLOSSARY.md 2>/dev/null
ls ${DOCS_DIR}/prd/ 2>/dev/null | grep -v '^\.archive$'
冲突/重叠判定（结合本次主题逐项过）：
- 重复：已有 spec 描述了同样能力 / 已有 PRD 覆盖了同一问题 → 不该再开 PRD，引导用户走
/revise 或追加用例
- 扩展：与既有 PRD 同主题但范围不同 → 问用户：修订原 PRD 目录，还是新建？
- 冲突：与既有 spec / PRD 的目标 / 约束相左（如默认行为反转、非目标互斥）→ 显式列出冲突点，先与用户裁决方向再继续
- 独立：无相关项 → 直接进入步骤 1
对用户呈现（即便无冲突也要简报，证明已检查）：
## 现态扫描
- 相关 spec：<INDEX 中相关条目，或"无">
- 相关 PRD：<目录名 + 一句话主题，或"无">
- 判定：<重复 / 扩展 / 冲突 / 独立> — <一句话说明>
- 建议：<走 /revise / 修订原目录 / 新建并裁决冲突 / 继续新建>
无 spec/INDEX.md 且无既有 PRD → 简报写"项目尚无 spec 与 PRD，按新建处理"后继续。
步骤 1：意图定性
用一句话复述要解决的问题（不是功能描述）让用户确认。例：用户说"我要一个导出按钮"，复述应是"运营每周要手工整理报表数据，耗时且易错——对吗？"
步骤 2：质疑（对用户可见）
逐项追问并呈现判断：
- 这解决谁的什么问题？有真实场景或证据吗？
- 不做会怎样？严重程度如何？
- 有没有更便宜的替代——现有功能、人工流程、买现成的？
判断"不值得做"或"有更便宜替代" → 输出一段否决理由并结束，不强行产出文档。用户坚持 → 把质疑结论记入 OVERVIEW 的"决策记录"后继续。
步骤 3：发散（头脑风暴）
- 枚举用户故事：覆盖所有受影响角色，不只主角色
- 主动补充用户没想到的：边界场景、异常路径、与既有功能的交互
- 提问前先自查：能从既有 spec 与活动 PRD（步骤 0 已扫描）得出答案的，呈现"结论 + 依据"请用户确认，不开放式提问；系统现态一律以 spec 文档为准，不查代码（保持黑盒）
- 术语随用随对齐：触及 GLOSSARY 已登记术语 → 沿用其定义与别名；全新术语、或已登记术语缺当前工作语言写法 → 用
question 工具 与用户对齐定义/写法（禁自行翻译不经确认），记入术语增量待步骤 5 落盘；只对齐本次实际触及的术语，不做全量批量对照
- 分歧点用
question 工具 逐项收集裁决，禁止脑补替用户决定
- 每次
question 提问给 1-3 候选 + 标记推荐项，让用户从"想答案"降到"判断接受 / 微调"：
- 选项名写具体行为，禁用抽象词（❌ "标准 / 灵活" ✅ "导出后默认下载 CSV"）
- 所有选项用同一组维度描述（行为 / 代价 / 适用场景），便于横向对比
- 推荐项前缀
✅ + 一句根因式理由（为什么是它，不是它有什么优点）
- 行为相近时显式写"差异仅在 X"
步骤 4：收敛
- 钉死目标与非目标（非目标防 scope 蔓延，必须显式列出）
- 用户故事标优先级 P0 / P1 / P2；P0 = 缺了它需求不成立
- 每条 P0 故事至少一个主路径用例，边界 / 异常用例按需补充
- 每条故事配可验证的验收标准
- 头脑风暴中被否决的方向连同理由记入"决策记录"，防止后续重复讨论
- 按子需求切分：把需求拆成一个或多个子需求（一个子需求 = 一条可独立成立 / 可分别交付的能力线），每个子需求一份文档；只有一条能力线时就一份子文档。先与用户对齐切分方案（子需求清单 + 依赖与交付顺序）
- 提炼验证路径：为每个子需求提炼其端到端验证路径；为整体提炼一条跨子需求的整体验证路径——这是 PRD 交付的"功能验证逻辑"，保持黑盒、有序、可观察，禁混入技术 / 测试步骤
步骤 5：产出 + 自检
一律落到目录（不论大小）${DOCS_DIR}/prd/<YYYY-MM-DD>.<主题>/（主题用 kebab-case）：
- 写
OVERVIEW.md：背景与问题、目标、非目标、子需求清单（索引）、依赖与交付顺序、整体端到端验证路径、开放问题、决策记录
- 为每个子需求写
<序号>-<子需求>.md（01-、02-…，子需求名 kebab-case）：用户故事 + 用例 + 验收 + 该子需求端到端验证路径 +（如有）子需求级开放问题
- 有术语增量时写
GLOSSARY.md：全新术语一行（锚点 + 可判定定义 + 本语言别名）、既有术语补别名一行（锚点 + 新别名，定义列写 —、以权威源为准）；已完整登记的术语不重复登记；无增量则不产出此文件
自检清单：
步骤 6：完成简报
## PRD 完成简报
- 产出目录：<prd/<YYYY-MM-DD>.<主题>/>
- 文件：OVERVIEW.md + N 份子需求文档
- OVERVIEW.md — 总览与整体验证路径
- 01-<子需求>.md — <一句话>
- 结论：<值得做 / 用户坚持（质疑结论已记录） / 否决（未产出文档）>
- 用户故事：P0 × N / P1 × M / P2 × K
- 验证路径：整体 1 条 + 子需求各 1 条
- 术语增量：新术语 X 条 / 新别名 Y 条（无则写"无"）
- 开放问题：<X 项，留给工程师评估>
- 下一步：把该目录交给工程师，放入项目 `${DOCS_DIR}/prd/` 后运行 `/spec` 消费
模板
OVERVIEW.md（目录入口，始终存在）
---
name: <kebab-case，与目录主题一致>
description: <一句话，≤ 80 字>
date: <YYYY-MM-DD>
---
# <需求标题>
## 背景与问题
<谁、在什么场景、遇到什么问题、现在怎么应对、痛点在哪。>
## 目标
- <可衡量的目标>
## 非目标
- <明确不做的事>
## 子需求清单（索引）
| 序号 | 子需求 | 解决的子问题 | 优先级 |
|---|---|---|---|
| 01 | [<子需求>](01-<子需求>.md) | <一句话> | P0 |
| 02 | [<子需求>](02-<子需求>.md) | <一句话> | P1 |
## 依赖与交付顺序
<子需求间依赖与建议交付顺序，如 01 → {02, 03 可并行} → 04；仅一个子需求时写"单一子需求，无依赖"。>
## 整体验证路径（端到端）
<一条有序、可观察、可判定的步骤序列，覆盖各子需求合起来后的端到端行为；保持黑盒，全绿即证明整个需求解决了背景问题。>
1. <操作 → 可判定结果>
2. <操作 → 可判定结果>
## 开放问题（留给工程师评估）
- <技术可行性 / 成本 / 依赖等待评估项>
## 决策记录
- <切分方式、被否决方向及理由；质疑环节的结论>
子需求文档 <序号>-<子需求>.md（一个子需求一份，≥1）
---
name: <kebab-case，与文件名一致>
description: <一句话，≤ 80 字>
date: <YYYY-MM-DD>
---
# <子需求标题>
## 用户故事
### P0：作为 <角色>，我想要 <能力>，以便 <价值>
**用例（主路径）**
- 场景：<具体人物在具体情境下>
- 操作：<一步步做了什么，含具体输入 / 数据>
- 预期：<可判定的具体结果>
**用例（边界 / 异常，按需）**
- 场景 / 操作 / 预期 同上
**验收**
- [ ] <可验证项>
## 验证路径（端到端）
<本子需求的有序、可观察、可判定步骤序列，从用户视角走完即证明该子需求达成；保持黑盒。>
1. <操作 → 可判定结果>
2. <操作 → 可判定结果>
## 开放问题（如有，限本子需求）
- <技术可行性 / 成本 / 依赖等待评估项>
GLOSSARY.md（术语增量，仅有新术语/新别名时产出）
# 术语增量
> 本需求新引入或补充别名的术语，由 /spec 消费时合入 spec/GLOSSARY.md。
| 锚点 | 定义 | 别名 |
|---|---|---|
| <english-anchor> | <可判定的定义；仅补别名时写 —，定义以权威源为准> | <语言>「<写法>」；<语言>「<写法>」 |
