--- name: adversarial-iteration description: > Use when iterating on a fix after an adversarial code review (Codex, human reviewer) surfaces design-level findings — not typos, lint, or formatter work. Frames the review/fix loop as implement -> [review -> REFLECT -> reproducer -> fix -> verify -> handoff] where each round runs in a fresh agent to prevent context accumulation. Provides a four-item cheap-checks list (timeline draw, upstream contract read, full lifecycle trace, variant enumeration) that catches recurring failure classes. No git commits during the loop — all changes commit together after zero-finding termination. Trigger when a review pass surfaces 2+ findings on a single change, when sibling bugs of an "already-fixed" issue keep appearing across rounds, or when the user asks "why did I miss this?". Do NOT use for single-line fixes where the cause is obvious from the diff, or for initial implementation work (use CLAUDE.md rules). --- # Adversarial Iteration Work *with* adversarial review feedback instead of patching symptoms. ## The loop ``` implement -> [spawn round agent -> review -> REFLECT -> reproducer -> fix -> verify -> return summary] --+ ^ | +-------- next round (fresh agent, clean context, re-reads files from disk) <--------------+ terminates when round agent reports ZERO_FINDINGS. ``` Step 1 (implement) is manual. Steps 2+ run inside `/loop` autonomously — no `AskUserQuestion`, `ExitPlanMode`, or other user gates. When multiple approaches exist, tag one "Recommended", pick it, continue. The user can interrupt at any point; you never pause to ask. If agents are unavailable, run the next review inline and re-read all changed files before reviewing. ## REFLECT The unique step. Skipping it produces fixes that pass the named test but seed the next finding in the same class. For each finding, answer: 1. **What did I do wrong?** One sentence, no euphemisms. 2. **Why did I miss it?** Name the assumption encoded without verifying. 3. **Which `CLAUDE.md` rule did I violate?** Be specific. 4. **What cheap check would have caught it?** (see next section) Then across all findings: *what's the unifying shape?* Often a single cognitive failure caused them all. Name it. Common shapes: - **Solved the named problem, not the invariant.** - **Yes-manned own design** — round-1 yes-mans the user; round-2 yes-mans yourself. - **Generic abstraction without per-instantiation audit.** - **Layer-ownership leak via assumed invariant.** - **Tunnel vision on per-unit fix, missed system-level cooperation.** If reflection produces a new shape, add it to this list. ## Cheap checks (do all four before writing fix code) 1. **Timeline draw** — For concurrent state changes, draw the interleaved timeline. Find the check-act gap. Two cooperating booleans is almost always wrong; use `Once`, `compare_exchange`, or a single owner. 2. **Upstream contract read** — For any value flowing in, read the producer's contract (grep, 5 lines). Don't assume from the type name. Ask: does this transformation belong in this layer? 3. **Full lifecycle trace** — For any fix depending on component cooperation, trace init through teardown. List every component and what happens to in-flight work. Especially: what stops first? 4. **Variant enumeration** — For any generic covering N types, list each type's destructor/serializer/contract. Verify the generic satisfies every one. If they differ non-trivially, prefer N type-specific wrappers or parametrize over a closure. ## Reproducer test Write the test **before** the fix. Verify it FAILS on unfixed code — if it passes, it's a tautology. The test must touch the *system* the bug lives in, not just a helper in isolation. Do not commit yet; all changes commit together after the loop terminates. ## Plan-mode discipline Draft a plan (in the response, not via `ExitPlanMode`) referencing: 1. The REFLECT root-cause shape this fix addresses. 2. The reproducer test (file + function) and its assertion. 3. Which cheap check identified the design constraint. 4. The chosen primitive and why it's the smallest satisfying change. 5. Adjacent contracts that also need tests. ## Verify - Reproducer flips red -> green (necessary, not sufficient). - Adjacent-contract tests from REFLECT also pass. - If the next review surfaces a sibling of the same finding, REFLECT wasn't deep enough — go back to REFLECT, don't just patch. ## Round handoff (MANDATORY — blocks next round) Do NOT commit during the loop. All changes accumulate as working-tree edits and are committed once after the loop terminates with zero findings. After verify passes, do these IN ORDER before spawning the next round. Skipping any one is a protocol violation. ### 1. Audit comments `grep -rn 'round\|TODO.*round\|HACK\|FIXME\|debugging\|TEMP' `. Remove round-N narrative, debugging scaffolding, and stale TODOs from the working tree before the next agent reads those files. ### 2. Build round summary Construct this structured summary for the orchestrator to carry forward: ``` ### Round N complete - Findings: - Root-cause shape: - Fixes: - Files changed: - Tests: pass/fail - Remaining risk: ``` ### 3. Spawn fresh agent for next round Read [references/round-agent-prompt.md](references/round-agent-prompt.md) for the agent prompt template. Populate it with: - The round number - All accumulated prior round summaries - The list of changed files Spawn a **general-purpose agent** (not codex:rescue — the round agent needs Read/Write/Edit/Bash for the full REFLECT->fix cycle). The fresh context window is the compaction mechanism — no `/compact` needed. The agent runs its full round (review -> REFLECT -> reproducer -> fix -> verify) and returns a structured round summary. The orchestrator evaluates whether the summary contains `ZERO_FINDINGS`. ## Termination The loop ends when **all three** hold: 1. Latest round agent reports `ZERO_FINDINGS` after re-reading all changed files. 2. Every finding has a reproducer test, verified green. 3. Every adjacent-contract test from each REFLECT passes. No other exit. Sibling findings recurring -> previous REFLECT was too shallow, go back to REFLECT. Fix getting expensive -> plan the architectural change as this iteration's step, same loop. Never propose "stop here, accept risk." ## Anti-patterns - **Reflection-as-apology.** "Should have been more careful" is not a root cause. "Never read `ExecStdout::next`" is. - **Test polarity flip.** If the test was green on broken code, it's confirmation bias, not a reproducer. - **One reproducer, no class coverage.** If reflection identified 6 types and only one has a test, the next review finds the other 5. - **Treating review as checklist.** The review surfaces symptoms; REFLECT finds the design choice that produced them all. - **Skipping agent spawn.** Running the next review in the same context instead of spawning a fresh agent. Accumulated context degrades review quality and wastes tokens. The pull to "just run the review here" is strong — resist it. A new agent re-reads files from disk, not from stale cached content. - **Bloated round summaries.** Including full diffs or debug traces in the round summary defeats the purpose. The summary is compressed signal, not a transcript. Five lines per round, not fifty. ## This project's codebase - Adversarial review: `/codex:adversarial-review` - Loop runner: `/loop` (dynamic-pacing, omit interval) - Commit pattern: all changes commit together after zero-finding termination; conversation history is the iteration audit trail.