# Adversarial Review

> Rigorous code review of completed implementation before committing. Use for features, refactors, and critical-path changes — not trivial changes (this is expensive).

- Skill: `steveclarke/adversarial-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add steveclarke/adversarial-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/steveclarke/adversarial-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: steveclarke (https://skillmd.com/u/steveclarke)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/steveclarke/adversarial-review

---


# Adversarial Review

Automated critique-fix loop using **fresh-eyes** review. Each round, the code is
reviewed cold — no knowledge of why decisions were made, no attachment to the
implementation. Critical and Suggestion findings get fixed, then a fresh review
checks again. Loop stops when only Nitpicks remain or after 3 rounds.

## Execution — Harness-Neutral

The contract is the **fresh-eyes critique-fix loop**, not any one mechanism:

- **Claude Code** — spawn a *new* reviewer subagent each round (Agent tool,
  `subagent_type: general-purpose`) so the reviewer literally has no memory of the
  code or prior rounds. This is the strongest form of "fresh eyes."
- **Codex / other single-agent harnesses** — run the loop yourself: each round,
  re-read the diff cold and review it as if you'd never seen it, deliberately
  setting aside what you know about why it was written. No subagent required; the
  fresh-eyes discipline is what matters, not the process boundary.

Everything below describes the loop in Claude's subagent terms — a single-agent
harness maps "spawn a reviewer" to "do a cold review pass" and "fresh subagent"
to "re-read from scratch."

## When to Use

- After implementation, before committing — especially for features and refactors
- When changes touch critical paths, security-sensitive code, or complex logic
- When you want a review that's harder than what you'd give yourself
- Position in pipeline: `implement → /simplify → /adversarial-review → /finalize → commit`

## When NOT to Use

- Trivial changes, docs-only, config tweaks — use `/simplify` + `/finalize` instead
- Mid-implementation — finish building first, then review
- When you just want a quick sanity check — use `/code-review` instead

## Input Modes

Parse `$ARGUMENTS` to determine what to review:

- **No args:** review uncommitted changes — run `git diff` and `git diff --cached` to get staged + unstaged changes
- **File/dir paths:** review specific files — read them directly and present as the code to review
- **`--base=<ref>` / `--fork=<sha>`:** an explicit base or fork point to diff against (a caller like `/ship` passes this so the review sees exactly the diff it inventoried). If given, review `<fork-or-base>...HEAD` and skip the auto-resolution below.
- **`--pr` flag:** review the full branch diff. **Resolve the base robustly** — don't assume `main`. Use the existing PR's base, else the repo default branch, resolved to a ref that exists locally, then the true fork point:
  ```bash
  BASE="$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || echo main)"
  if git rev-parse --verify --quiet "$BASE" >/dev/null; then BASE_REF="$BASE";
  elif git rev-parse --verify --quiet "origin/$BASE" >/dev/null; then BASE_REF="origin/$BASE";
  else echo "No base ref for '$BASE' — fetch it and retry"; exit 1; fi
  FORK="$(git merge-base "$BASE_REF" HEAD)"
  git diff "$FORK"...HEAD
  ```

If the diff is empty, tell the user there's nothing to review and stop.

## Step 1: Gather Context

Before dispatching the reviewer, collect two things:

### The diff

Collect the diff based on the input mode above. This is what the reviewer will critique.

### Project conventions

Search the project for convention docs the reviewer should know about. Look for:

- CLAUDE.md files (project root and nested directories)
- Guide/convention docs in common locations: `project/guides/`, `docs/`, `.cursor/rules/`, `AGENTS.md`
- Lint and style config files (`.rubocop.yml`, `.eslintrc.*`, `.prettierrc`, `standardrb` config, etc.)

**Budget:** Keep convention context to ~5K tokens. Include CLAUDE.md files and lint configs. Do NOT include full implementation guides, feature docs, or READMEs — the reviewer is reviewing code quality, not feature completeness. If convention material exceeds the budget, prioritize CLAUDE.md files first, then lint configs.

## Step 2: Dispatch Reviewer Subagent

Use the **Agent tool** to spawn a reviewer:

- `subagent_type`: `general-purpose`
- `description`: `"Adversarial code review — round N"`
- `prompt`: the full reviewer prompt below, with `{conventions}` and `{diff}` replaced with the actual content

### Reviewer Prompt

```
You are a senior developer doing a cold code review. You have never seen this
code before. You have no context on why decisions were made. You did not write
any of this. Review with completely fresh eyes.

