2026/9/5 17:10:17
FEATURED · 精选文章 
Superpowers SDD 修复循环实战Scoped Re-Review 提示词模板如何验证修复真的生效了【免费下载链接】superpowersAn agentic skills framework software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers在 superpowers 的 subagent-driven-developmentSDD技能中每个任务实现完成后都要经过实现 → 评审 → 修复 → 复审的循环。re-review-prompt.md 定义的就是这个循环中最关键的一环——范围化复审scoped re-review的提示词模板复审者不再做一轮全新评审而是只验证上一轮评审的每条 finding 是否已被处理并检查修复 diff 本身是否引入了新问题。读完本文你将理解这个模板每一节的契约语义、七个占位符的填充方式以及它与 SKILL.md 中五轮熔断、评审包脚本scripts/review-package如何协同工作使修复循环在结构上必然收敛。一、为什么复审必须是范围化的模板开篇就定调re-review-prompt.mdUse 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 表格复审范围锁定到 findings 列表——复审者只能对给定 finding 逐条判词并只检查修复 diff 内的新破坏五轮熔断——每任务最多 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 sessions 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每条一个 bulletThe 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].这里有三个要点[FIX_BASE_SHA]的语义是上一轮评审看到的 head而不是任务开始时的 BASE。这是范围化的核心diff 窗口只覆盖上次评审之后到现在的提交即本轮修复本身。[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 包不会与首轮评审的包互相覆盖。只读约束模板明确要求 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 findings 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.拆解成控制器动作序列修复者返回后确认其修复报告三要素齐全覆盖测试、命令、输出运行scripts/review-package PLAN_FILE FIX_BASE HEAD——FIX_BASE是上一轮评审看到的 head。从 review-package 源码可见它会校验两个 SHAgit rev-parse --verify把提交列表、stat、-U10diff 写入按范围命名的文件并打印wrote path: N commit(s), bytes bytes——控制器拿到打印的路径即可diff 内容永不进入控制器上下文填充模板七占位符派发复审子代理按四段式输出更新账本格式为SKILL.md After each round 与实施计划 Global Constraints 中的精确格式供 eval 场景 grepTask 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:linesrc/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复审评审对象任务完整 diffBASE..HEAD仅修复 diffFIX_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 的规则控制器在每一轮修复后应执行的检查点模型行必填[MODEL]显式填写小 diff 复审选低到中档避免继承最贵的会话模型findings 逐字粘贴[FINDINGS]不得改写、不得挑选Critical/Important findings 与 spec gaps 一条一个 bulletFIX_BASE 用对是上一轮评审看到的 head不是任务起始 BASE——用错会把整个任务 diff 拉回复审窗口退化成全量复审diff 包走脚本scripts/review-package PLAN_FILE FIX_BASE HEAD生成按范围命名的文件review-package 已处理 SHA 校验与多提交任务完整性控制器只传递打印出的路径复审前过完整性门修复报告必须同时含覆盖测试名、命令、输出三要素按输出裁决全部 ADDRESSED 且无新 Critical/Important 破坏 → 追加账本并标记 complete有 NOT ADDRESSED → 下一轮R5或熔断裁决R5范围外发现不阻塞转入账本 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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-developmentSDD技能中每个任务实现完成后都要经过实现 → 评审 → 修复 → 复审的循环。re-review-prompt.md 定义的就是这个循环中最关键的一环——范围化复审scoped re-review的提示词模板复审者不再做一轮全新评审而是只验证上一轮评审的每条 finding 是否已被处理并检查修复 diff 本身是否引入了新问题。读完本文你将理解这个模板每一节的契约语义、七个占位符的填充方式以及它与 SKILL.md 中五轮熔断、评审包脚本scripts/review-package如何协同工作使修复循环在结构上必然收敛。一、为什么复审必须是范围化的模板开篇就定调re-review-prompt.mdUse 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 表格复审范围锁定到 findings 列表——复审者只能对给定 finding 逐条判词并只检查修复 diff 内的新破坏五轮熔断——每任务最多 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 sessions 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每条一个 bulletThe 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].这里有三个要点[FIX_BASE_SHA]的语义是上一轮评审看到的 head而不是任务开始时的 BASE。这是范围化的核心diff 窗口只覆盖上次评审之后到现在的提交即本轮修复本身。[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 包不会与首轮评审的包互相覆盖。只读约束模板明确要求 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 findings 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.拆解成控制器动作序列修复者返回后确认其修复报告三要素齐全覆盖测试、命令、输出运行scripts/review-package PLAN_FILE FIX_BASE HEAD——FIX_BASE是上一轮评审看到的 head。从 review-package 源码可见它会校验两个 SHAgit rev-parse --verify把提交列表、stat、-U10diff 写入按范围命名的文件并打印wrote path: N commit(s), bytes bytes——控制器拿到打印的路径即可diff 内容永不进入控制器上下文填充模板七占位符派发复审子代理按四段式输出更新账本格式为SKILL.md After each round 与实施计划 Global Constraints 中的精确格式供 eval 场景 grepTask 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:linesrc/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复审评审对象任务完整 diffBASE..HEAD仅修复 diffFIX_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 的规则控制器在每一轮修复后应执行的检查点模型行必填[MODEL]显式填写小 diff 复审选低到中档避免继承最贵的会话模型findings 逐字粘贴[FINDINGS]不得改写、不得挑选Critical/Important findings 与 spec gaps 一条一个 bulletFIX_BASE 用对是上一轮评审看到的 head不是任务起始 BASE——用错会把整个任务 diff 拉回复审窗口退化成全量复审diff 包走脚本scripts/review-package PLAN_FILE FIX_BASE HEAD生成按范围命名的文件review-package 已处理 SHA 校验与多提交任务完整性控制器只传递打印出的路径复审前过完整性门修复报告必须同时含覆盖测试名、命令、输出三要素按输出裁决全部 ADDRESSED 且无新 Critical/Important 破坏 → 追加账本并标记 complete有 NOT ADDRESSED → 下一轮R5或熔断裁决R5范围外发现不阻塞转入账本 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
