Review Spec

Review Spec

从问题定义、需求决策和系统事实三个层面审查已有 spec。把 spec 自检当作基线，不要只做文案或结构检查。

调度 reviewer

默认把审查委派给一个专用 subagent；主 agent 负责确定输入和返回最终报告，不在 subagent 之外并行执行第二份审查。

1. 在委派前确定唯一 spec，并解析为绝对路径。存在多个候选文件且用户没有指明时，先让用户选择。
2. 向 reviewer 明确传入：
   • spec_path：spec 的绝对路径；
   • repository_root：相关仓库的绝对路径；
   • source_conversation：产生该 spec 的完整需求对话，或 reviewer 能访问的原始对话位置与覆盖范围；
   • evidence_limits：已知缺失的对话、代码或文档证据。
3. 按运行环境委派：
   • Codex：调用 spawn_agent。
     • 如果产生该 spec 的完整需求对话就在当前线程上下文中，使用 fork_context: true，并在 prompt 的 source_conversation 中明确覆盖范围。
     • 如果只能提供部分对话，或需要严格限制上下文，使用 fork_context: false，把可用的 source_conversation 和 evidence_limits 完整写入 prompt；不要假装 reviewer 看到了缺失的对话。
     • Codex 下固定传 model: "gpt-6-astra" 和 reasoning_effort: "high"，即使当前会话模型不同也不能省略 model 或让 reviewer 继承父模型。
     • agents/openai.yaml 只提供 UI 元数据；reviewer 模型由 spawn_agent.model 指定。
   • 非 Codex：使用当前环境原生的 subagent 机制，不传入 Codex 专用模型名或参数。
4. reviewer prompt 必须要求：读取 spec_path 指向的文件，遵循本 skill 的审查契约，只返回 reviewer 结果（Findings、证据缺口和总体建议），不输出主 agent 的最终报告表格、执行方式或降级说明，不修改任何文件，也不进入 scope、计划或实施。
5. 当前环境没有 subagent 能力、委派失败或无法启动 reviewer 时，由当前 agent 降级执行完整审查。降级报告必须在“审查概览”中明确写出 执行方式：当前 agent 降级审查（原因：<原因>），并照常列出证据边界；不要静默降级。

主 agent 与 reviewer 的输出边界

• reviewer 成功启动且主 agent 收到 reviewer 的最终结果时，主 agent 必须将执行方式记为 专用 subagent；不能因为 reviewer 没有自行填写执行方式，或因为当前 agent 没有再次调用 spawn_agent，就改写成降级审查。
• 只有没有发起委派、委派调用失败、reviewer 无法启动，或没有收到 reviewer 的最终结果时，主 agent 才能执行降级审查；降级原因必须对应实际发生的阶段，不要笼统写成“没有可用的 spawn_agent”。
• 主 agent 负责把 reviewer 结果汇总成最终报告、统计 P0/P1/P2、补齐输入和证据边界；不要把 reviewer 的输出协议当成最终报告协议，也不要在 reviewer 之外并行执行第二份完整审查。

审查契约

• 只输出审查意见，不修改 spec 或其他文件。
• 把结论作为建议，不设置通过门槛，不阻止用户进入后续流程。
• 把用户明确确认的内容视为需求依据。不要把助手提出但用户未接受的建议、示例或默认值当成已确认需求。
• 只报告可能改变需求、方案、实现计划或验收结果的实质问题。忽略纯措辞偏好和无影响的格式问题。
• 区分“没有发现问题”和“缺少证据，无法验证”。不要用猜测补齐证据缺口。

收集证据

1. 确认待审查的 spec。存在多个候选文件且用户没有指明时，先让用户选择，不要默认使用最新文件。
2. 读取产生该 spec 的完整需求对话。当前上下文不完整、只有摘要或没有原始对话时，明确记录限制；不要声称已验证所有需求决策。
3. 检查与方案相关的代码、项目约定和 Wiki。进入仓库后先读取适用的 AGENTS.md、CLAUDE.md 或等价指令，只验证会影响审查结论的系统事实。
4. 对重要需求和方案决策标记依据：
   • 已确认：用户在对话中明确选择或批准。
   • 推断：spec 或助手补充，但用户没有明确确认。
   • 无依据：找不到对话或仓库事实支持。
   • 冲突：spec、对话和仓库事实之间不一致。

不要把 spec 自身的陈述当作“用户已经确认”的证据。

按顺序审查

1. 先还原问题

• 用一句话说明受影响对象、当前不理想状态和希望得到的结果。
• 检查 spec 是否明确了真正的问题与成功结果，而不是把预选方案、功能清单或实现动作写成目标。
• 检查范围是否聚焦于同一个问题，是否混入无法由该问题解释的附带需求。
• 检查是否有足够依据说明这个问题需要解决；存在明显更小的处理方式时指出，但不要为了列备选而虚构方案。

如果无法稳定地复述问题，把它作为首要发现，不要继续假定方案目标正确。

2. 核对对话是否闭合

