/independent-review-loop

name: independent-review-loop
user-invocable: false
description: |
  Independent review loop run before delivery in code work. An independent reviewer (Codex, or fresh Codex-style subagents) reads the whole PR against the approved outcome; the lead fixes in-scope functional findings and re-reviews until none remain. Its differentiator is independence and exhaustiveness — a reviewer that fails differently from the authors, run to clean — distinct from the recursive-refinement ladder. Invoked by the team lead from the unified pre-ship gate (code-mode and /swarm:refine) after the ship steps.
keywords: independent review, codex review, review loop, pre-delivery review, bug surface, edge cases

Operational spec for the **team lead**. This skill runs an independent review pass at delivery: a reviewer that fails differently from the author reads the whole PR against the approved outcome, the lead fixes what is in scope, and the loop repeats until the reviewer finds no more in-scope functional issues. It is the automated form of "ship, then loop the PR through Codex until it stops finding edge cases" — with the lead acting as the operator who keeps findings on-scope.

What distinguishes this from the team's own review and the recursive-refinement ladder is **independence and exhaustiveness**: the reviewer is a different model (Codex) or a fresh-context agent that fails differently from the authors, and it runs to exhaustion — until no in-scope functional finding remains — rather than the bounded rung ladder. (The ladder hunts bugs too, as it drives the work to the full scope of the outcome; the new axis here is the *independent eye run to clean*, not bug-hunting per se.) It is a distinct pass; it never replaces the ladder.

Only the lead runs this. Reviewers (Codex, or fresh subagents) are read-only; the lead is the sole writer, same as every other phase.

When this runs

Invoked from the **unified pre-ship gate** in code-mode's Refine/Deliver (and `/swarm:refine`) — the gate the lead presents once the team reaches 9/10+, offering (thoroughness-descending): *recursive refinement + independent review* / *recursive refinement only* / *independent review loop only* / *ship as is*. This skill runs for the two options that include the independent loop — *recursive refinement + independent review* (after the recursive ladder completes) and *independent review loop only* (on its own); *recursive refinement only* and *ship as is* do not invoke it. Deliver invokes this skill when the `independent-review-loop pending` run-state task recorded at the gate is open — it branches on that recorded task, not on recall of the pick.

It runs **after the ship steps complete** (PR-then-loop on the common path): when a PR was created, the loop reviews the PR's diff and pushes each round's fixes to it; on a commit-only / push-only ship with no PR, it reviews the pushed branch against its base. The diff base is resolvable from the PR when one exists (see the loop's base resolution below for the no-PR fallback).

Engine choice (Codex or Swarm fallback)

**Persisted preference first.** Before asking, read `.claude/swarm-review.md` — the per-project reviewer config. It mirrors the *mechanism* of `.claude/swarm-ship.md` (ask once, read thereafter) but is a separate file: reviewer config is not ship config. If it names a **recognized** engine (Codex or Swarm fallback), use it and **skip both questions below** — print a one-line plain-text notice so the choice is visible and overridable ("Using saved reviewer: <engine> — edit `.claude/swarm-review.md` to change"), no modal. If the file is present but its engine value is missing, garbled, or unrecognized, treat it as **no saved preference** and fall through to the questions below — a typo must never wedge the choice. A saved preference only *selects* the engine; it never *asserts availability*. Still run the runtime check (`command -v codex` + the first call's auth result). If the saved engine is unavailable on this machine, **auto-degrade to the Swarm fallback without a modal** — print a one-line notice ("Saved reviewer Codex unavailable here — using the Swarm fallback for this run") and do **not** rewrite the file. A saved preference must never become a blocking modal on a machine that lacks the tool — that is the portability guarantee (and it differs from an interactive Codex pick that's absent, which may ask). Swarm prompts are portable across machines, so a peer missing Codex neither hangs on a teammate's saved pref nor has it silently overwritten.

When **no** preference is saved, select the reviewer engine with **AskUserQuestion** (header "Reviewer"). Detect Codex once: `command -v codex` (exit 0 = present). Offer **both engines every time** — `command -v codex` only sets the **order/default** and a neutral note. No affordability language, ever. ("No loop" is not offered here — that is the gate's "ship as is.")

• **Codex present** → 1) "Codex" 2) "Swarm fallback".
• **Codex absent** → 1) "Swarm fallback" 2) "Codex *(requires Codex CLI)*".

Descriptions (neutral): Codex = "An independent model (Codex) reviews the whole PR; fails differently from the code's author." Swarm fallback = "A fresh Claude reviewer in a Codex style — sharp, but shares the author's model blind spots; always available, no Codex needed."

**Then ask the scope of that choice** (only when no preference was saved) with a second **AskUserQuestion** (header "Save reviewer"): "Use this reviewer just this session, or always for this project?" — "This session" (default — nothing is written) / "Always" (persist it). Only "Always" writes `.claude/swarm-review.md`, with a single `## Engine` field naming the chosen engine:

# Reviewer Definition
## Engine
[Codex | Swarm fallback]

Persist the engine only — not availability, and not the rate-limit wait policy (the within-cap auto-wait below is default behavior, not a saved knob; the file is structured so a future field can be added withou