auto-review-loop

name	auto-review-loop
description	Repeatedly run the local Codex review command, classify findings, apply valid fixes, verify them, and stop when there are no actionable findings or human judgment is required.

Auto Review Loop

Use this skill when the user wants Codex to keep running the local codex review command, decide whether the review findings are valid, fix valid findings, and repeat until the loop is complete or blocked.

Quick start

Use the bundled runner script for review rounds. Do not hand-roll the codex review invocation unless the script is missing or cannot run in the current environment.

SKILL_ROOT="<absolute-path-to-this-skill>"
SCRIPT="$SKILL_ROOT/scripts/run_codex_review.sh"
"$SCRIPT" [--base <ref>] [--commit <sha>] [--remote <name>] [--prompt <text>] [--title <title>] [--output <path>]

Default loop limit: 5 rounds unless the user explicitly requests another limit.

In the current codex review CLI, --base or --commit cannot be combined with a positional review prompt. This runner always calls codex review with one of those target options, so --prompt <text> is report context only; do not rely on it to change the review instructions passed to codex review.

codex review supports these target modes:

• --base <ref>: review changes against a comparison base.
• --commit <sha>: review the changes introduced by one commit.

For auto-fix loops, prefer --base <ref> because fixes applied in the worktree remain in the reviewed diff on the next round. If the user specifies a comparison target in their prompt, pass it as --base <ref> and keep using that same base for every round. This includes locally available commit SHAs such as "the SHA before the latest commit", branch names, tags, and Git revision expressions such as HEAD~1 or HEAD^.

Use --commit <sha> only when the user explicitly asks to review one fixed commit. Do not keep auto-fixing and re-running against the same immutable commit unless the user also asked to amend or recreate that commit; otherwise the review can repeat the same findings forever. For "review the latest commit and fix issues", use --base HEAD~1, not --commit HEAD.

Examples:

"$SCRIPT" --base abc1234
"$SCRIPT" --base HEAD~1
"$SCRIPT" --commit HEAD

When the user does not specify a comparison target or commit target, omit both --base and --commit and let the script resolve the default remote main or master base.

Workflow

1. Inspect repository state with git status --short.
2. Determine the review target:
   • If the user provided a specific comparison target in the prompt, use it with --base <ref>.
   • If the user asked to review one specific immutable commit, use --commit <sha> only for that fixed commit review.
   • Otherwise use the default remote base resolution.
3. Run scripts/run_codex_review.sh to capture one codex review round into .codex/auto-review-loop/.
   • The default remote is origin.
   • When both --base and --commit are omitted, the script fetches and selects origin/main or origin/master, preferring the remote default branch when it is one of those names and otherwise preferring main over master.
4. Classify every new finding:
   • valid: demonstrable bug, failing test, type error, security issue, broken contract, missing required behavior, or clear maintainability issue.
   • invalid: already fixed, contradicted by code/tests, outside the selected diff, subjective preference without project backing, or based on a mistaken reading of the code.
   • needs-human: ambiguous product behavior, architecture tradeoff, destructive migration, public API decision, unclear reviewer intent, or change requiring credentials/secrets.
5. If any needs-human item exists, stop and report the decision points.
6. For valid items, edit the code using existing project conventions. Keep fixes scoped to the reviewed change.
7. Run the narrowest meaningful verification first, then broader tests when the touched surface is shared.
8. Re-run against the same base or commit target and repeat until there are no new valid findings or the max round limit is reached.

Loop safety

Before the first round, create a simple loop ledger in .codex/auto-review-loop/ or track the same facts in your working notes:

• round: current round number and configured maximum.
• target: exact --base or --commit value; never let it drift between rounds unless the user explicitly changes the target.
• diff fingerprint: git diff --stat plus a stable summary such as git diff --name-status <target>...HEAD when available.
• finding fingerprints: one concise key per finding, based on file path, line or symbol, and reviewer claim.
• attempt count: number of fix attempts per finding.

Stop the loop immediately and report the stop reason when any of these conditions occur:

• The configured maximum round count is reached.
• A needs-human finding appears.
• The same valid finding is still present after two fix attempts.
• A round produces the same set of valid finding fingerprints as the previous round and the diff fingerprint did not change.
• A verification command needed to validate the fix cannot run or fails for a reason unrelated to the attempted fix.
• The selected target is an immutable --commit target and fixes were applied outside that commit. In that case, switch to a --base <commit-parent> loop only if the user requested continuing against the worktree; otherwise stop and explain the mismatch.

If a review returns only invalid findings or no findings, stop successfully. Do not run another round just to confirm the same empty or rejected result.

Rules

• Never loop without a maximum round count.
• Record enough per-round state to prove the loop made progress.
• Do not auto-fix comments that require product, security, legal, or architectural judgment.
• Do not dismiss review findings silently. Report invalid findings with a short reason.
• If the same valid finding remains after two attempted fixes, stop and ask for human input.
• Preserve unrelated worktree changes and keep fixes scoped to the selected review target.
• Prefer local commands from the repo (package.json, Makefile, CI config, language tooling) over invented validation commands.
• Do not commit or push unless the user explicitly requested that as part of the loop.
• When finished, summarize rounds run, review target, stop reason, findings fixed, findings rejected, verification commands, and any remaining risks.

Output shape

Use this structure in the final response:

Conclusion: <completed | needs human | stopped at round limit>
Rounds: <n>
Stop reason: <why the loop stopped>
Fixed: <short list or "none">
Rejected: <short list with reasons or "none">
Verification: <commands and results>
Review target: <selected base or commit>