改进已有需求/计划/规格文档时…

当用户想改进一份已有的规划文档（需求、计划或规格）时，通过多角色审查发现会影响执行的问题，并在授权范围内修正或返回结构化结果。

适用场景

解决思路

1. 仅当用户想改进已有规划文档时使用；阅读需求、计划或规格，按文档是否能指导正确工作来评判，而不是按细节多少来评判。
2. 先确定目标：帮助作者完成一份可用于开展已商定工作的健全文档。
3. 只找会改变工作结果或实质性阻碍执行的问题，并在已授权范围内解决。
4. 小缺陷若会带来严重后果也要关注；文档已经足够好时不做改动。
5. 将 reviewer personas 仅作为证据来源；最终判断由自己做出。
6. 对照整份文档、项目事实和已定决策核查 persona 的主张。
7. 在 synthesis reference 规定的编辑权限和 reviewer 要求内，修正会阻止既有决策执行的已证实错误。
8. 只返回仍需许可的有价值改进、只有用户能给出的重大选择或必要信息、以及有用观察。
9. 完成标准：每个选中的 reviewer 已返回，或在 Coverage 中记为失败。
10. 完成标准：保留的 finding 对已商定工作有已验证后果。
11. 完成标准：分配给 Apply 的每个授权修正都已执行并检查。
12. 通过交互式 approval/decision 流程报告最终状态；非交互模式返回结构化文本。
13. 交互模式：先读 `references/modes.md`，按其规则检测模式、处理非交互参数契约和问题工具规则。
14. 问题工具：匹配当前工具列表中已有的 host blocking question tool；绝不调用面向用户的问题工具来发现它。
15. 若问题工具已列出但未加载，在交互流程顶部预加载。
16. 仅当 harness 确实没有该工具时，退回编号列表。
17. 需要用户决策的问题必须调用该工具，或大声退回；不能只用纯文本叙述。
18. Artifact Root：仅在无路径交互分支解析 `<root>`，该分支发现 `<root>/plans/` 下最近的 plan。
19. 其他运行一律读取传入路径的文档；绝对路径或非交互审查不依赖 repo root 或不需要的 CE config。
20. 在组装任何 artifact 路径前解析 CE artifact root `<root>`。
21. 只从 `<repo-root>/.compound-engineering/config.yaml` 读取 `docs_root`（`<repo-root>` 由 `git rev-parse --show-toplevel` 得到）；不要从 `config.local.yaml` 读取。
22. 若 `docs_root` 未设置，`<root>` 就是 `docs`，与之前一致。
23. 若设置了，验证其为 repo 相对目录，且真实符号链接解析后的路径仍在 repo 内，既不是 repo root 也不在 `.git/` 下。
24. 验证失败则停止并以错误点名 `docs_root` 和该值；绝不回退到 `docs`。
25. 使用 `<root>` 作为唯一 artifact 位置：不存在就创建，每个路径组装为 `<root>/<subdir>`，并放在本技能自己的子目录；绝不再读 `docs`。
26. Phase 1：读 `references/document-intake.md`，按其处理各模式下文档获取、找不到文档时做什么和说什么、以及分类信号。
27. 分派前验证：每个解析出的路径必须在磁盘上可读。
28. 若有路径不可读，不分派任何 persona；reviewer 从文件系统读取，无法访问只在未检出分支上的路径（issue #925）。
29. 按内容分类，不按 readiness 标签或文件路径分类。
30. 只有 Product Contract 的统一 artifact 归类为 `unified-requirements`；缺实现章节是预期的。
31. 任何实现规划都归类为 `unified-plan`，包括需要审查的不完整或阻塞规划。
32. 其他 artifact 使用旧的 `requirements` / `plan` 拆分。
33. HTML 统一 artifact 走相同路线；每个修复都落到文档原生格式；绝不向 HTML 插入 markdown。
34. 该 reference 覆盖带 ID 的条目；把分类传入每个 persona 的 `{document_type}` 槽位。
35. Phase 2：仅当 `references/document-intake.md` 中的 completed-review reuse 条件通过时跳过 dispatch；带该证据继续 Phase 3。
36. 读 `references/persona-selection.md`，获取每个条件 persona 的激活信号和 announcement 格式。
37. 注意两个信号会在看似可信证据上过度激活：`security-lens-reviewer` 的 sensitive-data bound 和 `adversarial-document-reviewer` 的 challenge-surface bar。
38. 读 `references/dispatch.md`，获取 payload 变量、slicing、模型分层和 reviewer 失败处理。
39. 团队总是包括 `coherence-reviewer` 和 `feasibility-reviewer`，加上每个被激活的条件 persona。
40. 任何 dispatch 前，以逐 persona 理由宣布团队。
41. 通过平台 subagent primitive 以有界并行分派通用 subagent。
42. 给每个 subagent 注入其 `references/personas/<reviewer-name>.md` 的完整内容。
43. 绝不按类型或名称分派 standalone agent。
44. 容量拒绝是 backpressure，不是 reviewer 失败：等待并重试。
45. 若容量无法恢复且选中的 reviewer 仍未分派，按 `references/cross-model-review.md` 收集并清理已启动的 cross-model jobs。
46. 然后以 incomplete 停止：不做 synthesis、不做 fixes、不做 success handoff。
47. 保留已收集结果，并报告哪些 reviewer 完成、失败或无法运行，以及原因。
48. Cross-Model Judgment Pass：若 conditional judgment trio（`adversarial-document-reviewer`、`product-lens-reviewer`、`security-lens-reviewer`）任一被激活，则运行该 pass。
49. 遵循 `references/cross-model-review.md`，它定义整个 pass：确认 host、整份文档使用的一个 target 和 route、任何内容离开机器前的 disclosure、如何启动/收集/合并 peers。
50. 该 pass 是附加且非阻塞的：失败或超时都不停止任何事，并在 Coverage 中点名。
51. 先检查 checkout 的 `cross_model_review_mode` 设置，它可用具名原因跳过该 pass。
52. 仅当 `CROSS_MODEL_PEERS` 设置时过滤接收者；未设置表示不过滤，不是未授权。
53. 绝不静默更改显式 model 或 recipient。
54. Phases 3-5：等待每个已分派 agent 返回，包括任何 cross-model `<reviewer-name>-<provider>.json` 返回。
55. 然后读 `references/synthesis-and-presentation.md`。
56. 按其定义做 synthesis、按 confidence 和 fix class 路由每个 finding、应用修复、生成非交互结果格式、交接到 routing question。
57. 在 promoting agreement 时，只有带 `independence_verified: true` 的 artifact 才算独立 reviewer。
58. 仅交互模式：读 `references/walkthrough.md`，用于 grouped confirmation、routing question、per-finding walk-through。
59. 读 `references/bulk-preview.md`，用于 best-judgment routing 后的 bulk-action preview、Append-to-Open-Questions、auto-resolve。
60. 在 review evidence 完成（新收集或有效复用）前，不加载 walkthrough 和 bulk-preview；非交互运行根本不加载它们，停在结构化 review 结果。
61. 只读当前 review 选中的 persona prompts。
62. 使用 dispatch payload 填充的 template 和 schema：`references/subagent-template.md` 与 `references/findings-schema.json`。

适用边界 · 注意事项

• 不适用于从零撰写需求、计划或规格；它面向改进已有规划文档。
• 不适用于目标文档路径不可读或只存在于未检出分支时继续审查；此时不应分派 persona。
• 不适用于文档已经足够好、无需改动的情况。