Superpowers SDD 修复循环实战：Scoped Re-Review 提示词模板如何验证“修复真的生效了“

Superpowers SDD 修复循环实战：Scoped Re-Review 提示词模板如何验证"修复真的生效了"

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers

在 superpowers 的 subagent-driven-development（SDD）技能中，每个任务实现完成后都要经过"实现 → 评审 → 修复 → 复审"的循环。re-review-prompt.md 定义的就是这个循环中最关键的一环——范围化复审（scoped re-review）的提示词模板：复审者不再做一轮全新评审，而是只验证上一轮评审的每条 finding 是否已被处理，并检查修复 diff 本身是否引入了新问题。读完本文，你将理解这个模板每一节的契约语义、七个占位符的填充方式，以及它与 SKILL.md 中五轮熔断、评审包脚本（scripts/review-package）如何协同工作，使修复循环在结构上必然收敛。

一、为什么复审必须是"范围化"的

模板开篇就定调（re-review-prompt.md）：

Use this template when dispatching a re-review after a fix round. The re-reviewer verifies the findings were addressed and checks the fix diff for new breakage.It is not a fresh review — the full review already happened.

Purpose:验证上一轮评审的每条 finding 是否被处理，且修复本身没有破坏任何东西。

这条定位不是风格偏好，而是对真实故障的修正。设计文档 2026-07-15-sdd-fix-loop-redesign-design.md 记录了四个在真实会话中观察到的问题，其中第一个就是病态评审循环：旧版循环的字面语义是"Repeat until approved"且没有轮次上限，每一轮复审又是对整个 diff 的全新完整评审——于是非确定性的前沿评审模型每轮都会翻出新 finding，形成 implement → review → fix → review → review → fix → review 的打转，没有断路器。设计文档把这种"每轮全量复审"称为churn engine（空转引擎），并指出 strict-cost 实验独立测量过：评审循环次数是单次运行成本中最大的方差来源。

因此新循环有两条硬性设计决策（见设计文档 Design Decisions 表格）：

1. 复审范围锁定到 findings 列表——复审者只能对给定 finding 逐条判词，并只检查修复 diff 内的新破坏；
2. 五轮熔断——每任务最多 5 轮修复，第 5 轮仍失败则由控制器裁决。

范围化复审是"结构性收敛"的第一块基石：复审者被禁止漫无目的地游走（wander），新发现如果落在修复 diff 之外的代码上，只能作为非阻塞观察项记录，不能延长循环。

二、模板全文结构与逐节契约

模板主体是一个可直接复制填充的 Subagent 派发块。下面按模板内部的章节顺序拆解，每一节都是对复审者行为的强约束：

2.1 派发头：模型必填

Subagent (general-purpose): description: "Re-review Task N fix round R" model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted model silently inherits the session's most expensive one]

[MODEL]是必填项。SKILL.md 的 Model Selection 一节明确警告：省略 model 字段会静默继承会话模型——通常是最强也最贵的模型——从而"静默地使整节模型选择策略失效"。针对复审的特殊建议是：小修复 diff 的范围化复审用低到中档模型（原文：Scoped re-reviews of small fix diffs take a cheap-to-mid tier），因为复审只看一个窄范围，不需要最强推理。

2.2 The Task / The Findings Under Verification / The Fix：三路输入

模板给复审者三路文件输入：

章节	占位符	内容
The Task	[BRIEF_FILE]	任务简报文件——与实现者工作时使用的是同一个文件
The Findings Under Verification	[FINDINGS]	上一轮评审的 Critical/Important findings 与 spec gaps，逐字复制（copied verbatim），每条一个 bullet
The Fix	[REPORT_FILE]	实现者的报告文件（修复报告追加在文件末尾）

[FINDINGS]必须逐字复制而不能改写，这一点很重要：finding 是上一轮评审的输出原文，改写会引入语义漂移，使"这条是否被处理"的判断失去锚点。[FINDINGS]与[BRIEF_FILE]共同构成复审的完整任务面——brief 告诉复审者任务本来要做什么，findings 告诉它上一轮发现了什么。

2.3 Diff 窗口：FIX_BASE 与 HEAD

