dual-round-review

Dual-Round Adversarial Review

Overview

Large model programming faces three core pitfalls:"Sycophancy"、"Palliative Patching" as well as "Review Hallucination and Over-engineering"。

This skill, througha dialectical dual-round cascaded adversarial review mechanism, builds a high-confidence quality breakwater before code is delivered and merged:

• Round 1: An extremely harsh red-team destroyer and prober of underlying physical/business essence (Non-Compliant perspective), specializing in first-principles penetration and extreme destruction.
• Round 2: A pragmatic and rigorous senior system architect—specifically judging the Round 1 reviewer (Review the Reviewer), separating truth from falsehood, intercepting over-engineering, and synthesizing the final definitive verdict.

graph TD
    Code["代码修改 (Base..Head) + 需求规格 (Spec)"] --> R1["第一轮: 红队与第一性原理审查<br>(独立纯净上下文 / Non-Compliant 视角)"]
    R1 --> R1Out["《第一轮审查报告》<br>(第一性原理质询 / 攻击路径 / 隐患清单)"]
    R1Out --> R2["第二轮: 架构师元审判 (Review the Reviewer)<br>(去伪存真 / 防过度工程 / 次生破坏评估)"]
    R2 --> Verdict{"终审裁决判定<br>(Final Verdict Synthesis)"}
    Verdict -->|存在阻断项 Blockers > 0| Fix["实施精准修复 (Surgical Fix)"]
    Fix -->|修复完毕且测试通过| R1
    Verdict -->|阻断项清零 Blockers == 0| Pass["准予进入交付 / 提交流程 ✅"]

---

Invariants

1. Context Isolation: R1 and R2 each run in independent sub-agents, receiving only the Spec, Diff, and (for R2 additionally) the R1 report; the main session chat history is not passed in.
2. Real Output First: The main agent outputs no review conclusion before the sub-agents actually return; the final verdict is generated only from R2's real results.
3. Scope Lock: Candidate defects must be marked as to whether they were introduced by the current change; historical technical debt is recorded in Suggestion/Backlog.
4. Evidence Support: Rejecting or downgrading an R1 rating must be accompanied by 文件:行 -level counter-evidence; downgrades without evidence do not take effect.
5. Two-Layer Persistence (State + Evidence): Each round's conclusion is written to .review-context/review-<baseline-sha>.md(runtime state, already gitignored) for re-loop reading of Previous Blockers and iteration count;at the same time, the full text of the Review Report returned by the sub-agent must be archived verbatimto <归档根>/<YYYY-MM-DD>-<slug>/(delivery evidence, committed to the version repository, see step 1.6).Replacing the full report archive with a summary is strictly prohibited。
6. Bounded Convergence: When the same module has not cleared blocking items after 3 consecutive dual-round cycles, produce a dispute focus report and escalate to human adjudication; fix convergence is kept within the minimal change scope.
7. Register Upon Dispatch: Before dispatching R1/R2, maintain in .goal-loop/dispatch-ledger.md the dispatch ledger details (role, backend handle, baseline SHA,dispatch count, status), and keep a one-line derived summary at the plan checkpoint. If not returned within budget, close out according to goal-loop of the references/host-adapters.md skill §5;the re-dispatch limit for the same role against the same baseline is 2 times; overdue interruptions count toward the loop count of Invariant 6. When resuming across sessions, read the ledger details first; if the details are lost, use the plan summary as the anchor, and reconstructing dispatch state from memory is prohibited.

---

Review Modes

Mode	Rounds	Applicable Scenarios	Output
Full (default)	R1 red team → R2 meta-judgment	Heavy Track / core architecture / critical business paths / Pre-Merge	Final verdict detail table
Light (single round)	R1 Red Team only + lightweight adjudication	Fast-Track / local targeted changes / no impact on public contracts or core paths	R1 report + lightweight adjudication table
Delta (recycle)	Recycle of Full or Light	After blocking items are fixed, use the fix commit as the new baseline	Updated review record and final adjudication

Light Mode Procedure：