## Project Conventions

{conventions}

## Code to Review

{diff}

## Review Criteria

Be opinionated. Review for:

- **Correctness:** bugs, logic errors, edge cases, race conditions
- **Security:** injection, auth bypass, data exposure, OWASP top 10
- **DRY:** duplicated logic that should be extracted
- **Modularity:** classes/methods doing too much, unclear boundaries
- **Testability:** code that's hard to test, missing test coverage
- **Simplicity:** over-engineering, unnecessary abstractions, premature generalization
- **Architecture:** does it conform to the project's established patterns and conventions?
- **Naming:** unclear or misleading names
- **Error handling:** swallowed errors, missing edge cases

## Output Format

Return findings as a list. Each finding MUST have:

- **Severity:** Critical | Suggestion | Nitpick
- **Location:** file path and line range
- **Issue:** what's wrong
- **Fix:** specific, concrete recommendation

Severity definitions:
- **Critical** = bugs, security issues, data loss risk, broken functionality
- **Suggestion** = improvements that meaningfully affect quality, maintainability, or conformance
- **Nitpick** = style preferences, minor naming quibbles, cosmetic issues

Be thorough but honest about severity. Don't inflate Nitpicks to Suggestions.
If the code is solid, say so — an empty findings list is a valid result.
```

## Step 3: Process Findings

When the reviewer subagent returns:

1. Read through the findings
2. **Fix** all Critical and Suggestion items directly in the code
3. **Skip** any finding that conflicts with established project conventions or prior discussion in this session — note why you skipped it
4. **Log** Nitpick items without acting on them
5. Track what was found and fixed this round

Use your judgment. If a finding is wrong or would break something, skip it and note why. The reviewer has fresh eyes but lacks your conversation context — you know things it doesn't.

## Step 4: Loop

After applying fixes:

1. Collect the new diff — compare against the **original baseline** (not the previous round). The reviewer should see the full changeset each time, not just the fixes.
2. Spawn a **fresh** reviewer subagent with the updated diff. Do not reuse the previous subagent.
3. Repeat until one of these conditions is met:
   - **Only Nitpick findings remain** → stop, the code is clean
   - **3 rounds completed** → stop, report any remaining non-nitpick findings

## Step 5: Report

Present a summary when done:

```
## Adversarial Review Complete

**Rounds:** N of 3
**Result:** [Clean — only nitpicks remain | Capped — N issues remain after 3 rounds]

### Round 1
- [Critical] file.rb:12-15 — description (FIXED)
- [Suggestion] file.rb:30 — description (FIXED)
- [Nitpick] file.rb:45 — description

### Round 2
- [Nitpick] file.rb:32 — description

### Remaining Nitpicks
- file.rb:45 — description
- file.rb:32 — description
```

If the first round returns no findings at all, report that the code passed clean and stop.

## Common Mistakes

- **Reusing the same subagent** for round 2 — it remembers its own findings and loses the "fresh eyes" benefit. Always spawn a new one.
- **Diffing fixes only** instead of the full changeset — the round 2 reviewer should see everything, not just what changed since round 1.
- **Applying every finding blindly** — you have conversation context the reviewer lacks. Use judgment. Skip findings that conflict with project conventions or prior decisions, and note why.
- **Running this on trivial changes** — this is expensive. If you just renamed a variable, use `/simplify` + `/finalize` instead.