Review Loop

Drive a code/PR change through independent review, verification, disposition, repair, and full re-review. Each finding ends in a verified repair, a cited drop, a successor handover, or declared residual. Measure the artifact against the project's own stated goal and governing conventions, in its declared authority order.

Caller Signature

/review-loop [source?] [scope?] [landing?]

source  : codex | code-review — one, or several reviewing in parallel
scope   : PR number | implicit current-branch PR / working tree
landing : head | stacked       (PR scope only)

Read designations from the request's words as well as its arguments. source selects the reviewer; the host is the environment driving the loop, not another user choice. Read only that host's reference before determining availability:

Other hosts may supply the same capabilities. Record the actual host, reviewer, and execution route; a new process provides a separate review context, not evidence of an independent model family. Sources remain runtime parameters rather than fixed frontmatter dependencies.

Source Interface

(diff pointer, design intent) → { findings[], verdict, exercised, direction? }
finding   : [critical | high | medium | low | suggestion] file:line — description
verdict   : approve | needs-attention
exercised : axes judged; axes not reached and what stopped each
direction : optional shared-cause hypothesis with its falsifier

Every source able to report reach owes exercised, including on approval. Ask explicitly whether the whole changed artifact's contract closes: declared values have producers, branches have supplied inputs, and obligations reach their consumers. Ask equally what the artifact carries that its remaining text already recovers: which obligation fails on a clause's deletion, and which two places state one thing and would have to be kept in step. Distinguish source analysis from executed checks. Request direction after findings on a non-approval; no single mechanism is a valid answer. A mechanism lacking a falsifier does not fill this slot.

A native report may be normalized by its adapter. An explicit successful empty findings result can mean approval; failed, skipped, missing, or unreadable review output cannot. Determine output capabilities from the available implementation. A source with no reach channel is declared once at entry and again at exit; a missing report from a capable source is a round-specific gap. The loop supplies neither reach nor a source direction by inference.

Rules

Phase 0 — Set the invocation and its ground

1. Use the source or sources designated in this invocation, with any effort level designated for each. Otherwise present the invokable sources with their actual coverage, cost, and reporting limits, without a default; ask which to use and wait for the answer. Silence stops. One available source relays its designation; zero stops with the missing capability. If an explicitly designated source is unavailable, surface why and ask whether to make it available, use an available alternative, or stop; retain the designation until that is settled.
2. Resolve explicit or current-branch PR scope; otherwise use the working tree. Capture the resolved diff base SHA and changed-file list. For working-tree scope, include staged, unstaged, and recursively enumerated untracked paths, and retain the captured HEAD as base even after loop commits. No changes means ask what to review and stop. For a PR, read PR scope before the first review for checkout and base preparation, and again before repairs for landing.
3. For PR repairs, relay an already-settled head or stacked landing, including a stated standing practice. State the reading and its basis. When unsettled, proceed with read-only review and finding disposition; ask before the first repair. Silence at that gate stops repairs. Hold the settled landing for this invocation while keeping the captured review base. An invocation ending without repairs needs no landing choice. A correction before repairs are committed replaces a misread designation; after commits, show what landed where and stop for recovery direction. A deliberately different settled landing belongs to a new invocation.
4. Harvest intent for the changed surface: applicable rules, project-guide rationale, adjacent design comments, and relevant context already at hand. Resolve the project's goal and authority order from its own declarations; report what the search did not find. Convey repository material as pointers. Convey loop-constituted design decisions as content with their constitutive basis, keeping the user's words where they establish direction. Only decisions holding independently of current code state enter this design-decision ledger; a revised decision supersedes its predecessor, with the retirement on the trace.
5. Preserve reviewer independence. Convey design intent, allowing the reviewer to challenge defects that intent causes. Keep fix-status claims, dispositions, do-not-reflag instructions, and shared-cause hypotheses out of reviewer context and out of surfaces harvested into it. A description of a decision carries no instruction about which verdict to return. Calibrate source severity by actual consequence against the mission: silent wrong results are critical, broken runtime behavior high, edge-condition failures medium, and consistency-only discrepancies low/suggestion; a convention-explained wording preference is not a defect.
6. Announce once that the user may end the loop at any time, receiving the trace and an optional offer to record what outlives it. Execution permissions and call supervision belong to the host; the loop provides no timeout guarantee itself.

