文档审查系统设计

文档审查系统设计¶

概述¶

在 superpowers 工作流中新增两个审查阶段：

1. Spec 文档审查 - 在 brainstorming 之后、writing-plans 之前
2. Plan 文档审查 - 在 writing-plans 之后、实现之前

两者均遵循实现审查所使用的迭代循环模式。

Spec 文档审查器¶

目的： 验证 spec 是否完整、一致，并已准备好进行实现规划。

位置： skills/brainstorming/spec-document-reviewer-prompt.md

检查内容：

输出格式：

## Spec Review

**Status:** Approved | Issues Found

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

**Recommendations (advisory):**
- [suggestions that don't block approval]

审查循环： 发现问题 -> brainstorming 代理修复 -> 重新审查 -> 重复直至通过。

调度机制： 使用带有 subagent_type: general-purpose 的 Task 工具。审查器提示词模板提供完整提示词。brainstorming 技能的控制器负责调度审查器。

Plan 文档审查器¶

目的： 验证 plan 是否完整、与 spec 匹配，并具备合理的任务分解。

位置： skills/writing-plans/plan-document-reviewer-prompt.md

检查内容：

Chunk 定义： chunk 是 plan 文档中任务的逻辑分组，以 ## Chunk N: <name> 标题为分隔。writing-plans 技能根据逻辑阶段（例如“Foundation”、“Core Features”、“Integration”）创建这些边界。每个 chunk 应足够独立，以便单独审查。

Spec 对齐验证： 审查器会同时收到： 1. plan 文档（或当前 chunk） 2. spec 文档的路径以供参考

审查器阅读两者并比较需求覆盖情况。

输出格式： 与 spec 审查器相同，但范围限定在当前 chunk。

审查过程（逐 chunk 进行）： 1. writing-plans 创建 chunk N 2. 控制器使用 chunk N 的内容和 spec 路径调度 plan-document-reviewer 3. 审查器阅读 chunk 和 spec，返回判定结果 4. 如有问题：writing-plans 代理修复 chunk N，转到步骤 2 5. 如通过：进入 chunk N+1 6. 重复直至所有 chunk 通过

调度机制： 与 spec 审查器相同 - 使用带有 subagent_type: general-purpose 的 Task 工具。

更新后的工作流¶

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

Spec 审查循环： 1. Spec 完成 2. 调度审查器 3. 如有问题：修复 -> 转到 2 4. 如通过：继续

Plan 审查循环： 1. Chunk N 完成 2. 为 chunk N 调度审查器 3. 如有问题：修复 -> 转到 2 4. 如通过：进入下一个 chunk 或开始实现

Markdown 任务语法¶

任务和步骤使用复选框语法：

- [ ] ### Task 1: Name

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

错误处理¶

审查循环终止： - 没有硬性迭代限制 - 循环持续到审查器通过为止 - 如果循环超过 5 次迭代，控制器应将此情况上报给人工以获取指导 - 人工可以选择：继续迭代、在已知问题下通过、或中止

分歧处理： - 审查器是建议性的 - 它们标记问题但不阻塞 - 如果代理认为审查反馈不正确，应在修复中说明原因 - 如果同一问题在 3 次迭代后仍存在分歧，上报给人工

审查器输出格式错误： - 控制器应验证审查器输出包含必填字段（Status、适用时的 Issues） - 如果格式错误，重新调度审查器并附带关于预期格式的说明 - 连续 2 次格式错误后，上报给人工

需要变更的文件¶

新文件： - skills/brainstorming/spec-document-reviewer-prompt.md - skills/writing-plans/plan-document-reviewer-prompt.md

修改的文件： - skills/brainstorming/SKILL.md - 在 spec 编写完成后添加审查循环 - skills/writing-plans/SKILL.md - 添加逐 chunk 审查循环，更新任务语法示例