| name | revise |
| description | 产出修订（诊断→定向修正→回归验证）——对 spec→plan→exec 偏差做根因归类：spec-defect / impl-defect / requirement-change；先诊断再修正、改代码必先 Red 测试、最小影响只改必须改的层；已完成 plan 是历史审计快照禁止回改；启动先 worktree 感知定位修复现场（主仓库停在 main 时自动定位到进行中的 worktree）。触发：/revise、有 bug、结果不对、和预期不符、产出需要优化、review 发现违规需修复。跳过：纯新增需求（→/spec→/plan）、还没有 spec/plan/代码可对照。 |
产出修订（Revise）：诊断 → 定向修正 → 回归验证
对 spec→plan→exec 流水线产出与预期的偏差做根因归类 → 定向修正 → 回归验证，覆盖修 bug、产出优化、需求变更三类场景。所有 review 发现问题需修正时，统一走此流程。
仅处理"对既有产出的修正"。与对错无关的纯新增需求走 /spec → /plan，不进本流程。
核心原则（兼硬约束）
- 先诊断再修正：禁止跳过归因直接改代码；诊断结果必须向用户通报（不阻断——通报后直接进入步骤 3），仅当代码/spec 存在方向分歧、需附「冲突分析简报」时停下等用户裁决方向
- 三类归因：每个问题必须归入 spec-defect / impl-defect / requirement-change 之一
- TDD 修正：涉及代码修改时必须先有失败测试（Red）再改实现（Green），测试须能暴露 bug
- 分层修复起点：spec-defect 必先改 spec 再改代码（禁只改代码不改 spec）；requirement-change 必先用户确认新需求再动手
- 修正闭环：修正后必须验证——全量测试通过 + spec 合规 + 索引同步
- 最小影响：只改必须改的层，不借修正之名扩展功能或重构（额外需求走
/spec → /plan）
- 已完成 plan 禁止回改：PROGRESS.md 全部完成的 plan 是带日期的历史审计快照，回改即篡改记录（目录日期与内容脱节、"完成的是哪个版本"不可追溯）；仅进行中（PROGRESS.md 未全完成）的 plan 允许原地修正以保证断点续接。修复本身由本流程直接驱动，git commit 即修订记录
- 三 Agent 串行强制派发：涉及代码修改时必须按 Test → Impl → Review 顺序派
bb-spec-test-engineer / bb-spec-impl-engineer / bb-spec-spec-reviewer 三个 subagent，禁止主 agent 自己写测试、写实现、做 spec 合规检查；唯一例外是「轻量修复判断」（见步骤 3）通过且用户同意后允许主 agent 直接 TDD 修复
- Agent 隔离同 exec：Test 不看实现，Impl 不看 spec，Review 只读不写
- 输出中文
三类归因
| 类型 | 含义 | 根因在哪层 | 修复起点 |
|---|
| spec-defect | spec/plan 没有正确描述预期行为 | 定义层 | 改 spec → 级联 plan → TDD 重新实现 |
| impl-defect | spec 正确，实现不符合 | 实现层 | 补测试(Red) → 改实现(Green) → 验证 |
| requirement-change | 用户实际需要与现有 spec 不同 | 需求层 | 确认新需求 → 改 spec → 级联 |
工作流
步骤 0：收集问题信息
有参数（$ARGUMENTS 非空）：直接使用用户传入的问题/优化描述。
无参数：向用户提问（一次 2-3 个）——预期行为是什么？实际行为是什么？在哪个场景/功能下出现？
步骤 1：定位修复现场 + 读取配置 + 定位关联资产
先定位修复现场（worktree 感知）：主仓库目录常年停在 main，进行中的功能分支可能在 ~/.bb-spec/worktrees/ 下的某棵 worktree 里。读任何资产前先跑 git branch --show-current + git worktree list --porcelain：
- 已在 linked worktree 或非 main/master 功能分支 → cwd 即修复现场，继续
- 在主仓库且 HEAD 为 main/master，且问题指向某棵 worktree 上进行中的工作（其 plan PROGRESS.md 未全完成，或分支领先 main）→ 后续读资产、修代码、跑测试、commit 全部定位到该 worktree 内执行（
cd 进去或全程用其绝对路径）；多棵候选 → question 工具 让用户选
- 问题针对 main 上已合入的代码 → 属新修复任务，按 git-workflow 先确定开分支方式再动手，禁止直接在 main 工作区改代码
现场确定后，在该目录下 cat .bb-spec.yaml 2>/dev/null 取 base_dir（缺省 .bb-spec）；${DOCS_DIR} = <base_dir>/docs，后续所有路径基于此值。读 ${DOCS_DIR}/spec/INDEX.md 与 ${DOCS_DIR}/plan/INDEX.md，据问题描述定位四层资产并全部读取：
| 资产 | 定位方式 | 目的 |
|---|
| spec 文件 | INDEX.md + 关键词匹配 | 确认"期望行为"的定义 |
| plan 文件 | INDEX.md + spec 溯源 | 确认"怎么做"的设计 |
| 实现代码 | plan 中的文件路径 / codegraph | 确认"实际做了什么" |
| 测试文件 | 测试目录 + 命名惯例 | 确认"验了什么" |
建立完整链路：spec 说什么 → plan 怎么做 → 代码做了什么 → 测试验了什么。
流程归属判定（不论单 repo 还是多 repo，进步骤 2 前必做）：确认本次问题真属于 revise（"对既有产出做已知偏差的定向修正"）。满足以下任一条件应退出 revise，转 /spec → /plan → /exec：
- 需要先拆解、协商或定义新协议才能落地（如"做快 auth 流程"、"打通 X 服务可观测性"、跨服务通信契约调整）
- 单 repo 但变更面横跨多个 spec/plan 域且涉及新设计决策
- 跨 ≥ 2 个 repo 且不止是被动跟随的机械级联（proto 字段改名后 consumer 跟着改属机械级联，反之属协调式）
判定退出时必须停下，提示用户改走 /spec，禁继续 revise 流程。
步骤 2：诊断归因
按决策树逐层判定：
1. spec 是否正确描述了预期行为？
├─ 否 → spec 规则本身有错误/遗漏/歧义？
│ ├─ 是（spec 翻译需求时出错）→ spec-defect
│ └─ 否（用户的实际需求变了）→ requirement-change
└─ 是 →
2. plan 是否正确翻译了 spec？
├─ 否（plan 误读 spec）→ spec-defect
└─ 是 →
3. 实现是否符合 plan + spec？
├─ 否 → impl-defect
└─ 是 →
4. 测试是否覆盖了出问题的场景？
├─ 否（测试遗漏）→ impl-defect
└─ 是（测试断言有误）→ impl-defect
向用户通报诊断结果（诊断本身不阻断——展示后直接进入步骤 3；仅当代码/spec 存在方向分歧、附下方「冲突分析简报」时才停下等用户裁决方向。用户对归因有异议可随时打断，无异议即默认继续）：
## 诊断结果
- 归因：<spec-defect / impl-defect / requirement-change>
- 证据：spec 说<原文> / plan 说<原文> / 代码做了<实际行为> / 测试验了<覆盖情况>
- 结论：<一句话说明哪层出了什么问题>
- 影响范围：<受影响的文件/功能列表>
冲突分析简报（代码行为与 spec 定义存在可争议分歧时，附在诊断后辅助用户判断方向；明确的实现 bug 无需此简报）：
## 冲突分析：<一句话描述>
| | 代码现状 | Spec 定义 |
|---|---|---|
| 行为 | <代码实际做了什么> | <spec 要求做什么> |
- 保留代码（改 Spec）：<理由——如代码已上线验证、覆盖了 spec 遗漏的边界、性能更优>
- 遵循 Spec（改代码）：<理由——如更贴合业务意图、更安全、当前代码是历史妥协>
- **建议**：<推荐方向> — <一句话理由>
- **代价**：<选该方向的改动范围与风险>
确认修复方向后开始修复？
步骤 3：按类型修复
强制派发：所有涉及代码修改的修复路径（除下方「轻量修复判断」通过外）必须通过 task 工具派 bb-spec-test-engineer → bb-spec-impl-engineer → bb-spec-spec-reviewer 三个 subagent 串行完成，禁止主 agent 直接动手写测试或实现代码。主 agent 仅做：拆分输入、按隔离矩阵传 prompt、验证每步产物、衔接下一步。
多 repo 派发节律（修复涉及 ≥ 2 个 repo 时适用）：以「单 repo 的 spec/code/test 链路」为最小派发单元，按 repo 顺序逐个走完整 Test→Impl→Review 循环，禁止把多 repo 路径塞进一个 subagent——测试惯例、spec 目录、项目约束在 repo 维度才一致，跨 repo 混传会破坏隔离矩阵。每个 repo 完成后再进入下一个，全部完成后才进入步骤 4 回归验证。
轻量修复判断：进入修复前评估改动规模，同时满足全部条件时可向用户提议跳过 3-Agent 隔离直接修——归因为 impl-defect（spec/plan 无需变动）+ 改动 ≤ 1 个文件 ≤ 10 行 + 修复逻辑显而易见（拼写错误、off-by-one、条件取反）。
提议话术："这个修复只改 <文件>，约 <N> 行，是否跳过 3-Agent 隔离直接修？"
- 同意 → 主 agent 直接 TDD 修复（仍须先补失败测试再改实现），跳过 3a/3b/3c 的 Agent 派发；修代码前必须调用
Skill code-constraints 加载代码纪律约束并严格遵守（注释 WHY 不写 WHAT、禁 spec 溯源注释、禁未要求的功能/抽象/防御、外科手术式改动、反历史包袱）
- 拒绝或未回应 → 走标准流程
不满足上述条件时，禁止提议跳过，直接走标准流程。
3a. spec-defect — 定义层出错，从 spec 起向下级联
- 改 spec：编辑 spec 文件修正规则（遵守 spec skill 变更判定：修改=编辑原文件，废弃=删文件 + 移除索引条目）
- 检查 plan 影响（先看 plan 状态再动手）：
- 进行中（PROGRESS.md 未全完成）→ 原地修正对应 plan 的业务规则/验证方式，保证断点续接正确
- 已完成（PROGRESS.md 全部完成）→ 不改 plan，spec 层修正照常、修复由本流程三 Agent 直接驱动；若偏差大到需要一份新实施计划，按步骤 1 流程归属判定退出转
/spec → /plan
- 无影响则跳过
- TDD 修复实现（强制三 Agent 派发）：
- 派
bb-spec-test-engineer，prompt 传「修正后的 spec 业务规则 + 验证预期 + 项目测试惯例」→ 主 agent 验证 Red
- 派
bb-spec-impl-engineer，prompt 传「函数清单 + 文件路径 + 测试文件路径 + 项目约束」→ 主 agent 验证 Green
- 派
bb-spec-spec-reviewer，prompt 传「业务规则 + 验证预期 + 所有变更文件路径」→ 主 agent 处理 review 结果
- 同步索引：spec/plan 的 INDEX.md 如有变动则更新
3b. impl-defect — spec 正确，只修实现层（强制三 Agent 派发）
- 派
bb-spec-test-engineer，prompt 传「被违反的 spec 规则 + 验证预期 + 项目测试惯例」→ 主 agent 验证测试能暴露 bug（Red）
- 派
bb-spec-impl-engineer，prompt 传「函数清单 + 文件路径 + 测试文件 + 项目约束」→ 主 agent 验证 Green
- 派
bb-spec-spec-reviewer，prompt 传「spec 规则 + 验证预期 + 所有变更文件路径」→ 主 agent 处理 review 结果
3c. requirement-change — 需求层变化，先确认再级联
- 确认新需求：与用户对话明确新预期行为（一次 2-3 个关键问题）
- 更新 spec：走 spec 变更流程（编辑/新增/删除 spec 文件 + 同步 INDEX.md）
- 评估级联影响：检查哪些 plan 和实现受影响，向用户展示范围
- 级联修复：按 3a 步骤 2-4 执行（改 plan → 三 Agent 派发 TDD 修实现 → Review 验证）
步骤 4：回归验证
- 全量测试：运行项目全量测试，确认无回归
- spec 合规：检查修复是否引入新的 spec 违规
- 索引同步：确认 spec/plan INDEX.md 与文件实际状态一致
- 本地 commit：上述通过后做一次本地 commit——先
git branch --show-current 确认分支（在 main 上则跳过并提示按 git-workflow 先建分支），只提交本次涉及文件（spec/plan/实现/测试），message 遵循仓库历史风格（先 git log --oneline -10）、不硬编码类型前缀，仅本地、不自动 push
步骤 5：完成简报
## 修订完成简报
- 归因：<spec-defect / impl-defect / requirement-change>
- 根因：<一句话>
- 修改文件：spec / plan / 实现 / 测试（各列路径，无则省略）
- 测试结果：✅ 全部通过 / ❌ 仍有失败（列出）
- 回归检查：✅ 无回归 / ⚠️ <说明>
- 待解决：<残留问题列表，无则"无">
- 下一步：<如"运行 /review 复查" / "无">
Agent 隔离规则
修复阶段复用 exec 的三 Agent 隔离，信息边界不变：
| Agent | 可见 | 不可见 |
|---|
| Test Agent | 修正后的 spec 规则 + 验证预期 + 项目测试惯例 | 函数清单、实现路径、现有实现代码 |
| Impl Agent | 函数清单 + 文件路径 + 成品定义（如有）+ 测试文件 + 项目约束 | spec 原文 |
| Review Agent | spec 规则 + 验证预期 + 所有变更文件 | 不修改任何文件 |