• 将每个重要需求、约束和方案选择追溯到对话中的明确决定。
• 找出尚未回答的问题、被拒绝后又写入 spec 的选项、相互矛盾的回答，以及由助手擅自提升为需求的细节。
• 按任务相关性检查行为边界、角色、数据、失败场景、兼容性、迁移、安全、性能和运维约束。不要机械要求与任务无关的章节。
• 特别检查会导致两种合理实现的歧义，以及会改变用户可见行为或数据语义的默认选择。

3. 检查方案质量和系统适配

• 将每个主要方案组件追溯到已确认的问题、需求或约束；指出没有必要性的复杂度和没有方案承接的需求。
• 用代码和项目文档验证架构假设、现有抽象、数据流、生命周期、协议和仓库约定。
• 检查方案能否端到端工作，包括关键失败路径、状态转换、兼容或迁移影响；只检查与任务实际相关的维度。
• 检查是否重复建设已有能力、绕过既有边界、引入不必要耦合，或遗漏更简单且同样满足目标的做法。
• 区分“spec 未说明”“方案本身有缺陷”“方案与仓库事实冲突”，不要混为同一种问题。

4. 执行基础 spec 自检

• 扫描 TBD、TODO、占位符和无法验证的模糊表述。
• 检查各章节是否内部一致，架构、流程、决策和验收是否互相支持。
• 检查范围能否由一个连贯计划完成；过大时指出需要拆分的边界。
• 找出能被合理解读成两种含义的需求。

5. 检查验收是否证明目标

• 确认验收标准描述可观察结果，而不只是实现步骤或内部结构。
• 确认关键失败场景有预期行为。
• 确认测试切入点能够证明问题已解决，并覆盖方案中风险最高的假设。
• 找出与问题、需求或方案没有对应关系的验收项，以及没有验收项承接的重要需求。

控制发现质量

仅在问题可能造成以下任一结果时报告：

• 解决错误的问题或交付错误的用户行为；
• 把未确认决定带入实现；
• 遗漏关键边界、失败行为、兼容性或数据语义；
• 采用与现有系统事实冲突或不可行的方案；
• 引入显著且无必要的复杂度或风险；
• 使完成状态无法被可靠验收。

按实际影响标记：

• P0 — 必须先解决：核心目标或关键验收不能成立；必需能力缺失；方案或实现被阻断；存在严重安全、数据损坏或兼容性破坏风险。
• P1 — 应当解决：存在明确缺陷或实质歧义；重要边界或失败路径错误；非核心需求遗漏；存在明显架构、可靠性、数据一致性或测试风险。
• P2 — 改进建议：尚未证明存在错误行为，但调整能实质改善结构、可维护性、清晰度、性能余量或未来风险。

不要按问题类型机械定级：严重缺陷可以是 P0；不要为了填满每个等级而制造发现。

输出报告

以下完整报告模板仅由主 agent 使用；reviewer subagent 不输出该模板，只返回 reviewer 结果。

按以下结构输出；没有内容的章节直接省略：

# Spec review

## 审查概览

| 项目 | 内容 |
|---|---|
| 总体建议 | <最值得优先处理的问题和剩余风险> |
| P0 / P1 / P2 | <数量 / 数量 / 数量> |
| 问题理解 | <用一句话复述受影响对象、当前问题和目标结果> |
| 对话证据 | <完整 / 部分 / 缺失及一句话边界> |
| 仓库证据 | <已检查的关键代码或文档范围> |
| 执行方式 | <专用 subagent / 当前 agent 降级审查及原因> |

## Findings 摘要

| ID | 优先级 | 类别 | 问题 | 证据位置 | 处理方向 |
|---|---|---|---|---|---|
| F1 | P0 | <类别> | <一句话问题> | `<spec:line / file:line>` | <一句话建议> |

## Findings 详情

### F1 [P0|P1|P2] <简短标题>
- 类别：问题定义 | 未确认需求 | 细节缺失 | 方案设计 | 系统适配 | 一致性/歧义 | 验收
- 证据：<spec 章节或行号、对话中的明确内容、相关代码或文档路径>
- 影响：<为什么会改变需求、方案、计划或验收>
- 建议：<建议的澄清问题或调整方向，不直接重写 spec>

## 证据缺口
- <缺失的对话、代码事实或其他无法验证的依据>

## 总体建议
<概括最值得优先处理的 1–3 个问题和剩余风险；不要给通过/不通过结论或评分>

使用以下格式规则：

• 在概览中统计 P0、P1、P2 数量。摘要和详情按 P0、P1、P2 排列，同级内按对问题和方案的影响排序。
• 为每项 Finding 分配稳定的 F1、F2 编号；摘要表与详情标题必须一一对应。
• 摘要表只写单段短文本。证据位置只放最关键的 spec、对话、代码或文档位置；完整证据、影响和建议放在详情中。
• 表格中的路径和行号使用行内代码。单元格中的 | 必须写成 \|，不要在单元格中放多段文字或列表。
• 详情不要逐字重复摘要；引用具体证据，无法引用时把它列为证据缺口。

没有实质问题时，在概览中写 P0 / P1 / P2 = 0 / 0 / 0 和“未发现实质问题”，省略“Findings 摘要”和“Findings 详情”，仍列出证据边界和剩余不确定性。输出报告后停止，不要自动进入 scope、修改 spec 或生成实施计划。