**Fix base:** [FIX_BASE_SHA] (the head the previous review saw) **Head:** [HEAD_SHA] **Diff file:** [DIFF_FILE] Read the diff file once — it contains the fix commits, a stat summary, and the fix diff with surrounding context. Do not re-run git commands. If the diff file is missing, fetch the diff yourself: `git diff --stat [FIX_BASE_SHA]..[HEAD_SHA]` and `git diff [FIX_BASE_SHA]..[HEAD_SHA]`.

这里有三个要点：

1. [FIX_BASE_SHA]的语义是"上一轮评审看到的 head"，而不是任务开始时的 BASE。这是范围化的核心：diff 窗口只覆盖"上次评审之后到现在的提交"，即本轮修复本身。

2. [DIFF_FILE]由脚本生成：scripts/review-package PLAN_FILE FIX_BASE HEAD打印出的路径。从 review-package 的源码可以看到，输出文件包含三段——git log --oneline提交列表、git diff --stat统计、git diff -U10带 10 行上下文的完整 diff。文件名按范围命名：

   out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"

   脚本头注释专门说明了这个设计意图："named per range, so a re-review after fixes gets a distinct fresh file"（按范围命名，因此修复后的复审得到的是另一个全新文件）。这保证了修复轮复审的 diff 包不会与首轮评审的包互相覆盖。

3. 只读约束：模板明确要求 "Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way."（你的评审对此 checkout 是只读的，不得改动工作树、索引、HEAD 或分支状态。）并规定"读一次 diff 文件、不要重跑 git 命令"，仅在 diff 文件缺失时才自行用 git 命令兜底。

2.4 Scope 节：禁止漫游

这是范围化复审与全量复审的分水岭，原文措辞非常强硬：

Your scope is the findings list and the fix diff. Verdict every finding. Inspect the fix diff for new problems the fix itself introduced.Do NOT re-review code the fix did not touch: if you notice an issue entirely outside the fix diff, report it under Out-of-Scope Observations — it does not block this task and does not extend the loop. A broad whole-branch review happens after all tasks are complete.

三条规则：

• 每条 finding 都必须给判词（Verdict every finding），不能漏；
• 只检查修复 diff 引入的新问题；
• 修复 diff 之外发现的任何问题，一律进 Out-of-Scope Observations：不阻塞本任务、不延长循环，由控制器记录在案留给最终整分支评审处理。

这条规则直接回应了 SKILL.md "Common Rationalizations" 表格中的一行借口："The reviewer will just find something new anyway"（反正评审者总会发现新东西）——现实是：范围化复审只验证修复、不会漫游；未触及代码上的新发现进账本（ledger），不进循环。

2.5 Tests 节：报告是"未验证的声明"

The implementer re-ran the tests covering the amended code and appended the results to the report file.Treat the report as unverified claims: confirm the fix report names the covering tests and shows their output, and verify the claims against the diff. Do not re-run the suite to confirm their report. Run a test only when reading the code raises a specific doubt that no existing run answers — and then a focused test, never a package-wide suite.

复审者对实现者报告的测试结论持怀疑态度（与 task-reviewer-prompt.md 的 "Do Not Trust the Report" 一脉相承）：要确认修复报告指名了覆盖测试、展示了输出，并把声明与 diff 对照核验；但不得为确认报告而重跑测试套件——只有当读代码时产生"现有运行都无法回答的具体疑问"时才跑测试，且只能跑聚焦测试，绝不跑包级全量套件。这与 SKILL.md 修复循环中的"完整性门"呼应：派发复审前，控制器要先确认修复报告同时包含三样东西——覆盖测试、运行命令、输出；三者齐全才派发复审。

2.6 Output Format：四段式输出契约

模板规定复审者的最终消息就是报告本身："begin directly with the first finding's verdict. Every line is a verdict, a finding with file:line, or a check you ran — no preamble, no process narration."（直接从第一条 finding 的判词开始；每一行要么是判词、要么带 file:line 的发现、要么是你执行的检查——无前言、无过程叙述。）

四个输出块：

1) Finding Verdicts（逐条判词）

### Finding Verdicts For each finding in The Findings Under Verification, in order: - **[finding one-liner]** — ADDRESSED | NOT ADDRESSED, with file:line evidence. "Attempted" is not addressed: the specific defect must no longer exist.

