adversarial-pair

Files (1)

• SKILL.md

SKILL.md (first lines)

# Adversarial Pair

The canonical "two-voice review" dispatch mechanic. Promotes the cooperative + adversarial pattern from prose-buried-in-CLAUDE.md (and inline sections in `rails:design-feature` / `rails:design-review`) into a **first-class skill** every phase-routed review can point to.

## The failure it prevents

A review run in the **same session as authoring** has its attack voice contaminated by the just-spent author voice. The reviewer is unconsciously protecting the design they just built — congratulating it, missing the very holes the author already half-rationalized. The cheap inline counter-passes that ship with `rails:design-feature` are the *one-agent* version of this problem; they catch the easy stuff and miss the load-bearing weaknesses.

The fix is **two cognitively-independent passes that cannot infect each other** — different agents, different framings, different worktrees, same input artifact. Reconcile their findings cold.

## When to invoke

Fire after a **non-trivial** change is authored, before it's frozen / merged / shipped:

| Phase | Pair runs | Review skill the pair invokes |
|---|---|---|
| Design freeze | After `rails:design-feature` | `rails:design-review` |
| Plan freeze | After `rails:impl-plan` | `rails:impl-plan-review` |
| Threat-modeling | When feature touches auth / payment / multi-tenant / admin / crypto | `rails:threat-model` |
| Pre-PR | After implementation, before opening PR | `rails:ai-pre-review-checklist` + language review (`rails:python-review` / `rails:typescript-review`) |

**The review skill is the *input* to this dispatch mechanic — not a substitute for it.** `rails:design-review` describes what to look for; `rails:adversarial-pair` describes how to run it twice with opposite framings.

### Skip cases

Don't dispatch the pair (single agent / inline pass is enough) when:

- **Pure-docs change** — no production code touched, no risk surface.
- **Pure-fixture change** — unless the fixture is customer-data-leak-prone.
- **Tiny one-file fix** — single function, no new contract, no new caller.
- **Already-frozen artifact unchanged since last pair pass** — re-running on unchanged input is waste.

Skip cases are about cost. The pair burns roughly 2× the tokens of a single review and dispatches two worktree agents. If the change can't justify that, run the inline counter-pass and move on.

## How to dispatch

The dispatch is three steps: spawn two agents in parallel, wait for both, reconcile.

### Step 1 — Spawn both agents in parallel

Send a **single message with two `Task` tool calls** so they run concurrently. Each call uses `isolation: "worktree"` so the agents work on isolated copies of the repo and can't step on each other's notes / scratch files.

```javascript
Task({
  description: "Cooperative review of <artifact>",
  subagent_type: "general-purpose",
  isolation: "worktree",
  prompt: COOPERATIVE_PROMPT,
})

Task({
  description: "Adversarial review of <artifact>",
  subagent_type: "general-purpose",
  isolation: "worktree",
  prompt: ADVERSARIAL_PROMPT,
})
```

(Some Claude Code versions surface this as the `Agent` tool — the parameter shape is identical; the rest of the apex repo standardizes on `Task` per `commands/review-pr.md`.)

### Step 2 — Prompt templates (fill in `{REVIEW_SKILL}` and `{ARTIFACT_PATH}`)

**Cooperative prompt** — steelman the artifact:

```
You are in an isolated git worktree. Use relative paths; do NOT cd to
absolute paths.

Treat the `{REVIEW_SKILL}` skill as your PASS CHECKLIST and OUTPUT SCHEMA
ONLY: read its SKILL.md to learn (a) what passes / conditions / checks to
run, and (b) what output format to use. IGNORE any framing the skill
prescribes — whether it says "attack mode", "adversarial lens", "cold
pass", or anything else. THIS skill's framing (steelman / cooperative)
overrides the review skill's own framing. (Many apex review skills like
`rails:design-review` are explicitly adversarial — that doesn't apply
here; you are the cooperative half of the pair.)

Run every pass in **steelman mode**: find what works, what reuses well,
what's clean. For each pass condition, cite the strongest evidence in the
artifact (`{ARTIFACT_PATH}`) and code (`file:line`) that it's met.

Default to "defensible" unless the evidence forces "unresolved." Your
job is to find what this artifact gets RIGHT — not to invent praise.

Output: follow the `{REVIEW_SKILL}`'s own output schema if it specifies
one (e.g., `rails:ai-pre-review-checklist` produces a step-by-step
checklist; `rails:design-review` produces per-pass verdicts; etc.).
Otherwise emit per-pass findings (defensible / unresolved / can't-tell),
each with `file:line` citations. No prose summary.
```

**Adversarial prompt** — attack the artifact:

```
You are in an isolated git worktree. Use relative paths; do NOT cd to
absolute paths.

Treat the `{REVIEW_SKILL}` skill as your PASS CHECKLIST and OUTPUT SCHEMA
ONLY: read its SKILL.md to learn (a) what passes / conditions / checks to
run, and (b) what output format to use. IGNORE any framing the skill
prescribes — whether it says "steelman", "cooperative", "defensible", or
anything else. THIS skill's framing (attack / adversarial) overrides the
review skill's own framing. (For review skills whose default framing is
already adversarial — like `rails:design-review` — just use their passes
as-is in attack mode.)

Run every pass in **attack mode**: find what's wrong, missing, hand-waved,
or what the author got away with. For each pass condition, name the
specific thing that's unresolved — flow not covered, primitive duplicated
instead of extended, failure mode without user-visible behavior, invariant
quietly broken.

Default to "refuted" unless the evidence forces "defensible." Your job is
to find what this artifact gets WRONG — not to invent gotchas, but to
read the artifact and the code (`file:line`) like a senior engineer
trying to merge the smallest possible diff.

Output: follow the `{REVIEW_SKILL}`'s own output schema if it specifies
one (run the same passes, but in attack mode). Otherwise emit per-pass

From vancourse/apex, MIT.

More from vancourse/apex