1. Dispatch R1 only (using the round-1-red-team.md template,Review Mode: LIGHT_REVIEW）；
2. The main agent adjudicates directly against verdict-rubric.md and outputs an adjudication detail table (reusing the 7-column structure of §4, with "Original R1 Rating" and "Final Adjudication" filled in by the same adjudicator);
3. After blocking items are fixed, recycle according to Delta;Trigger conditions for escalation to Full: changes touch public contracts, core business paths, authentication/concurrency/data consistency, or a PR/release is about to be merged;
4. The basis for Light's exemption and the escalation decision are written into the review record (step 1.5); if driven by goal-loop , they are also written into its plan checkpoints.

---

When to Use

Mandatory

• Core architecture changes: involves global data flow, state machines, multi-module contracts, or cross-domain architecture adjustments.
• Key business logic implementation: authentication and authorization, payment transactions, concurrent scheduling, complex algorithms, and other core trunk paths.
• High-risk defect fixes: investigating and fixing hidden concurrency deadlocks, memory/handle leaks, and issues unresolved after multiple attempts.
• Delivery and Merge Gate (Pre-Merge Gate): before the final PR merge or version release.

When NOT to Use

• Pure copy adjustments, spelling error corrections, style tweaks with no business logic.
• Temporary exploration scripts (Scratch scripts) or speculative Prototype validation.
• Mechanical constraints already fully covered and automatically fixed by rule tools (Linter/Prettier/TypeChecker).

---

Core Process Workflow

As the Main Agent, please execute the review strictly according to the following 5 steps:

1. Pin Baseline & Context

Determine the review mode (uncommitted changes, staging area, or Commit range), and run the auxiliary script to extract structured context:

# 技能目录随安装方式而定（源码仓库通常为 skills/dual-round-review，安装后通常为 .agents/skills/dual-round-review）
SKILL_DIR="<dual-round-review 技能实际所在目录>"

# 智能模式（优先未提交改动，无改动则检查最近一次 Commit）+ 启用交付凭据归档 scaffold（RFC-0001）
bash "$SKILL_DIR/scripts/prepare-review-context.sh" --slug=<交付单元slug>

# 或指定提交区间（归档根可用 --archive-root=<路径> 覆盖，默认 docs/project/reviews）
bash "$SKILL_DIR/scripts/prepare-review-context.sh" --slug=<交付单元slug> [BASE_SHA] [HEAD_SHA]

• Ensure the following are ready: ① Git Diff content and change statistics; ② Requirements design or task description (Spec); ③ Repository coding standards; ④ (conditional) When frontend artifacts are delivered:frontend-qa-gateThe conclusion of the "Frontend Acceptance Report" must be PASS (subject to check-qa-report.sh --require-verdict=PASS --min-assertions=15 mechanical verification); if FAIL / BLOCKED (including unverified items), first handle it according to that skill's backflow routing, and do not proceed to review release.

1.5 Review Record Anchor

The short-cycle state of the review loop must be persisted, to avoid losing Previous Blockers and the iteration count after context truncation. Create one record file per baseline .review-context/review-<baseline-sha>.md(this directory is already in .gitignore ignored), with the schema fixed as follows:

# 审查记录 · <baseline-sha>
- **模式**: [full | light | delta]
- **基线**: <BASE_SHA>..<HEAD_SHA>
- **轮次**: [1 | 2 | ...]
- **迭代计数**: [n/3]
- **Previous Blockers**: [上一轮坐实的 Blocker 稳定 ID 列表，或 无]
- **Round 1 结论**: [报告摘要或报告文件路径]
- **终审裁决**: [🔴 阻断交付 | ✅ 准予交付 | 未定]
- **阻断项统计**: [🔴 X / 🟡 Y / ⚪ Z]

Recovery rule: Before entering the review, if a record for the same baseline already exists, first read that file to recover the round,Previous Blockers and iteration count, then decide whether to continue, recycle, or escalate. The record file is by prepare-review-context.sh generate, or manually create per the above schema. If the anchor contains an "Archive Index" section,at the same timeread from that archive root the README.md round ledger, and restore the previous round's report file path and its SHA256 fingerprint (Delta recirculation verifies based on this that the report has not been rewritten).

1.6 Review Evidence Archive

The full review report is anon-reconstructabledelivery evidence: once the session ends, the sub-agent's reasoning chain, attack path derivation, and 文件:行 counter-evidence vanish permanently (this repository has seen an archive summary that itself stated "full text see session record"). Therefore it must be stored in layered fashion together with the runtime anchorlayered to disk：

Layer	Location	Lifecycle	Enter version control
① Runtime state	.review-context/review-<baseline-sha>.md	One review cycle	❌ (already gitignored, correct design)
② Delivery evidence	<归档根>/<YYYY-MM-DD>-<slug>/	Delivery audit period	✅
③ Mechanical gate	scripts/check-review-report.sh	—	✅

• Archive root: recommended default docs/project/reviews/; if the host project already has an established review record convention (an existing reviews/ directory or a doc-governance variant)the host convention prevails, and register the actual archive root in the anchor's "Archive Index" section.
• Naming convention: one directory per delivery unit (shared across all Delta recirculation rounds; the directory name's date is thefirst review date); round files are <轮次标记>-<base7>..<head7>.md, and the round marker is r1 / r2 / delta-r1 / delta-r2。
• Archive index README.md round ledger schema:| 轮次 | 基线 | 派发句柄 | 报告文件 | SHA256(前 12 位) | 结论 |。
• Write responsibility boundary: R1/R2 sub-agents' Read-Only constraint remains unchanged; themain agentupon receiving the real returnwrites verbatim to diskand registers the SHA256 (sha256sum <报告文件> | cut -c1-12). The fingerprint can mechanically detectpost-hoc tampering and whole-file truncation; itdoes not coverrewriting, compression, and selective excerpting during transcription (this residual is a known trade-off explicitly registered in RFC-0001 §7.3 A1; transcription distortion is borne by D4's R2 file channel).
• Gate: after archiving is complete, run bash "$SKILL_DIR/scripts/check-review-report.sh" <归档目录>; for delivery-release scenarios additionally run --require-verdict=PASS. Check items: index fields complete / report present and non-empty / fingerprint consistent / R1 five blocks / R2 three blocks / stable IDs aligned across the two rounds / still complete after fence stripping.
• Anomaly degradation：
  1. Write-to-disk failure (permissions, disk) → close out per goal-loop 's references/host-adapters.md §5 and record the interruption reason;it is strictly forbidden to declare the review passed with no archive；
  2. Host has no docs/ structure → select the archive root per the "host-first" principle and register it in the anchor;
  3. Delta recirculation same-name file conflict → treat as a baseline drift defect,must not overwritethe existing report.

2. Dispatch Round 1 Review: Red Team and First Principles (Dispatch Round 1)

Context isolation red line: dispatch independent sub-agents,passing in the main session's chat history is strictly forbidden. Use round-1-red-team.md prompt template:

• Dispatch Capability (Host-Agnostic): Use the current host's actual sub-agent dispatch capability, selecting by capability semantics, not bound to a specific tool name or platform (subject to the tools declared in this session).
• Dispatch Mode Determination：
  • Synchronous Dispatch(the call returns the result within this turn): directly retrieve the R1 report in the current turn and then continue to Step 3;
  • Asynchronous Dispatch(a handle is returned first and wake-up occurs later via message): after starting, end the current turn and wait for wake-up, then continue only after receiving the real report;
  • The determination is based on the tool's return semantics, not the platform name.
• Role Preset: Extremely harsh, non-compliant, presupposing that the code must contain hidden defects.
• Review Focus：
  1. Diff-Scope Boundary Lock: For the complete rules, see verdict-rubric.md §3; the prompt dispatched to R1 must inline this rule (sub-agent contexts are isolated and cannot read this file on their own).
  2. First-Principles Penetration: Is it a superficial patch? Is there a native minimalist solution?
  3. Runtime Reality Dimension (Conditionally Activated): Activated only when the diff touches client/SSR code (for determination conditions and details, see round-1-red-team.md conditional dimension block); skip this dimension for non-frontend changes.
  4. Red-Team Adversarial Stress Testing: Construct extreme concurrency races, exception injection, resource leaks, and contract-breaking paths.
  5. Targeted Delta Re-Loop: If this is a re-loop after a Blocker fix, focus the audit on whether the previous round's Blocker was fundamentally resolved and whether the fix patch itself introduced secondary defects.
• Real-Output Discipline: Before the real R1 report is returned, do not output any review prejudgment or hypothetical report, and do not dispatch R2 in advance; during asynchronous dispatch, end the turn and wait for wake-up.
• Dispatch Budget: R1's waiting budget is 1 checkpoint cycle. If it does not return before the deadline, it is judged an overdue event and handled per the goal-loop skill's references/host-adapters.md §5 closure (interrupt → record to disk .review-context/review-<baseline-sha>.md → alternative path → update dispatch ledger),indefinite waiting is strictly prohibited. Interrupting and truthfully recording does not violate real-output discipline; passing off an empty report as a review conclusion is what violates it.
• Persist Review Records and Archive Report: After receiving the R1 report, complete in sequence ① write the Round 1 field of .review-context/review-<baseline-sha>.md (see Step 1.5); ② archive thefull report verbatimas <归档根>/<date>-<slug>/r1-<base7>..<head7>.md, and register the baseline, dispatch handle, filename, first 12 digits of SHA256, and conclusion in the archive index round ledger; ③ run check-review-report.sh to confirm the structure is verifiable.Only after archiving is complete may you proceed to Step 3。
• Obtain the "First-Round Adversarial Review Report" returned by the sub-agent.

3. Delegate the second round of review: Meta-Architect Trial (Dispatch Round 2)

In After completely receiving the real output report from the first-round review sub-agent, only then can a second independent sub-agent be dispatched, using the round-2-meta-architect.md template:

• Dispatch capability and mode: follow the host-agnostic dispatch rules and synchronous/asynchronous determination from step 2 (if synchronous, retrieve in this turn; if asynchronous, end the turn and wait to be woken).
• Input content：Spec + Git Diff + Full text of the first-round review report (must use the actual content returned by R1; the main agent is strictly forbidden to fabricate it)。
• Role preset: a pragmatic and rigorous senior system architect—specifically to judge the first-round reviewer (Review the Reviewer)。
• Review focus：
  1. Boundary Enforcement: verify whether R1's candidate Blockers were introduced by the current change; downgrade historical technical debt to Suggestion/Dismissed (rules see verdict-rubric.md §3）。
  2. Separate truth from falsehood: investigate whether R1 produced hallucinated false positives due to lack of context.
  3. Prevent over-engineering (YAGNI): reject R1's overly abstract, complex layered, or impractical dogmatic suggestions.
  4. Secondary damage assessment: assess whether adopting the fix suggestions would induce a broader destructive refactor.
  5. Batch downgrade red flag: when R2 downgrades or rejects multiple P0/P1 items from R1 all at once, it must provide item-by-item 文件:行 -level counter-evidence; the main agent spot-checks, and those with insufficient evidence are sent back to R2 for re-review.
• Authentic output discipline: before R2's actual verdict is returned, do not output the "Final Verdict"; the final verdict must be generated based on R2's actual results (when dispatching asynchronously, end the turn and wait to be woken).
• Dispatch budget: same as R1 (waiting budget of 1 checkpoint cycle); if overdue, follow goal-loop skill's references/host-adapters.md §5 to close out and persist to disk.
• Persist review records and archive report: after obtaining the R2 verdict, complete in order ① write the final-review fields of .review-context/review-<baseline-sha>.md (see step 1.5); ② archive thefull text of the final verdict verbatimas <归档根>/<date>-<slug>/r2-<base7>..<head7>.md and register it in the round ledger; ③ run check-review-report.sh --require-verdict=PASS to confirm the release conclusion can be mechanically verified.Only after archiving is complete may you proceed to step 4。
• Obtain the "Final Verdict Detail Table" output by the final review.

4. Verdict Triage and Qualitative Handling (Verdict Triage)

Strictly check against verdict-rubric.md to determine the conclusion:

• 🔴 Blockers (P0/P1)：
  • Conclusion: review not passed.
  • State machine locked: the task status is forced to remain "in progress/not passed",it is strictly forbidden to declare passage on your own after modifying the code。
  • Action: immediately implement a precise root-cause fix (Surgical Fix),never modify irrelevant code along the way. After fixing, run the full test suite to confirm it passes and perform an atomic commit.
  • Delta Re-Loop Protocol: use the fix commit as the new baseline, and pass Previous Blockers(stable ID list) in the prompt.
    • Full-Delta: re-dispatch the full R1 → R2 closed loop from step 2; R1 focuses on the Blocker fix evidence and direct secondary regressions, and R2 gives the final release approval;
    • Light-Delta: Only re-dispatch R1 and re-adjudicate per the Light procedure (no R2), applicable after fixing a Blocker hit in Light mode;
    • Both read the iteration count from the review record to prevent baseline drift and divergence.
• 🟡 Optimization Suggestions (Suggestions, P2/P3)：
  • Conclusion: Approved for release.
  • Action: Record in the project to-do or follow-up optimization list; does not block this delivery.
• ⚪ Dismissed Items (Dismissed)：
  • Action: Discard directly; no code changes required.

5. Convergence Guardrails

• Precise Convergence Principle: When fixing blocking items, strictly converge the scope of changes to prevent the review loop from diverging due to new variables introduced by incidental refactoring.
• The 3-Tries Rule: If for the same module, 3 consecutive times dual-round loops fail to clear the blocking items, or R1/R2 fall into an irreconcilable philosophical dispute:
  1. Immediately stop the automatic loop.
  2. Compile the "Dual-Round Review Dispute Focus Report" (including the disputed code, both rounds' viewpoints, and potential risks).
  3. Escalate to a human engineer (the user) for final adjudication.

---

Rationalizations & Pitfalls

Typical Rationalizations / Wishful Thinking	Real-World Harm and Countermeasures
"The change is only a few lines, no need to run dual rounds"	Most catastrophic deadlocks or memory leaks come precisely from 1-2 lines of uncaught asynchronous state changes. The shorter the code, the more you need to check whether it is a "shallow band-aid".
"The first round raised many comments, I changed everything accordingly"	Strictly forbidden to accept everything wholesale! R1 easily produces over-engineered suggestions detached from reality; pseudo-requirements must be filtered through R2 architect meta-adjudication.
"R1 flagged many legacy issues, fix them all as Blockers"	⛔ Severe Violation (review scope creep and historical overreach)! Historical technical debt not introduced by this change should be downgraded to Suggestions per verdict-rubric.md §3 and recorded in the to-do; otherwise the PR cannot converge and secondary regressions are introduced.
"All jsdom unit tests are green, so there won't be runtime issues" (frontend/SSR projects only)	⛔ Ignoring the real runtime environment! jsdom does not check Next.js SSR hydration mismatches, Safari private browsing mode's SecurityError or production build/runtime crashes caused by conditional early-return Hook calls. Specialized checks must be performed.
"I can just think through both rounds myself in the main session"	A single context inevitably hasself-confirmation biasand sycophantic tendencies. Context isolation must be achieved through sub-agents.
"Fixed one blocking item, just re-review the second round"	The fix patch may introduce new secondary defects; R1 must be re-run; in Full mode R2 must also be re-run to complete the loop.
"Changed it per the architect's opinion and all unit tests are green, no need for dual rounds again"	⛔ Severe Violation (self-verification bias and secondary defect blind spots)! Fixing the code itself can very easily introduce more fatal secondary disasters (such as data wiping or state deadlock). All-green unit tests absolutely cannot replace the external two-round adversarial process; the fix commit must be used as input and R1 must be re-delegated to start the cycle again.
"After launching the sub-agent, I'll go ahead and write out the verdict for the user to see"	⛔ Serious violation (false premature answer)! Before the sub-agent has actually finished its reasoning, the main agent presuming to produce output on its own will cause the review to become a mere formality and may even conceal real defects. When dispatching asynchronously, end the turn and wait; when dispatching synchronously, also wait until this call returns a report before producing conclusions.
"Launch both rounds of review sub-agents in parallel at the same time"	⛔ Violates the cascade first principle! The essential mission of R2 is to judge R1 (Review the Reviewer). Without R1's complete output, R2 has no basis on which to judge at all; launching in parallel is strictly prohibited.
"The report summary has already been written into the anchor, so it counts as archived"	⛔ Serious violation (loss of credentials)! The summary contains only conclusion statistics; R1's attack-path reasoning,文件:行 evidence and R2's counter-evidence chain all remain in the session and will permanently disappear once the session ends.It is strictly prohibited to archive a summary in place of the full report: the original text returned by the sub-agent must be written verbatim into <归档根>/<date>-<slug>/ and the SHA256 fingerprint must be registered (see step 1.6).
"R1 is taking a long time to return, so I'll send R2 out first to advance in parallel" "Since R2 can't get R1's report, I'll treat its independent opinion as the final verdict"	⛔ Violation (concurrency circumvention + empty report masquerading)! The former violates the cascade order, and the latter swaps "independent verification with no input" for "two-round adversarial conclusion". Correct handling: close out that sub-agent according to the dispatch budget — interrupt → record the reason for interruption → choose an alternative path (re-dispatch to the original backend with a narrowed scope / switch to an isolated backend;when isolation cannot be guaranteed for review-type tasks, escalate to human adjudication — inline self-review does not constitute any round of review) → update the dispatch ledger (execution-type dispatches have a separate inline exception, see goal-loop skill's references/host-adapters.md §5.4(d), but its results must not be used for any review round); R2 must receive R1'sfull real reportbefore it can be dispatched.

---

Reference Documents and Practical Case Navigation

Procedure and Prompt Reference

• verdict-rubric.md - Verdict grading standards and severity determination rules
• failure-modes-catalog.md - Library of high-frequency failure modes in LLM code generation and review
• round-1-red-team.md - First-round red team and first-principles sub-agent task template
• round-2-meta-architect.md - Second-round meta-judgment senior architect sub-agent task template
• check-review-report.sh - "Delivery Credential Archiving" structural mechanical gate (index fields / fingerprint consistency / two-round blocks / stable ID alignment;--require-verdict=PASS for delivery release)

Practical Exercise Cases

• case-1-palliative-patch.md - Case 1: Identification and blocking of shallow patching (band-aid fixes)
• case-2-over-engineering.md - Case 2: Screening of over-engineering and armchair theorizing (rejection items)
• case-3-concurrency-race.md - Case 3: Identification of hidden asynchronous races and resource leaks (confirmed blocking items)
• case-4-clean-pass.md - Case 4: First-principles compliant implementation (blocking items cleared, delivery approved)