Spec Review

Spec Review

Status: Approved | Issues Found

Issues (if any):

• [Section X]: [issue] - [why it matters]

Recommendations (advisory):

• [suggestions that don't block approval]

要点拆解：

- **Status** 字段只有两个合法取值：`Approved` 或 `Issues Found`，这是派发端验证输出的首要字段；
- **Issues** 采用 `[章节]: [具体问题] - [对规划为何重要]` 的单行结构，把"是什么"与"为什么要紧"绑定在一起，防止评审者只丢结论不给依据；
- **Recommendations** 是**咨询性（advisory）**建议，不阻塞审批——它与 Issues 的职责边界被刻意划清：Issues 决定是否返工，Recommendations 决定能否做得更好。

### 评审循环与派发机制

Spec 评审遵循标准的迭代收敛循环：

Issues Found -> 由写 Spec 的 agent（brainstorming）修复 -> 重新评审 -> 直至 Approved

设计文档明确指出派发机制为：**使用 Task 工具并以 `subagent_type: general-purpose` 派发评审子代理**，评审者提示词模板提供完整 prompt 文本，由 **brainstorming 技能的控制器负责派发**。之所以强调"修复由写 Spec 的同一 agent 完成"，是因为它保留了对需求的上下文记忆，修复更精准。

## Plan 文档评审者：进入编码前的任务级校验

### 目的与位置

Plan 评审者的任务是：**验证 Plan 是否完整、与 Spec 对齐、且任务拆解正确**（"Verify the plan is complete, matches the spec, and has proper task decomposition"）。其载体为 [skills/writing-plans/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)。

在仓库当前版本模板中，派发时机被描述为 **"The complete plan is written"（完整计划写完后）**；评审 prompt 同时接收两个输入——**待审 Plan 文件路径** 与 **供参考的 Spec 文件路径**。

### 检查维度（原设计 5 大类）

| Category | What to Look For |
|----------|------------------|
| Completeness（完整性） | TODOs、占位符、未完成的任务 |
| Spec Alignment（与 Spec 对齐） | Plan 是否覆盖 Spec 需求、有无范围蔓延（scope creep） |
| Task Decomposition（任务拆解） | 任务是否原子化、边界清晰 |
| Task Syntax（任务语法） | 任务与步骤是否使用复选框语法 |
| Chunk Size（块大小） | 每个 Chunk 是否小于 1000 行 |

### Spec 对齐校验：评审者必须同时读两份文档

Plan 评审区别于 Spec 评审的关键在于**对照阅读**：评审者收到的输入包含两样东西——（1）Plan 文档（或当前 Chunk），（2）Spec 文档的路径。评审者需要通读两者，逐条比对需求覆盖情况，检查是否存在"Spec 写了但 Plan 没排任务"的漏项，以及"Plan 排了 Spec 根本没提"的范围蔓延。

仓库当前版本的模板将此检查细化为 **Buildability（可落地性）**：一个工程师仅凭这份 Plan 能否不卡壳地把事情做完？并保留 Spec Alignment 维度，把检查维度收敛为 Completeness / Spec Alignment / Task Decomposition / Buildability 四项，同时引入与 Spec 评审一致的 Calibration 原则——只有会导致实现走偏或卡住的严重缺口（Spec 需求缺失、步骤自相矛盾、占位内容、任务模糊到无法执行）才构成阻塞问题。

### Chunk 的定义与分块评审流程

原设计文档引入了一个重要概念——**Chunk（块）**：

> A chunk is a logical grouping of tasks within the plan document, delimited by `## Chunk N: <name>` headings.

Chunk 边界由 writing-plans 技能基于逻辑阶段（例如 "Foundation"、"Core Features"、"Integration"）划分，每个 Chunk 自包含到可以被独立评审。**1000 行**是单个 Chunk 的硬上限，其背后逻辑与 LLM 上下文窗口的可靠工作区间有关——超出该长度的计划文本难以在一次评审中被完整、准确地消化。

分块评审采用**边写边审、逐块放行**的流程：

1. Writing-plans 技能产出 Chunk N；
2. 控制器派发 plan-document-reviewer，输入为 Chunk N 内容 + Spec 路径；
3. 评审者阅读 Chunk 与 Spec，返回裁决；
4. 若发现问题：写计划的 agent 修复 Chunk N，回到步骤 2；
5. 若通过：继续编写 Chunk N+1；
6. 重复直到所有 Chunk 均获批准。

输出格式与 Spec 评审者相同，但作用域限定于当前 Chunk；问题定位粒度精确到 `[Task X, Step Y]`，这正是为了与实现阶段逐任务执行的粒度对齐。派发机制与 Spec 评审者一致：Task 工具 + `subagent_type: general-purpose`。

## 合并后的完整工作流

加入两级评审后，superpowers 的主流水线变为：

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

**Spec Review Loop（Spec 评审循环）：**
1. Spec 完成；
2. 派发评审者；
3. 若发现问题：修复 → 回到步骤 2；
4. 若通过：进入 writing-plans。

**Plan Review Loop（Plan 评审循环）：**
1. Chunk N 完成；
2. 派发评审者审 Chunk N；
3. 若发现问题：修复 → 回到步骤 2；
4. 若通过：写下一个 Chunk，或进入实现。

值得注意的是，[RELEASE-NOTES.md](https://gitcode.com/GitHub_Trending/su/superpowers/blob/44c9b2d6e889982ac18c27d05a19fefe335194e1/RELEASE-NOTES.md?utm_source=gitcode_repo_files) 记录了随后一次重要演进（v5.0.4，2026-03-16）：**Plan 评审由"分块逐个评审"改为"一次评审完整计划"**，移除了全部 Chunk 相关概念（`## Chunk N:` 标题、1000 行限制、逐块派发）。因此如果你查看当前 [writing-plans/SKILL.md](https://gitcode.com/GitHub_Trending/su/superpowers/blob/44c9b2d6e889982ac18c27d05a19fefe335194e1/skills/writing-plans/SKILL.md?utm_source=gitcode_repo_files)，会发现其中已不再包含 Chunk 边界与分块循环，而是在 [Execution Handoff](https://gitcode.com/GitHub_Trending/su/superpowers/blob/44c9b2d6e889982ac18c27d05a19fefe335194e1/skills/writing-plans/SKILL.md?utm_source=gitcode_repo_files) 阶段将执行交给 subagent-driven-development 或 executing-plans，由 SDD 在**每个任务**之间执行评审闸门（这正是"fresh subagent per task + two-stage review"的设计）。阅读本文的 Chunk 概念时请留意这一历史上下文：它在设计期解决了"计划太长一次性审不完"的问题，后期被"整份计划一次评审 + 逐任务实现评审"取代。

## Markdown 任务语法：让评审与执行共享同一套结构

要让评审者与执行者都能程序化识别"任务"与"步骤"，Plan 文档中的任务与步骤必须统一使用复选框语法：

```markdown
- [ ] ### Task 1: Name

- [ ] **Step 1:** Description
  - File: path
  - Command: cmd