review-adversarial

review-adversarial

Adversarial review skill with state-tracked review loops. You (the agent) perform the review; the scripts manage findings state and loop convergence.

When to Use

• User asks for a critical/adversarial review of code, a diff, or a design doc
• User wants iterative review passes until issues are resolved
• User asks you to "poke holes" or "find what's wrong"

Review Loop Protocol

1. Initialize:  python scripts/loop.py init [--max-rounds N] [--state PATH]
2. You review the target artifact using an adversarial perspective
3. Record:      python scripts/review.py --state .review-state.json < findings.json
4. Present findings to the user                       <-- TRIAGE GATE, see below
5. User dispositions each one: fix / dispute / accept  <-- do NOT skip or infer
6. Respond:     python scripts/respond.py --state .review-state.json --resolve <id>=<disposition> ...
7. Check:       python scripts/loop.py next --state .review-state.json
   → "continue" — unresolved findings remain or you found new issues; go to step 2
   → "converged" — all findings resolved; done
   → "max_rounds" — hit the limit; produce summary
8. Summary:     python scripts/loop.py summary --state .review-state.json
9. Promote (optional): python scripts/promote.py --state .review-state.json --output docs/reviews/
   → Converts findings to markdown files for tracking via docs-issues skill

The triage gate (steps 4-6) — do not skip it

A finding is a proposal, not a work order. Nothing gets fixed before the user has dispositioned it. This is the step most likely to be skipped, because a well-written finding reads like an instruction and fixing it feels like progress.

Present every finding and get one of three answers:

Disposition	Meaning
fixed	the user wants it fixed — only now may you write code
disputed	the finding is wrong, or the premise does not hold; record the rationale
accepted	real, but not worth fixing; accepted as risk

Batch obviously-correct one-liners into a single question rather than asking one at a time, but un-triaged means un-implemented. Applies to findings you generated yourself, and to findings from a subagent — a tester or reviewer calling something a "regression" is that agent's opinion, not a verdict.

Why this is a hard gate, not advice. Real case (code-monkeys, 2026-09): a tester reported that a config file was unreachable inside containers and labelled it a regression. It was dispatched for fixing within a minute. Correct triage was "do nothing — that code path was already broken in there and nobody uses it". Instead the fix added a dockerfile COPY, a sync line and a two-path resolver; the resolver's failure mode then hung the interactive shell on TAB; that took two more review rounds to find and fix, and the whole design was reverted a day later. Every round of that work descended from one un-triaged finding. The cost of asking is one message. The cost of not asking compounds silently, because each fix is individually defensible.

Two questions worth putting to the user with the findings, not after:

• Is this finding real, and is the premise behind it true?
• Should the behaviour it asks for exist at all — or is refusing/deleting the better answer?

Scripts

loop.py — Orchestration & State

# Initialize a new review session
python scripts/loop.py init --max-rounds 3 --state .review-state.json

# Advance to next round (returns: continue, converged, or max_rounds)
python scripts/loop.py next --state .review-state.json

# Show current status
python scripts/loop.py status --state .review-state.json

# Produce final summary
python scripts/loop.py summary --state .review-state.json

review.py — Record Findings

# Pipe findings JSON into the state file
echo '[{"id":"F1","severity":"major","category":"security","location":"auth.py:42","description":"SQL injection via string interpolation","suggestion":"Use parameterized queries"}]' | python scripts/review.py --state .review-state.json

# Or pass a file
python scripts/review.py --state .review-state.json --file findings.json

Each finding is a JSON object with fields:

• id — unique within the round (e.g., "F1", "F2")
• severity — critical, major, minor, nit
• category — security, correctness, performance, clarity, maintainability, edge-case
• location — file:line or section reference
• description — what's wrong
• suggestion — how to fix it

respond.py — Record Resolutions

# Mark findings as resolved
python scripts/respond.py --state .review-state.json --resolve F1=fixed F2=disputed F3=accepted

# Disputed findings require rationale (prompted interactively or via --rationale)
python scripts/respond.py --state .review-state.json --resolve F2=disputed --rationale "F2:Rate limiting is handled at the LB layer"

Dispositions: fixed, disputed, accepted (accept-risk)

promote.py — Convert Findings to Tracked Issues (optional)

After the review loop converges (or hits max rounds), you can promote findings into docs/reviews/ markdown files for long-term tracking. This integrates with the docs-issues skill for export to GitHub/GitLab/todo.md.

# Auto-classify by category (security/correctness/edge-case→bug, others→debt)
python scripts/promote.py --state .review-state.json --output docs/reviews/

# Explicit classification per finding
python scripts/promote.py --state .review-state.json --output docs/reviews/ \
    --classify F1=bug F2=feature F3=debt F4=question

# Skip nits and disputed findings (default behavior)
python scripts/promote.py --state .review-state.json --output docs/reviews/ \
    --skip nit,disputed

# Preview without writing
python scripts/promote.py --state .review-state.json --output docs/reviews/ --dry-run

Promoted findings are marked promoted: true in the state file, so re-running is idempotent. Each finding becomes one markdown file in docs/reviews/{kind}s/{date}-{slug}.md with full schema (see docs-issues skill).

Adversarial Perspectives

Cycle through these when reviewing (use the prompt template in assets/templates/review-prompt.md):

Perspective	Focus
Attacker	Injection, auth bypass, data exfiltration, privilege escalation
Skeptical User	Error handling, edge cases, misleading behavior, data loss
Future Maintainer	Readability, coupling, hidden assumptions, missing docs
Ops Engineer	Failure modes, resource leaks, observability, deployment risks
Pedantic Reviewer	Naming, consistency, dead code, style violations

Agent Instructions

When performing an adversarial review:

1. Initialize the loop state with loop.py init
2. Read the target artifact thoroughly
3. Adopt one or more adversarial perspectives from the table above
4. Generate findings as structured JSON (use the schema above)
5. Record findings with review.py
6. Present findings to the user in a readable format (table or list)
7. STOP and wait for a disposition on each (fix, dispute, or accept). Writing a fix for an un-triaged finding is the single most expensive mistake this skill exists to prevent — see The triage gate above. Never mark everything fixed at the end as bookkeeping.
8. Record responses with respond.py
9. Advance with loop.py next — if "continue", re-review focusing on:
   • Disputed findings (re-evaluate with the user's rationale)
   • Fixed code (verify the fix, check for regressions)
   • New issues introduced by fixes
10. Summarize when converged or at max rounds

Dependencies

Python 3.6+ (standard library only)