codex

review-only

• Per-finding atomic commits — every fix gets its own conventional commit, easy to revert
• Stop conditions are NON-NEGOTIABLE (see Stop Conditions below) — when one fires, the loop STOPS and the remaining work surfaces to the user, period
• User can interrupt anytime with ctrl-c; main session catches and reports partial state

• Codex runs in a fresh process every iteration — no shared conversation context with main session
• Codex output (verbose finding text) goes to a temp file, NOT into chat — only a structured JSON summary enters main session memory, per-iteration
• Main session implementing fixes MUST execute the codex finding's

  Mitigation:

  field literally, mechanically — NO additional reasoning about whether the fix is right, NO substitution of "a better approach", NO scope expansion
• If you cannot fix the finding from the

  Mitigation:

  field alone (because it's ambiguous, requires design judgment, or touches code outside the scope of this finding) → SKIP that finding for this iter and surface it to user at end

• This skill does not produce wontfix decisions. Findings are either fixed (auto) or surfaced (escalation).
• Do NOT decide "this finding doesn't matter" → all findings are fixed unless they hit the "cannot fix from Mitigation alone" gate above
• Do NOT fill out Wontfix Template fields from main-session memory (see

  pr-babysit

  § 4.6)

• Tests run after each iter's fixes —

  pnpm test

  (or detected per-repo command). Failure → STOP and escalate
• This is the natural safety net for "fixes that break things"

• Codex (cross-model) generates findings → bias-isolated at finding-generation layer
• Main session writes fix → not bias-isolated, but follows codex Mitigation literally → bias attack surface is "mechanical execution accuracy", not "verdict judgment"
• If you catch yourself reasoning "I think codex is wrong about this" → that's verdict reasoning, NOT allowed in this skill. Surface to user at end. </HARD-GATE>

• loop

  (default) — codex review → per-finding fix + commit → tests → re-review → loop until stop

• review-only

  — single codex pass, present findings, stop. No fix, no commit, no test run. Use when you want a manual review without auto-modification.

• User says "self review" or "review my branch" → loop (default)
• User says "just show me findings" or "self review without fixing" → review-only

• Just wrote code on a feature branch, working tree is clean and committed, want auto cross-model review + fix before push
• Iterating on a feature, want to converge on a clean state quickly
• Pre-PR sanity pass — catch the obvious stuff codex spots before sending to humans

• Live PR review with sticky comment + inline threads →

  /cadence:pr-review

  (default mode)
• PR babysit work after PR is open →

  /cadence:pr-babysit

  (handles thread reply, dedup, CI gates)
• Working tree has uncommitted changes — STOP and ask user to commit or stash first. Loop assumes clean working tree at start so per-finding commits are atomic
• You want manual verdict control → use

  mode=review-only

  and decide yourself
• First-time use on a new branch → consider

  mode=review-only

  first to see what codex produces before letting it auto-fix

• ITER

  — current iteration number (starts at 1)

• MAX_ITERS = 3

  — hard cap. Empirically codex's high-value findings (real reachable bugs, the kind a same-model reviewer misses) land in iters 1–3; iters 4–5 trend to hygiene-tier nits + the occasional false positive that the controller then has to spend judgment rejecting. The real stop is SC0 (severity floor) below —

  MAX_ITERS

  is the blunt backstop.

• FINDING_HISTORY

  — list of

  file:line:slug

  fingerprints from prior iterations (for repetition detection)

"$OUTPUT_FILE" 2>/tmp/self-review-err

$JSON_FILE

FINDINGS_COUNT=$(jq '.findings | length' "$JSON_FILE")

FINDINGS_COUNT == 0

severity

Blocker|Factual

justification

Reachable|Asymmetric

Suggestion

Question

Factual

Precedent

Historical

REAL_BUGS=$(jq -r '[.findings[]
  | select((.severity == "Blocker" or .severity == "Factual")
           and (.justification == "Reachable" or .justification == "Asymmetric"))]
  | length' "$JSON_FILE")

REAL_BUGS == 0

FINDINGS_COUNT > 0

MAX_ITERS

Why SC0 is checked before SC2 but after SC1: zero findings is unambiguous success; a hygiene-only iteration is converged-enough success; the

MAX_ITERS

cap is the unhappy backstop. Naming it SC0 keeps it visually adjacent to SC1 (both success-class) without renumbering SC2–SC6.

ITER > MAX_ITERS

undefined

jq -c '.findings[]' "$JSON_FILE" | while read -r FINDING; do
  ID=$(echo "$FINDING" | jq -r '.id')
  PERSONA=$(echo "$FINDING" | jq -r '.persona')
  CATEGORY=$(echo "$FINDING" | jq -r '.category')
  SLUG=$(echo "$FINDING" | jq -r '.slug')
  FILE=$(echo "$FINDING" | jq -r '.file')
  LINE=$(echo "$FINDING" | jq -r '.line')
  FAILURE_MODE=$(echo "$FINDING" | jq -r '.failure_mode')
  MITIGATION=$(echo "$FINDING" | jq -r '.mitigation')

  # Main session reads the full finding from OUTPUT_FILE for context
  # then implements MITIGATION literally
  apply_minimal_fix_from_mitigation "$FILE" "$LINE" "$MITIGATION"

  # Verify file changed
  if git diff --quiet "$FILE"; then
    SKIPPED_FINDINGS+=("$ID: no diff produced — mitigation may need design judgment")
    continue
  fi

  # Atomic commit
  git add "$FILE"
  git commit -m "fix($PERSONA): $SLUG — self-review iter $ITER #$ID

Failure mode: $FAILURE_MODE
Mitigation: $MITIGATION

Source: codex review following pr-review methodology
Category: $CATEGORY
"
done

• Read the codex

  Mitigation:

  field for this finding. Implement it MINIMALLY.
• Do NOT expand scope (don't refactor adjacent code, don't add tests not requested, don't add comments)
• Do NOT add Claude reasoning ("I also noticed X, fixed that too" — NO)
• If

  Mitigation:

  is ambiguous or requires design judgment to implement → SKIP, add to

  SKIPPED_FINDINGS

  , surface to user at end
• One finding = one commit. If a single mitigation actually touches 3 files, one commit covering all 3 is fine. But two different findings = two commits.

Failure mode

await

• Before committing, grep the codebase for the same pattern (the failure shape, not the literal line). Fix all matching sites under that finding's commit.
• This is explicitly NOT the "expand scope" violation above. Scope expansion is fixing unrelated things. Fixing the same flagged pattern at sibling sites is finishing the finding — leaving siblings for the next codex pass wastes an iteration AND ships the identical bug at an unflagged site until then.
• How to tell them apart: would codex, on the next pass, file a finding with the same

  Failure mode

  wording pointing at a different

  file:line

  ? If yes, that site belongs in THIS commit.
• If grep surfaces sibling sites whose fix needs design judgment (not a mechanical copy of the same mitigation) → fix the mechanical ones, SKIP the judgment ones, surface them. Don't force a uniform fix across sites that aren't actually uniform.

• ${CLAUDE_PLUGIN_ROOT}/skills/pr-review/security-reviewer-prompt.md
• ${CLAUDE_PLUGIN_ROOT}/skills/pr-review/staff-engineer-prompt.md
• ${CLAUDE_PLUGIN_ROOT}/skills/pr-review/sdet-prompt.md
• ${CLAUDE_PLUGIN_ROOT}/skills/pr-review/spec-auditor-prompt.md

• ${CLAUDE_PLUGIN_ROOT}/skills/pr-review/SKILL.md § Finding Inclusion Threshold

${CLAUDE_PLUGIN_ROOT}

read-only

• "HARD-GATE" / "You have NO knowledge of conversation history" — you are isolated by being a different process and model family
• "Incremental Mode Addendum" / "prior_fix_range" / drop signal (B) — those depend on babysit-side state tracking. Skip the (B) check entirely. Signals (A), (C), (D) still apply.
• "dispatched from a dev session" / "subagent" framing — you are codex executing this prompt directly

• Per-persona category tables: Security (S1-S5), Staff Engineer (E1-E9), SDET (T1-T4), Spec Auditor (C1-C4)
• Finding Inclusion Threshold: Justification class (Reachable / Precedent / Asymmetric / Historical)
• Drop signals (A), (C), (D)
• Hygiene batch rule (cluster hygiene drops into one Q-class finding per file)
• Race-class Finding Metadata: Mitigation MUST end with

  [window=<ms|s|min|hr>, damage=<data-loss|deadlock|inconsistency|latency|marginal>, recovery=<has|no>]

• Per-prompt Output Schema (Severity / Confidence / Blast / Justification / Evidence / Failure mode / Mitigation)

• findings: []

  (empty array) is VALID output meaning no findings. Still emit the block with

  {"findings": []}

  between the sentinels — do NOT omit the JSON block.

• line

  MUST be the source file line number (the line in the file as written on disk after your reading), NOT the diff hunk line number. If the diff shifted lines, use the post-shift source file line.

• line_source

  MUST be

  "source"

  literal — this confirms you used source file lines, not diff lines. Any other value → caller treats as malformed and escalates.
• All listed fields are REQUIRED. Do not emit findings with missing fields.

• Do NOT modify any files
• Race-class findings without meta tag → drop the finding
• You are codex, not Claude — your prose can be your own
• Stay focused on the diff

undefined

1. Run codex (same prompt as loop mode Step 1)
2. Present output verbatim from

   $OUTPUT_FILE

   (full per-persona findings text)
3. Stop. Do NOT commit. Do NOT touch files.

• Cross-model isolation rationale: codex (OpenAI GPT) reviews Claude-generated code → avoids same-model self-preference bias (Wataoka et al., perplexity-driven). Each codex invocation is a fresh process — no conversation context inheritance.
• Context-mix prevention design: codex output goes to

  /tmp/self-review-iter-$ITER.md

  (file, not chat). Main session only parses the JSON summary block into conversation memory. Full finding text accessed by main session via file read when implementing each fix — not auto-injected. This keeps main session's growing conversation lean across iterations.
• Methodology single-sourced: codex reads

  ${CLAUDE_PLUGIN_ROOT}/skills/pr-review/*-prompt.md

  directly (dispatcher expands the env var to an absolute path before handing the prompt to codex). When pr-review prompts update, this skill picks up the new methodology automatically. No keep-in-sync burden between pr-review and self-review.
• Adaptation layer keep-in-sync: the "IGNORE these sections" list in the codex prompt mirrors Claude-specific sections in pr-review prompts. If pr-review adds new Claude-only machinery, update the IGNORE list. Annotated as a maintenance concern, not auto-detected.
• Per-finding atomic commits:

  git revert <sha>

  undoes one finding's fix cleanly. History preserves the audit trail of what codex flagged + how it was fixed.
• Test gate as natural safety net: the cheapest signal that "auto-fix broke things" is a failing test. Catches regressions without needing complex semantic verification.
• Loop count cap (3) reasoning: empirically (5-iter run on a real feature branch) codex's high-value findings — real reachable bugs, the same-model-blind-spot class — all landed in iters 1–3. Iters 4–5 produced hygiene-tier nits, the tail of an already-identified pattern, and one outright false positive the controller had to reject. The cap was 5; it is now 3. The principled stop is SC0 (severity floor) —

  MAX_ITERS

  is the blunt backstop, and a run that still yields real-bug findings at iter 3 is itself signalling the change is too big and should be split.
• SC0 vs MAX_ITERS — why both: SC0 (severity floor) is the intended stop — it fires when an iteration produces no real reachable bug, i.e. further rounds would only surface nits.

  MAX_ITERS=3

  is the backstop for the pathological case where codex keeps finding real bugs that far out. A healthy run stops on SC0 at iter 2–3; only an unhealthy (oversized-diff) run reaches the cap.
• Pattern generalization beats round count: the loop's structural weakness is amplifying one conceptual bug into N findings across N iterations (codex finds one site per pass; controller fixes one site per pass). The Step 3 "Pattern generalization" rule counters this — on first sighting of a pattern-class finding, grep + fix all sibling sites in the same iteration. Done well, the loop self-converges inside the cap without relying on it.
• Author bias still applies to FIX step, not VERDICT step: codex finding generation is cross-model isolated. Main session writing the fix is NOT — but the HARD-GATE constrains main session to mechanical execution of

  Mitigation:

  field, removing the verdict-reasoning attack surface. If you notice main session "reasoning whether codex is right" → that's a HARD-GATE violation, surface the finding instead of arguing.
• Worktree assumption: skill expects to run on a feature branch (user already in worktree or non-main branch). Doesn't self-create worktrees. If user is on

  main

  , warn but don't block — they may know what they're doing.
• No state persistence across invocations: each invocation starts fresh.

  FINDING_HISTORY

  is per-invocation. If you re-invoke after manual edits, the loop has no memory of previous runs — by design (keeps the skill stateless, no

  .claude/state/

  files to maintain).