Phase 1 — Obtain the round's reviews

Use the selected host route and source adapter with the captured pointer and current intent bundle. Several designated sources review that same pointer in parallel, each in its own context; the round's findings are their union, each keeping its source. Read the returned review and diagnostics in full. Record actual call settings and any reported failure cause as provenance, not coverage.

Use each source's first read-only review call to confirm its command and contract through startup, any skill expansion, and returned output. Reuse matching implementation evidence as the adapter specifies. Before accepting a verdict, establish that its source actually reviewed the captured surface and completed successfully. When execution contradicts the expected contract, diagnose that mismatch; unresolved source or scope mismatches contribute no verdict and follow the incomplete-call rule.

A call ending without a usable review contributes no verdict and satisfies neither convergence arm. Show what returned and ask whether to continue this round without that source's review, switch source, or stop. A failure that persists makes the source unavailable under Phase 0 rule 1, where its designation is settled. Continuing still owes that source a completed review before convergence. An extraction failure calls for inspecting raw output; it does not prove source failure. A capable source omitting reach leaves the missing report visible as residual.

Phase 2 — Verify and attribute

Call /inquire on each finding against the current artifact before acting. Drop a refuted finding with its cited basis and no defect provenance. For surviving findings, check the asserted issue against the captured base, following moves/renames:

An unchanged copy left inconsistent by this change is introduced drift, not an independent contributor. indeterminate takes the pre-existing side for scope decisions. Provenance informs scope; it neither licenses nor excludes repair. Fold genuine user judgments raised by verification into Phase 3's disposition gate.

Phase 3 — Read the cause and settle disposition

Once per round, examine the artifact against the project's stated goal, even when the source found nothing. Name the goal and consequence behind any additional finding, verify it through Phase 2, and include it in classification. Record an empty goal reading too; omit this pass only where no declared goal was found.

Read the verified set for a shared mechanism, competing explanations, unexplained findings, and a falsifier. No shared cause is a valid result. A source direction is one candidate, reconsidered after verification; agreement with the loop's reading is not independent corroboration. Materially different root and local repairs are a plan-level judgment even when each isolated fix looks mechanical.

A shared-cause reading may direct repair only while its falsifier holds off. It neither drops findings nor becomes constituted design intent. Recheck the falsifier when the surviving set changes or a repair lands; retire a defeated reading and reclassify unlanded work. Applied repairs stand for the next full review. Across rounds, compare new findings with prior fix predicates on the trace: a previously matching site missed by a sweep calls for completing the enumeration; an instance outside that predicate calls for reconsidering the abstraction. A later-created or newly matching site does not falsify an earlier sweep.

Where that reading, on a full re-review every designated source completed, names no shared cause, every root on the trace maps to its resolution, and no recurrence awaits diagnosis, the loop ends there as it stands: the round's findings go to the user unrepaired with their dispositions, and no repair is chosen or applied.

• Mechanical / Extension: a verified bug with a self-evident localized fix, or another deterministic edit whose plausible shapes do not materially diverge. Apply and report without a disposition gate.
• Judgment / Constitution: materially different repair trajectories, unresolved design trade-offs, or unentrusted scope/risk decisions. Present evidence first, then ask the live question in everyday language. Cluster findings by shared disposition; when repair shape is the live axis, ask about trajectories rather than asking whether to apply them all.

Relay a disposition already settled by the user's prior direction, the PR's purpose, a governing rule harvested under Phase 0 rule 4, or citable precedent, recording side effects. A proposed repair that a harvested rule excludes is not a live option: report it with that rule as its rejection basis before classifying, so any gate forms only over the admissible trajectories that remain. Reopen only a genuinely live competing judgment. Packaging an identical mechanical fix does not reopen disposition; repairing a pre-existing-side defect needs a citable scope license (purpose, mandated sweep, or settled precedent), otherwise ask about expansion.

