debating-code-reviews

Adversarial Debate Code Reviews

Orchestrate a team of 4 specialized reviewers who independently analyze code, then debate each other's findings. Adversarial debate between diverse review perspectives catches significantly more bugs than single-pass review.

Why Debate Works

Single-reviewer code review suffers from blind spots - each reviewer has biases and areas of focus. Adversarial debate forces findings to survive scrutiny:

• Independent analysis prevents groupthink
• Cross-examination eliminates false positives
• Diverse techniques (path tracing, pre-mortem, adversarial testing) cover different bug categories
• Devil's advocate challenges ensure every finding has real evidence

Prerequisites

Agent teams are experimental and disabled by default. Enable them by adding the following to your settings.json or shell environment:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

When to Use

Use the full debate protocol for:

• High-risk changes - Authentication, payment, data migration, security-sensitive code
• Complex cross-module changes - Changes touching 5+ files or multiple system boundaries
• AI-authored code - Code generated by AI that needs confidence before merging
• Critical bug fixes - Fixes where getting it wrong is worse than the original bug

See "When to Skip" at the bottom for lighter alternatives.

The Review Team

Reviewer	Role	Primary Technique	Focus
The Tracer	Correctness	Execution path tracing	Logic errors, edge cases, state bugs
The Architect	Design	Pre-mortem analysis	Patterns, complexity, coupling
The Breaker	Adversarial Tester	Adversarial input + test review	Breaking inputs, test quality gaps
The Prosecutor	Devil's Advocate	Five Whys + assertion verification	False positives, overstated severity

Each reviewer is available as a custom agent in ../../agents/ and is configured with Opus, read-only tools, and this skill preloaded. See ./references/reviewer-personas.md for detailed persona rationale and thinking styles.

Running the Debate

Step 1: Create the Agent Team

Create an agent team with the 4 reviewer agents. They are pre-configured in this plugin's agents/ directory (tracer, architect, breaker, prosecutor).

Teammates don't inherit the lead's conversation history - they only get project context (CLAUDE.md, skills, MCP servers) plus the spawn prompt. Include enough detail about the code change in the prompt for reviewers to work independently.

Create an agent team to review [describe the code change - include file paths,
what the change does, and why].

Spawn 4 teammates using the tracer, architect, breaker, and prosecutor agents.
Require plan approval for the prosecutor (it must wait for Round 1 findings).

Create tasks with dependencies:
- Round 1 tasks (no dependencies, run in parallel):
  - "Tracer: review [files] for correctness" → assign to tracer
  - "Architect: review [files] for design" → assign to architect
  - "Breaker: review [files] for adversarial inputs and test quality" → assign to breaker
- Round 2 tasks (depend on all Round 1 tasks):
  - "Prosecutor: challenge Round 1 findings" → assign to prosecutor
  - "All reviewers: respond to challenges and each other's findings"
- Round 3 task (depends on Round 2):
  - "All reviewers: state final positions with confidence levels"

After Round 3, synthesize all findings into a single report.

Step 2: Round 1 - Independent Review (Parallel)

Tracer, Architect, and Breaker review the code independently. All three run in parallel via the shared task list.

The Prosecutor is in plan approval mode during Round 1 - the lead won't approve its plan until Round 1 tasks are complete.

Each reviewer produces findings with:

• Severity: BLOCKING / WARNING / NOTE
• Evidence: Code quotes, execution traces, or specific scenarios
• Impact: What happens if not fixed

Step 3: Round 2 - Challenge (Sequential)

Round 2 tasks automatically unblock when Round 1 completes (via task dependencies).

1. Lead broadcasts Round 1 findings to all teammates (use broadcast sparingly - it sends to every teammate and costs scale with team size)
2. Prosecutor's plan is approved - it reviews every finding and provides verdicts (CONFIRMED / DISPUTED / DISMISSED)
3. Lead messages Tracer, Architect, and Breaker individually with the Prosecutor's challenges and each other's findings. Each responds.

See ./references/debate-protocol.md for detailed messaging patterns.

Step 4: Round 3 - Final Positions

Each reviewer states final findings with confidence levels (HIGH / MEDIUM / LOW).

The Prosecutor provides final triage for each finding.

Step 5: Synthesize

The lead produces the final report using the template in ./references/synthesis-template.md.

The report sections:

1. Confirmed Findings - Survived debate, ranked by severity
2. Disputed Findings - Reviewers disagreed, needs human judgment
3. Dismissed Findings - False positives or retracted
4. Test Quality Assessment - From the Breaker's test review
5. Debate Highlights - Notable disagreements and discoveries

Severity Definitions

Severity	Meaning	Action
BLOCKING	Incorrect behavior, data loss, or security issue	Must fix before merge
WARNING	Design issue, missing edge case, or test gap	Should fix, may defer with justification
NOTE	Minor improvement or observation	Consider, no action required

Verdicts

Verdict	When to Use
APPROVE	No BLOCKING findings, warnings are minor
APPROVE WITH CHANGES	No BLOCKING findings, but warnings worth addressing
REQUEST CHANGES	One or more confirmed BLOCKING findings

When to Skip

The full 4-reviewer debate is thorough but has a cost (time and tokens). Use lighter approaches for lower-risk changes:

Change Type	Recommended Approach
High-risk, cross-module, AI-authored	Full debate (4 reviewers, 3 rounds)
Medium-risk, single module	2 reviewers (Tracer + Breaker), no Prosecutor
Low-risk, small change	Single reviewer (Tracer for logic, Architect for design)
Documentation, config, formatting	Standard code review, no debate needed

Quick Reference

• Reviewer agents: ../../agents/ (tracer, architect, breaker, prosecutor)
• Persona rationale and thinking styles: ./references/reviewer-personas.md
• Round structure and messaging: ./references/debate-protocol.md
• Report template and triage: ./references/synthesis-template.md