Spec Document Reviewer Prompt Template

Use this template when dispatching a spec document reviewer subagent.

Purpose: Verify the spec is complete, consistent, and ready for implementation planning.

Dispatch after: Spec document is written to docs/superpowers/specs/

它要解决的是一个典型的 Agent 工作流缺陷：**写文档的 Agent 对自己刚写完的文档缺乏怀疑**。LLM 在生成 spec 时倾向于"顺着自己刚写的假设继续推进"，占位符（TBD/TODO）、前后矛盾、含糊到可以有两种解读的需求，都会直接带进下游的 implementation plan。Superpowers 的做法是用一个**上下文全新的子代理**来审查 spec——它不共享作者的会话历史，只拿到 spec 文件路径，以"陌生审查者"视角给出裁决。

这与仓库中其他 reviewer 模板是同构的：[plan-document-reviewer-prompt.md](https://gitcode.com/GitHub_Trending/su/superpowers/blob/44c9b2d6e889982ac18c27d05a19fefe335194e1/skills/writing-plans/plan-document-reviewer-prompt.md?utm_source=gitcode_repo_files) 审查计划文档，[code-reviewer.md](https://gitcode.com/GitHub_Trending/su/superpowers/blob/44c9b2d6e889982ac18c27d05a19fefe335194e1/skills/requesting-code-review/code-reviewer.md?utm_source=gitcode_repo_files) 审查代码 diff。三者共同的模式是"精确裁剪的上下文 + 独立子代理 + 结构化裁决返回"，只有 Status / Issues / Recommendations 回到主控 Agent 的上下文里，避免审查过程烧掉主会话的上下文窗口。

## 完整提示词模板与逐段解析

模板中真正会被填充并发给子代理的是下面这段 prompt（`[SPEC_FILE_PATH]` 为占位符，派发时替换为 spec 文档的实际路径）：

```text
Subagent (general-purpose):
  description: "Review spec document"
  prompt: |
    You are a spec document reviewer. Verify this spec is complete and ready for planning.

    **Spec to review:** [SPEC_FILE_PATH]

    ## What to Check

    | Category | What to Look For |
    |----------|------------------|
    | Completeness | TODOs, placeholders, "TBD", incomplete sections |
    | Consistency | Internal contradictions, conflicting requirements |
    | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
    | Scope | Focused enough for a single plan — not covering multiple independent subsystems |
    | YAGNI | Unrequested features, over-engineering |

    ## Calibration

    **Only flag issues that would cause real problems during implementation planning.**
    A missing section, a contradiction, or a requirement so ambiguous it could be
    interpreted two different ways — those are issues. Minor wording improvements,
    stylistic preferences, and "sections less detailed than others" are not.

    Approve unless there are serious gaps that would lead to a flawed plan.

    ## Output Format

    ## Spec Review

    **Status:** Approved | Issues Found

    **Issues (if any):**
    - [Section X]: [specific issue] - [why it matters for planning]

    **Recommendations (advisory, do not block approval):**
    - [suggestions for improvement]

下面逐段展开。

子代理类型与派发参数

• Subagent (general-purpose)：以通用型子代理派发。设计规格文档 2026-01-22-document-review-system-design.md 中写明了派发机制——"Use the Task tool with subagent_type: general-purpose. The reviewer prompt template provides the full prompt. The brainstorming skill's controller dispatches the reviewer."，即由 brainstorming 技能的主控（controller）在 spec 写完后负责派发。
• description: "Review spec document"：用于在会话中展示这次派发在做什么，对操作者透明。
• 唯一的输入是 [SPEC_FILE_PATH]：审查者只拿到文件路径，不拿会话历史、不拿作者意图说明。这与 requesting-code-review/SKILL.md 中"Hand it precisely crafted context, never your session's history"的原则一致——审查者应该只盯着工作产物本身。

检查维度：五个类别各抓什么

类别	检查内容	为什么重要
Completeness（完整性）	TODO、占位符、"TBD"、未写完的章节	带占位符的 spec 会让下游计划凭空脑补缺失部分
Consistency（一致性）	内部矛盾、互相冲突的需求	矛盾需求会导致计划里出现两条互斥的实现路径
Clarity（清晰度）	含糊到"足以让人做错东西"的需求	注意门槛：只有当歧义可能导向两种不同的实现时才算问题
Scope（范围）	是否聚焦到单一 plan 能承接，而不是覆盖多个相互独立的子系统	与 brainstorming 技能的分解要求呼应（见下文工作流一节）
YAGNI（防过度设计）	用户没要求的功能、过度工程	防止 spec 膨胀出"顺便做一下"的功能

这里的 Scope 维度值得注意：它不是笼统的"范围太大"，而是精确到"是否可以由一份 plan 实现"。这与 brainstorming/SKILL.md 中的范围评估要求形成上下游配合——brainstorming 在提问前就要判断"如果需求描述了多个独立子系统（例如一个带聊天、文件存储、计费、分析的平台），立即标记它"，帮助用户分解成子项目，每个子项目各走一遍 spec → plan → implementation 循环。审查者的 Scope 检查就是这条规则的下游兜底。

校准准则（Calibration）：防止审查者变成吹毛求疵的编辑

模板中最有设计含量的部分是 ## Calibration：

Only flag issues that would cause real problems during implementation planning. A missing section, a contradiction, or a requirement so ambiguous it could be interpreted two different ways — those are issues. Minor wording improvements, stylistic preferences, and "sections less detailed than others" are not.

Approve unless there are serious gaps that would lead to a flawed plan.

它做两件事：

1. 划定"问题"的下限：只有"会导致实施规划出真实问题"的缺陷才算 Issue——缺失章节、内部矛盾、存在两种解读的需求。措辞润色、风格偏好、"某章节比其他章节写得细一点"都不算。
2. 设定"通过"的默认方向：默认是通过（Approve），除非存在会导致 plan 出错的严重缺口。这明确了对抗性审查与顾问式审查的边界：审查者的输出里，只有 Issues 具有阻断力。

这一点也解释了模板把输出拆成 Issues（可阻断） 与 Recommendations（仅建议，不阻断通过） 两层的用意——建议类意见即使写了也不影响 Status 判定，从而避免"审查者提了 10 条风格建议导致循环无法收敛"的死循环。

输出契约：三个字段的结构化裁决

## Spec Review

**Status:** Approved | Issues Found

**Issues (if any):**
- [Section X]: [specific issue] - [why it matters for planning]

**Recommendations (advisory, do not block approval):**
- [suggestions for improvement]

模板末尾用一行总结了子代理的返回契约：

**Reviewer returns:** Status, Issues (if any), Recommendations

注意 Issues 条目的格式要求：[Section X]: [具体问题] - [为什么它对规划重要]。每个 Issue 必须定位到章节、给出具象描述，并说明对规划的实际影响——这既便于作者定点修复，也便于后续对"修复是否有效"做再审查。设计规格文档 2026-01-22-document-review-system-design.md 还规定了主控侧的容错：控制器应校验审查输出包含必需字段（Status 及有 Issue 时的 Issues），若输出格式畸形（malformed），带格式说明重新派发，连续两次畸形后上报给人。

模板在 Superpowers 工作流中的位置

spec-document-reviewer-prompt.md 声明的派发时机是 "Spec document is written to docs/superpowers/specs/"。把这个时间点放进 brainstorming 技能的完整检查清单（见 brainstorming/SKILL.md），整条流水线是：

1. 探索项目上下文
2. 按需即时提供 visual companion
3. 逐个提出澄清问题
4. 提出 2–3 个方案及权衡
5. 分节呈现设计并逐节获得用户批准
6. 将设计文档写入 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 并提交 git
7. Spec 自审——作者自己用"新鲜眼睛"做占位符扫描、内部一致性、范围、歧义四项检查，问题直接就地修复
8. 用户审阅 spec 文件
9. 进入 writing-plans 技能

也就是说，在 spec 从"作者自审"过渡到"用户审阅"和"下游规划"之前，spec reviewer 子代理充当独立第三方校验层：第 7 步的作者自审解决的是"作者知道但懒得检查"，而 spec reviewer 子代理解决的是"作者自己看不出来的盲点"——因为它不携带写作时的上下文偏见。

brainstorming 技能还设了一道硬闸门（HARD-GATE）：在呈现设计并获得用户批准之前，不得调用任何实现类技能、不得写任何代码。spec reviewer 与这道闸门共同保证了"未经审查的 spec 不会进入实施"。工作流全景可以概括为设计文档中的公式：

brainstorming -> spec -> SPEC REVIEW LOOP -> writing-plans -> plan -> PLAN REVIEW LOOP -> implementation