For conflicting governing surfaces, cite an applicable declared authority order or settled direction to identify what governs. That settles direction, not repair shape or execution permission. Where direction remains unsettled or its authority is contested, show both surfaces, their disagreement, and their authority relation or its absence; ask an open-ended direction question and retain the user's words.

Where findings pull one clause or invariant in opposite directions and nothing governing decides between them, the clause holds a judgment the governing surfaces leave open: a Judgment gate showing both readings and any repair already landed in one direction, not a repair either reading settles.

Read every repair as an ablation before classifying it. A finding grounds a repair through the consequence it verified; a finding that shows only something unstated grounds none and is dropped on that basis. The repair is the least text that resolves that consequence and loses no other obligation — an existing carrier before a new one, a removal before an addition — and that reading is a recommendation, not the disposition.

Recurrence: identify the same defect by clause/invariant, not phrasing or line. An initial uninformed return is absorbed by settled policy. Instance-specific dismissals/deferrals never enter reviewer context, so their returns keep that disposition and remain residual. A return after a fix was visible or a constituted decision conveyed requires diagnosis before convergence. A still-self-evident incomplete repair stays Mechanical and is rewritten in the next apply pass with the recurrence history in its hand-off. A contested design decision reaches a judgment gate with the recurrence history; a third recurrence after the escalated re-apply discredits the Mechanical diagnosis and also gates. End recurrence through repair or constituted direction, not reviewer suppression.

Read trajectory from recurrence, causes, and base provenance, not finding-count trends. Separate introduced, fix-induced, and pre-existing-side work when deciding what this unit carries. A rising count changes neither the criterion nor source scope.

Phase 4 — Apply and check the bundle

For PR scope, follow PR scope before the first edit.

The driving session settles disposition and hands the apply pass to a writer. Where the host offers a full-context fork, one fork per apply pass is the default writer and carries steps 1, 4 and 5 below end to end; the host reference (for Claude Code, Claude Code § Writer fork) names the fork mechanism. Where the host offers only a fresh-context delegate, the driving session performs step 1 itself and hands the enumerated predicate and screened sites to that writer in a self-contained brief, which then carries steps 4 and 5. Where the host offers no delegation, or an action is parent-held for risk, the driving session writes inline. Under every route the scan holder is whoever performs step 1, and the writer is whoever performs steps 4 and 5.

A writer returns to the driving session whenever it stops — at a gate it cannot settle, or at the end of the pass — carrying what Trace and Exit requires of the pass so far, so the driving session records rather than re-derives it.

1. The scan holder scans planned change points, adjacent interactions, and repeated instances. Derive each fix's predicate from the violated invariant and verified cause. Trace relevant state through production, transfer, invalidation, and consumption, including transitions and interleavings; enumerate the predicate's sites. State the observation that would falsify the repair and select bounded checks from it. Return a live judgment about consistency or evidence support to Phase 3 before its dependent repair. Semantically verify and risk-screen every site before writing it; a new unscreened site returns for screening. A nameless predicate licenses no write. Sweep matching sites in this apply pass within the settled scope, reporting expansion.
2. Risk is separate from Mechanical/Judgment classification. Route substrate actions to host permissions; an unsettled epistemic risk goes to the user for apply, defer, or drop. Rejection blocks an edit not yet written.
3. Repeated fix-induced follow-ups across consecutive rounds move judgment, not writing: the next apply pass returns its enumerated predicate and sites to Phase 3 before writing, and Phase 3 reads whether those repairs have become a chain in which each answers a problem the previous addition created rather than the original finding's subject. Such a chain suggests the first addition computed what the contract leaves to judgment; removing that surrogate with the machinery grown around it, against adding the next case, is the plan-level root-or-local judgment. Return to autonomous apply after a review without such follow-ups.
4. Read every written and swept site against its disposition and exercise the repaired invariant through the transitions and orderings identified by the scan. Repair a known discrepancy within the settled disposition and re-check the affected bundle before hand-forward; a live judgment returns to Phase 3. An explicitly accepted or deferred limit remains residual. Record unavailable checks with their reason and consequence for confidence. These checks establish bounded conformance; full re-review independently judges the artifact. Call /contextualize once on the whole applied bundle against the design-decision ledger and touched-surface conventions.
5. An adaptation that /contextualize actually writes re-enters scan, site screening, sweep, and write verification once. Reconcile an already-written adaptation with its settled disposition before hand-forward. A self-evident repair stays within that disposition; a competing repair or a live judgment about evidence support returns to Phase 3 with the current artifact and consequences. A defer or drop verdict states whether the landed effect remains and its authorized basis; the verdict alone does not authorize retaining it. After reconciliation and checks, including explicit unavailable-check limits, the writer commits to the settled landing for PR scope and pushes where that landing has a remote, then returns.
6. After a judgment returned to Phase 3 is settled, resume the pending step in the same apply pass with that answer.