按顺序对每条 finding 给出二值判词ADDRESSED / NOT ADDRESSED，且必须附file:line证据。模板特别收紧了判定标准："Attempted is not addressed"（尝试过不算处理）——那个具体的缺陷必须已不复存在。这一条把"我改了相关代码"和"缺陷确实消失"区分开。

2) New Breakage in the Fix Diff（修复 diff 中的新破坏）

修复本身弄坏或引入的东西，带严重级别（Critical/Important/Minor）与 file:line；干净则写 "None"。按 SKILL.md 的循环规则，修复 diff 中新出现的 Critical/Important 破坏会并入 open findings 列表——这是循环唯一会被"扩大"的合法途径，而且只限修复 diff 内部。

3) Out-of-Scope Observations（范围外观察）

完全位于修复 diff 之外的问题。非阻塞；控制器把它们记入账本留给最终评审。没有则写 "None"。

4) Verdict（轮次裁决）

### Verdict **Fix round:** [All findings addressed, no new Critical/Important breakage | Findings remain open] — list the open ones.

二选一：要么"所有 finding 已处理且无新 Critical/Important 破坏"，要么"仍有未处理 finding"——并列出仍开放的条目。这正是控制器判定"循环是否收敛"的唯一依据。

三、占位符速查表

模板末尾给出的七项占位符（re-review-prompt.md "Placeholders" 一节）：

占位符	必填	取值来源
[MODEL]	必填	按 SKILL.md Model Selection 选定；小修复 diff 的范围化复审用低到中档档
[BRIEF_FILE]	—	任务简报文件（与实现者同一份；由 scripts/task-brief 生成，输出<workspace>/task-<N>-brief.md）
[FINDINGS]	—	上一轮评审的 Critical/Important findings 与 spec gaps，逐字复制，每条一个 bullet
[REPORT_FILE]	—	实现者报告文件（修复报告追加于其后）
[FIX_BASE_SHA]	—	上一轮评审看到的 head（不是任务初始 BASE）
[HEAD_SHA]	—	当前提交
[DIFF_FILE]	—	scripts/review-package PLAN_FILE FIX_BASE HEAD打印出的路径

注意[FINDINGS]和[FIX_BASE_SHA]是 2026-07-15 修复循环重构时为复审模板新增的占位符——实施计划 2026-07-15-sdd-fix-loop-redesign.md 的 Global Constraints 明确写道：

Template placeholders keep the existing bracket convention:[MODEL],[BRIEF_FILE],[REPORT_FILE],[BASE_SHA],[HEAD_SHA],[DIFF_FILE],[GLOBAL_CONSTRAINTS]; the new re-review template adds[FINDINGS],[FIX_BASE_SHA].

复审者返回内容（"Re-reviewer returns" 一节原文摘要）：逐条 finding 判词（ADDRESSED / NOT ADDRESSED）、修复 diff 中的新破坏、范围外观察、轮次裁决。控制器拿这四样就能直接决定下一步：收敛 → 完成任务；不收敛且未达上限 → 下一轮；不收敛且第 5 轮 → 熔断裁决。

四、模板在 SDD 修复循环中的位置

单独看模板是"一份合同"；放进 SKILL.md 的 The fix loop 小节才能看到它的完整生命周期。

4.1 触发与轮次策略

循环在"评审报告 spec ❌、任意 Critical/Important finding、或控制器确认过的 ⚠️ 项"时触发。两个出口在循环开始前就分流：Minor findings 只记账本（Task <N>: minor (deferred): <one-liner>）永不进循环；与计划文本冲突的 finding 直接交人类裁决。

进入循环后每任务最多 5 轮，每轮 = 一次修复派发 + 一次范围化复审：

