adversarial-review-pipeline
Adversarially review a code change before it ships - a single-agent severity-graded review that works anywhere, an optional three-agent Writer/Breaker/Reviewer pipeline, and an optional five-agent pipeline with a fix loop and browser verification. Use when: reviewing a diff, branch, or PR before merge; checking a feature for bugs, security issues, or unnecessary complexity; asking whether a change is over-engineered or missing edge cases; or setting up a review workflow for a team. Triggers: adversarial review, review this PR, break this change, find problems with this diff, code review, YAGNI check, over-engineering review.
Adversarial Code Review
Review a change the way someone who wants it to fail would. The goal is not to confirm the work is good - it is to find what is wrong with it before it ships.
Three tiers. Tier 1 is the default and needs nothing but the agent you are already talking to. Tier 2 adds a three-agent pipeline. Tier 3 adds a fix loop and browser verification.
The core idea
A review that asks "is this good?" produces reassurance. A review that asks "what would break this?" produces findings. The difference is entirely in the framing of the request.
The strongest single technique: hand the reviewer only the artifact, never the author's reasoning. A reviewer that sees the author's rationale will tend to agree with it. A reviewer that sees only the code has to evaluate the code.
The second strongest: the artifact is the deliverable, not the completion message. See "The artifact rule" below.
Tier 1 — Single-agent review (no dependencies)
This works in any agent session, with no subagents, no second model, no setup.
1. Scope the change
Before reviewing anything, list what the change is supposed to reach. If the change is a diff:
git diff main...HEAD --stat
git diff main...HEAD --name-only
For each changed file, find who depends on it:
grep -rn "<changed_function_or_constant>" --include="*.<ext>" .
A file you cannot list the callers of is a file you have not reviewed. An unreviewed caller is the most common place a "complete" change breaks something.
2. Read the change adversarially
Read the diff once as if you were trying to break it. For each hunk, ask:
| Question | What it catches |
|---|---|
| What input makes this wrong? | Off-by-one, empty set, nil, zero, negative, huge |
| Who calls this, and with what? | Changed contract, wrong caller assumption |
| What happens if this raises? | Missing error handling, partial state |
| What happens if it runs twice? | Missing idempotency, double charge, duplicate row |
| What happens if two requests race? | Race condition, lost update, double spend |
| What happens when the data is absent? | Nil dereference, missing record |
| Who can reach this, and who should not? | Authorization, IDOR, missing scope |
| What is logged, returned, or rendered? | Sensitive data leaking to logs or UI |
| Is this the smallest thing that does the job? | Scope creep, speculative generality |
| Is there already a helper for this? | Reinvention, two implementations drifting |
Then run the tests. A failing test is the highest-value finding available to you, and it is also the cheapest to verify.
3. Grade every finding
Use four severities. The grade decides what happens next, so be honest about the difference between "this is broken" and "I would have written it differently."
| Severity | Meaning | Action |
|---|---|---|
block-merge | Broken, exploitable, or wrong for real users | Must fix before merge |
high | Correctness or security risk on a reachable path | Fix before merge |
medium | Real issue, but bounded or low-impact | Fix if safe, else defer with a note |
low | Style, naming, taste, or a hypothetical | Defer |
Do not inflate. A review where everything is block-merge gets ignored.
If a reviewer is unsure between two severities, take the lower one and say why
you are unsure.
4. Write the report
The report is the deliverable. Put it in a file:
# Review: <short change description>
## Findings
### [block-merge] <one-line title>
**Where:** path/to/file.rb:42
**What:** <the concrete problem>
**Why it matters:** <the user-visible or security consequence>
**Fix:** <the specific change>
## Scope & Skipped
**Verified:**
- <path/behavior you actually checked>
**Not checked:**
- <thing you did not check> — <risk this carries>
## Verdict
ACCEPT / ACCEPT WITH FIXES / REJECT
5. The Scope & Skipped section is required
A review that silently narrows its own scope reads as full coverage when it is not. Name what you did not look at and what risk each omission carries.
## Scope & Skipped
**Verified:**
- Payment capture path, including the retry branch
- Authorization check on both entry points
**Not checked:**
- Webhook signature verification — the handler is new and unexercised.
Risk: forged webhooks accepted.
- Concurrent submission behavior — no test exercises two simultaneous
requests. Risk: duplicate rows under load.
This section is often more valuable than the findings list, because it tells the reader where to look next.
The artifact rule
The file on disk is the deliverable. The completion message is a pointer.
An agent can report completion, summarize its findings confidently, and still have written nothing. This happens with subagents especially, but it is not limited to them.
ls -la review-<slug>.md # confirm it exists and is non-trivial
wc -l review-<slug>.md # a few bytes = the write failed
If the file is missing or nearly empty, do not treat the completion message as proof the work landed. Recover the content from the session transcript before redoing the work, so you do not lose findings that were already produced.
Tier 2 — Three-agent pipeline (Writer → Breaker → Reviewer)
The classic shape: a Writer implements, a Breaker attacks the result without ever seeing the Writer's reasoning, and a Reviewer reconciles the artifact with the findings into a verdict.
Writer -> Breaker -> Reviewer -> Human
(code) (findings) (verdict) (decide)
Each role sees a different slice, and that is the point: the Writer sees only
the requirement, the Breaker sees only the artifact, and the Reviewer sees
both. The role contract, the three prompts, and the verdict format are in
references/three-agent-pipeline.md.
Tier 3 — Five-agent pipeline (Writer → Breaker → Fixer → Spec Writer → Live Tester)
The three-agent pipeline plus a fix loop and browser verification - which is what catches the class of bug that unit tests structurally cannot.
Writer -> Breaker -> Fixer -> Spec Writer -> Live Tester
Use it for user-facing features with forms, redirects, auth flows, or
multi-step wizards. The Breaker and the Fixer are deliberately separate
agents: a model in adversarial mode is good at finding problems and bad at
writing fixes, and an agent that both finds and fixes will rationalize its
own findings. The role definitions, the Fixer prompt, and the ordering rules
are in references/five-agent-pipeline.md.
The YAGNI & DRY review
Every review - single-agent or not - answers five questions explicitly. They catch a class of problem functional testing never will, because speculative code usually works.
- YAGNI. Does the change add generality the task does not exercise - extra
tables, config hooks, extension points, helpers? If the feature does not
need it today, flag it. Severity
highwhen it touches money, state, or auth; otherwisemedium. - DRY. Is the same logic, concept, or validation duplicated? Severity by
blast radius:
mediumfor isolated duplication,highwhen the duplicated logic sits in a money, state, or auth path where the two copies will drift. - Reinvented house component. Did the change build a new helper when the codebase already has one? Name the existing component to use.
- Unnecessary dependency or indirection. Did the change add a package,
wrapper, or conversion layer that the standard library or a few lines could
replace? Severity
medium; name the simpler option. - Worse-is-better. Did the change prefer a large configurable abstraction
over a smaller concrete solution? If the abstraction makes the money,
state, or auth path harder to trace or test, flag
high.
The full lens, the spec-written-to-match-the-implementation failure mode, and
the money/state checklist are in references/review-checklists.md.
Reporting back
Close the review with what changes the reader's next action - not a narration of the steps:
- What was found - finding count by severity, and what was fixed.
- What was skipped - and why.
- The risk they must know about - anything deferred that could bite in production, and anything still needing a product decision.
Do not restate the review checklist or narrate the agents.
Common pitfalls
- Reviewing the diff instead of the change. A diff shows what moved, not what depends on it. Grep for callers.
- Accepting the author's reasoning. Pass the artifact, not the rationale.
- Inflating severity. If everything is
block-merge, the review gets ignored. Grade honestly. - Trusting a completion message over the artifact. Check the file exists.
- Spawning agents in parallel. The roles are a dependency chain.
- Letting the same agent find and fix. It will rationalize its own findings.
- Fixing the spec instead of the code when the spec was written to match the implementation rather than the requirement.
- Reviewing only the happy path. The defects live in the empty state, the boundary, the retry, and the unauthorized caller.
- Omitting Scope & Skipped. Then a narrow review reads as a broad one.
- Running the multi-agent pipeline on a trivial change. The coordination cost exceeds the value.
Completion check
- The change's scope and its callers were listed before reviewing.
- Every finding has a severity, a location, and a concrete consequence.
- The YAGNI & DRY questions were answered explicitly.
- The report exists on disk and is non-trivial.
- A
## Scope & Skippedsection names what was not checked and the risk. - Any test that passed by working around a constraint was probed against the real request shape.
- Money/state checks were run if the change touches money, state, or webhooks.
- A verdict was given: ACCEPT, ACCEPT WITH FIXES, or REJECT.
Related
references/rails-turbo-and-controller-traps.md- the places a Rails framework does something different from what the code looks like it doesreferences/rails-system-spec-review.md- writing Rails system specs from the user's perspective, and the journeys worth walkingreferences/rails-money-and-state-checks.md- Rails-specific money and state checksreferences/rails-review-checks.md- the commands a Rails review runsreferences/three-agent-pipeline.md- Writer / Breaker / Reviewer prompts and the role contractreferences/five-agent-pipeline.md- the Fixer, Spec Writer, and Live Tester rolesreferences/review-checklists.md- YAGNI & DRY, the spec-written-to-match- the-implementation failure, and the money/state checksrails-tdd-standards- RSpec standards this review depends onrails-ci-fixer- CI-only failure patterns for a Rails change
Related skills
- Downloads
- 119All time
- Security audit
- Pass
- Last updated
- 1d ago
- Current version
- v1.0.1
- License
- MIT-0
