# Review Spec

> Manually review an existing spec against conversation and repository evidence. Use only when the user explicitly invokes review-spec by name.

- Skill: `swm8023/review-spec` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add swm8023/review-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/swm8023/review-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: swm8023 (https://skillmd.com/u/swm8023)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/swm8023/review-spec

---


# Review Spec

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

<REVIEWER-SUBAGENT-STOP>
如果你是主 agent 派遣来执行本次 spec 审查的 reviewer，跳过“调度 reviewer”，直接从“审查契约”开始执行。不要再次委派 subagent，也不要执行主 agent 的降级判断或最终报告包装。
reviewer 只返回审查结果：Findings、证据缺口和总体建议；不要输出 `# Spec review`、`审查概览`、`执行方式` 或降级原因。完整报告由主 agent 汇总。
</REVIEWER-SUBAGENT-STOP>

## 调度 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 结果。

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

```markdown
# 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 或生成实施计划。