Peer Review

# Peer Review

Use a second AI agent to review and challenge the first agent's work. The peer reviewer exists to find
what the builder missed -- not to agree, not to be polite, and not to rubber-stamp. This is the
single most effective quality gate you can add beyond automated tests.

## Core Principle

> **The peer reviewer's job is to find what the builder missed, not to agree.**

A review that says "looks good" is a wasted review. The peer review model should be given explicit
instructions to be critical, to challenge assumptions, and to look for what is *not* there rather
than what is.

---

## Why Peer Review Works

LLMs have blind spots. Every model has patterns it over-relies on, edge cases it misses, and
architectural assumptions it makes implicitly. A second model -- or the same model with a different
prompt and role -- catches a different set of issues.

**The analogy:** In traditional engineering, code review exists because the author has cognitive
blind spots about their own work. The same principle applies to AI agents, but the blind spots are
different: they are systematic patterns in training data, context window limitations, and prompt
interpretation biases.

**What peer review catches that automated tests miss:**
- Architectural over-engineering or under-engineering
- Missing error handling patterns
- Security vulnerabilities the builder didn't consider
- Cavekit requirements that were technically met but poorly implemented
- Dead code, unused imports, and unnecessary complexity
- Performance pitfalls that only manifest at scale
- Missing edge cases not covered by the cavekit

---

## Review Modes

| Mode | Timing | Mechanism |
|------|--------|-----------|
| **Diff Critique** | After implementation completes | A second model inspects the changeset with a fault-finding prompt; the builder incorporates valid fixes |
| **Design Challenge** | During the planning phase | A second model proposes alternative designs; the builder evaluates both against spec requirements and selects the stronger option |
| **Threaded Debate** | When exploring complex trade-offs | Multiple exchanges occur on a persistent conversation thread so context accumulates across turns |
| **Delegated Scrutiny** | For substantial review tasks | A dedicated teammate agent manages the full peer review interaction and delivers a consolidated findings report to the lead |
| **Deciding Vote** | When two approaches conflict | The lead presents both options to the peer review model, which analyzes trade-offs and recommends a path forward |
| **Coverage Audit** | During the validation phase | Test coverage data and gap analysis are fed to the peer review model for independent assessment of testing thoroughness |

### Choosing the Right Mode

```
Need peer review
├─ Reviewing completed code?
│   ├─ Small changeset (< 500 lines) → Diff Critique
│   └─ Large changeset or full feature → Delegated Scrutiny
├─ Designing architecture?
│   ├─ Single decision point → Deciding Vote
│   └─ Full system design → Design Challenge
├─ Debating trade-offs?
│   ├─ Need extended back-and-forth → Threaded Debate
│   └─ Need a decisive answer → Dec