Phase 5 — Re-review and stop on evidence

When the processed round has not earned convergence below, refresh changed files and design intent and obtain a full re-review from each designated source, including after dispositions that landed no edit. Any edit invalidates the preceding verdict and always owes this review of the original surface plus all repairs. For PR scope, use the re-review pointer supplied by PR scope. For working-tree scope, compare against the captured base and include current untracked files even if the loop has since committed. Keep review base fixed. Where the ledger convention puts a repair's derivation in its commit message, that message is a fix-status claim under Phase 0 rule 5: point the re-review at the ledger through the pre-repair range only, and state that the repair commits are judged from their content in the diff as part of the whole range.

These reviews are the next round's: Phase 1's rules for parallel sources and failed calls apply to them, and their findings and direction go straight to Phase 2. Process findings even alongside approval, and perform the goal reading. Converge only on the current reviewed artifact when every surfaced finding is dispositioned, no recurrence awaits diagnosis, no edit has landed since the review, and either:

• for every designated source, the source returned approve or a full re-review returned zero new non-refuted findings; or
• the loop ended at Phase 3's root-resolved end.

A new finding remains new in its discovery review even when deferred or handed over; its later return is not new and preserves the disposition. Unreached axes, missing reach reports, open deferrals, and explicitly retained adaptation effects remain residual; they do not themselves force another round and are never reported as clearance.

At any exit before these conditions hold, report non-convergence with the latest reviewed artifact, later edits, unfinished repairs, residuals, and retained judgments. The user may exit at any point; an external interruption supplies no convergence evidence.

Trace and Exit

Present each round's trace and continue without a gate:

Round k — host / source / route — reviewed base → head or working-tree state — verdict
Exercised: source-reported reach and gaps (omit for a standing no-channel source)
Call: observed settings or diagnostics, when present
Goal: loop's goal reading and its findings, including none (omit if no declared goal)
Roots: Phase 3 shared-cause reading — each shared cause with the findings it explains, or none
Relay: autonomously dispositioned findings → applied | dropped: basis | carried: reason
Gated: findings requiring user judgment → applied | dropped: basis | carried: reason
Apply: writer route (fork | brief | inline) → commits or new head, or tree state (omit if no pass ran)
Landing: repair destination (PR only)

A round with several sources carries its Round, Exercised and Call lines once per source.

Each verified finding carries base provenance; an applied fix also carries its predicate and sweep side effects. Carry the loop's check artifact, evidence, unexercised limits, and unavailable-check reasons with that repair's Relay/Gated entry; keep this loop-side evidence distinct from the source-reported Exercised line. Assign exactly one Relay/Gated home by whether the user was asked, including nested /contextualize questions and epistemic risk gates. Host permission decisions are execution annotations. Record the fit pass as its own entry, with adaptation, any retroactive rejecting verdict, and the resulting artifact state and disposition. Preserve write discrepancies and their reconciliation; carried reasons are records, while subsequent reviews detect findings fresh.

At every exit, present the accumulated dispositions and residual, including standing source limits. Read exit handover before offering durable recording.