• 第 1–3 轮：resume 原始实现者，把开放 findings 逐字发给它。实现者上下文完整——它知道任务、代码和自己的选择。implementer-prompt.md 的 "After Review Findings" 一节规定了被 resume 后的动作合同："Fix them, re-run the tests that cover the amended code, and append a fix report to your report file: what you changed, the covering tests you ran, the command, and the output."（修复它们，重跑覆盖被改代码的测试，把修复报告追加到报告文件：改了什么、跑了哪些覆盖测试、命令、输出。）若你的 harness 无法向存活的子代理再发消息，则派发一个携带 brief 路径、报告文件路径和 findings 的新实现者——报告文件无论如何都是持久记忆。
• 第 4–5 轮：换一个更强模型的实现者，附带框架话术："A prior implementer attempted this task [N] times; you own it now. Read the report file for what was tried."（此前一位实现者尝试过此任务 [N] 次；现在由你接手。读报告文件看尝试过什么。）设计文档的解释是：能撑过三次 resume 的循环通常意味着实现者看不到自己的问题——"fresh eyes and a capability bump in one move"（一次动作同时完成换视角与升能力）。

4.2 每一轮如何调用复审模板

SKILL.md 第 4 步的关键段落：

The re-review is scoped.Runscripts/review-package PLAN_FILE FIX_BASE HEADwhere FIX_BASE is the head the previous review saw, and dispatch re-review-prompt.md with the findings list, the brief, the report file, and the printed diff path. The re-reviewer verdicts each finding ADDRESSED or NOT ADDRESSED and flags new breakage in the fix diff only. New Critical/Important breakage in the fix diff joins the open findings list. Out-of-scope observations go to the ledger as deferred minors — they never extend the loop.

拆解成控制器动作序列：

1. 修复者返回后，确认其修复报告三要素齐全（覆盖测试、命令、输出）；

2. 运行scripts/review-package PLAN_FILE FIX_BASE HEAD——FIX_BASE是上一轮评审看到的 head。从 review-package 源码可见，它会校验两个 SHA（git rev-parse --verify），把提交列表、stat、-U10diff 写入按范围命名的文件，并打印wrote <path>: <N> commit(s), <bytes> bytes——控制器拿到打印的路径即可，diff 内容永不进入控制器上下文；

3. 填充模板七占位符，派发复审子代理；

4. 按四段式输出更新账本，格式为（SKILL.md "After each round" 与实施计划 Global Constraints 中的精确格式，供 eval 场景 grep）：

   Task <N>: fix round <R>/5 (<X> addressed, <Y> open — <finding one-liners>; commits <a7>..<b7>)

4.3 熔断与裁决

当第 5 轮的复审仍有 finding 未关闭，"断路器"跳闸：停止派发，由控制器逐条裁决（控制器持有评审者所没有的计划和跨任务上下文）：

• 评审者错了或有争议→ 搁置（park），账本记Task <N>: parked — <finding> — ruling: <why the code stands>，最终评审会看到双方立场；
• 真实但下游无依赖→ 同样搁置，ruling 注明"真实但延期"；
• 真实且承重（load-bearing）——后续任务构建于其上，或暴露计划缺陷 → 立即 STOP，记Task <N>: BLOCKED — <reason>并向人类报告。

模板里的 "Verdict" 一节正是这一裁决机制的数据来源。设计文档特别强调没有提前出口：控制器绝不在达到上限前裁决，因为"提前裁决以结束循环"等于换了一种名字做预判（pre-judging）——这与模板禁止评审者漫游是同一设计哲学的两面：把循环的自由度锁死，收敛才有保证。

4.4 最终评审中的复用

范围化复审不只服务于单任务循环。SKILL.md 的 Final Review 一节规定：最终整分支评审若发现 findings，派发一个（ONE）修复子代理处理完整 findings 列表，然后恰好运行一次范围化复审（对修复范围跑review-package，仍用本模板），残余 findings 按熔断规则裁决——没有第二波修复。也就是说，同一份模板、同一套契约，同时约束任务级循环与分支级收尾，规则完全一致。

五、一次完整的修复轮：从示例中看模板生效

SKILL.md 的 Example Workflow 给出了带行内引用的完整样例（Task 2 场景）：

[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path] Task reviewer: Spec ❌: - Missing: Progress reporting (spec says "report every 100 items") Issues (Important): Magic number (100) [Fix round 1: resume the implementer with both findings] Implementer: Added progress reporting, extracted PROGRESS_INTERVAL constant. Re-ran test/recovery.test.js — 10/10 passing. Fix report appended. [Run review-package PLAN_FILE FIX_BASE HEAD; dispatch scoped re-review] Re-reviewer: Missing progress reporting — ADDRESSED (src/recovery.js:41). Magic number — ADDRESSED (src/recovery.js:7). New breakage: none. Verdict: all findings addressed. [Ledger: Task 2: fix round 1/5 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)] [Ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, review clean)]

