debating-code-reviews

What this skill does

# 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:

```json
{
  "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`