对照模板的四段式输出，可以看到复审者的行为被完全约束住：每条 finding 一个判词加file:line（src/recovery.js:41、src/recovery.js:7）、New breakage 一行 "none"、没有范围外观察就省略、最后给出轮次裁决 "all findings addressed"。控制器据此把 "2 addressed, 0 open" 记入账本并直接标记任务 complete——整个过程没有任何"再从头审一遍"的开销。

六、与首轮评审模板的职责边界

为避免两份模板职责混淆，这里对照 task-reviewer-prompt.md（首轮任务评审）与 re-review-prompt 的分工：

维度	task-reviewer-prompt.md（首轮）	re-review-prompt.md（复审）
评审对象	任务完整 diff（BASE..HEAD）	仅修复 diff（FIX_BASE..HEAD）
输入	brief、全局约束、报告、diff 包	brief、findings 列表（逐字）、报告（含追加的修复报告）、diff 包
输出	spec 合规 ✅/❌/⚠️ + 质量判级（Critical/Important/Minor）+ Task quality 裁决	逐条 ADDRESSED/NOT ADDRESSED + 新破坏 + 范围外观察 + 轮次裁决
漫游权限	可针对"可命名的具体风险"做一次聚焦检查	禁止——diff 外发现一律非阻塞记录
测试态度	不重跑套件，只为具体疑问跑聚焦测试	同样：不重跑套件，仅报告声明核验 + 聚焦测试
模型档位	按 diff 规模/复杂度/风险选型	小修复 diff 走低到中档

值得注意的是复审模板没有spec 合规判定块：spec 合规已在首轮完成，复审只回答"上一轮的账清没清"。这种职责切分是设计文档"Re-reviews are scoped to the findings"决策的直接落地。

七、实操要点清单

结合模板与 SKILL.md 的规则，控制器在每一轮修复后应执行的检查点：

1. 模型行必填：[MODEL]显式填写；小 diff 复审选低到中档，避免继承最贵的会话模型；
2. findings 逐字粘贴：[FINDINGS]不得改写、不得挑选，Critical/Important findings 与 spec gaps 一条一个 bullet；
3. FIX_BASE 用对：是"上一轮评审看到的 head"，不是任务起始 BASE——用错会把整个任务 diff 拉回复审窗口，退化成全量复审；
4. diff 包走脚本：scripts/review-package PLAN_FILE FIX_BASE HEAD生成按范围命名的文件（review-package 已处理 SHA 校验与多提交任务完整性），控制器只传递打印出的路径；
5. 复审前过完整性门：修复报告必须同时含覆盖测试名、命令、输出三要素；
6. 按输出裁决：全部 ADDRESSED 且无新 Critical/Important 破坏 → 追加账本并标记 complete；有 NOT ADDRESSED → 下一轮（R<5）或熔断裁决（R=5）；
7. 范围外发现不阻塞：转入账本 deferred minors，由最终整分支评审统一 triage（最终评审使用 scripts/review-package 对MERGE_BASE..HEAD打包，并按 SKILL.md 指示指向账本中的 deferred-minor 与 parked 行）。

八、小结

re-review-prompt.md 用约百行文本解决了一个多代理开发框架的核心难题：如何在不引入全量复审成本的前提下证明"修复是真的"。它的三个结构性约束——输入锁定（findings 逐字 + 修复范围 diff 包）、输出锁定（四段式、每行带 file:line 证据）、行为锁定（只读、不漫游、不重跑套件）——与 SKILL.md 的五轮熔断、账本格式共同构成收敛的修复循环。模板本身的演化也记录在仓库中：设计文档给出了问题诊断与设计决策表，实施计划的 Task 1 给出了逐字节的目标内容、占位符约定（新增[FINDINGS]、[FIX_BASE_SHA]）与验收命令。若要进一步理解上游，建议顺读 SKILL.md 的 The fix loop 与 Common Rationalizations 两节，以及 task-reviewer-prompt.md 与 implementer-prompt.md 中与之衔接的合同条款。

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers