Goal
Converge an open-ended "please review and fix" task into a verifiable loop:
- Infer the initial change intent X from context.
- Choose a stable and repeatable native
codex reviewcommand for the review target. - For each review finding, determine whether it falls within the scope of X's changes.
- Fix only issues related to X and clearly determined.
- Run necessary verification.
- Continue reviewing using the same review target until there are no findings.
This skill handles loop control and decision boundaries;codex review only provides independent review results, and the current agent is responsible for the final judgment and code modifications.
When an auditable findings ledger is needed, use codex-review-fix-loop-ledger, which layers a ledger on top of this loop.
Input requirements
Confirm three inputs before starting:
项目路径: the root directory of the Git repository to review.初始改动意向 X: what this round of changes was originally intended to accomplish. The user can provide it explicitly; if not provided, infer it from context.审查目标 R: uncommitted changes, changes relative to a baseline branch, a specified commit, or custom review instructions.
Priority for inferring X:
- The implementation / fix / refactoring goal most recently proposed by the user in the current conversation.
- The files and descriptions actually modified by the current agent in this or the previous round.
- The change theme presented by the
git diff/git showcorresponding to R. - The problem description in the most recent relevant review output or user feedback.
After inferring, write X in one sentence and continue. Ask the user first only in the following cases:
- There are multiple unrelated candidate Xs at the same time, and choosing the wrong one would cause fixes to be made in the wrong scope.
- The user requests
--base, but the baseline branch cannot be determined from context or Git status. - The diff is very large but the context has no clear goal.
- The fix may change the public API, data migration, permission model, persistence format, or commit history.
Native CLI commands
Use the Codex CLI directly, do not call a Python wrapper, and do not maintain your own codex review output parsing script.
Prefer setting the tool call's workdir to the project path. When the path needs to be specified explicitly in the command, use Codex's global -C, and place it before the review subcommand:
codex -C <project-path> review "Review the current code changes (staged, unstaged, and untracked files) and provide prioritized findings. Do not run codex, codex review, or invoke any other AI reviewer command."
When reviewing current staged, unstaged, and untracked changes, the complete prompt above must be used. In the Codex source code, --uncommitted generates the first sentence in it; this skill uses a custom prompt to append the second sentence as recursion protection. Do not abbreviate the command back to --uncommitted。
Commands and applicable scenarios
| Command | Review content | Applicable scenarios | Loop precautions |
|---|---|---|---|
codex review "Review the current code changes ... Do not run codex ..." |
staged, unstaged, untracked changes | Pre-commit check; current workspace review/fix; default scenario of this skill | Reuse the complete prompt above as-is each round to prevent the reviewer from recursively calling an AI reviewer |
codex review --base <branch> |
Changes of the current branch relative to the merge-base of the specified baseline branch | PR/MR style review; acceptance of the entire feature branch | Keep the same base for each round; after fixes, the branch diff updates accordingly |
codex review --commit <sha> |
The changes introduced by a specified commit | One-time review of a committed change set; pinpoint the problems in a certain commit | A commit is an immutable target; when history is not rewritten, you cannot claim the original commit is clean after fixing the workspace |
codex review "<instructions>" |
Completely defined by instructions | Specialized scope or review criteria that built-in targets cannot express | The prompt must clearly state the object and include recursion protection; reuse it verbatim each round |
codex review - |
Read custom instructions from stdin | The instructions are very long, or are provided by an upstream command | Semantically identical to a positional prompt, and must likewise include recursion protection |
When reviewing a specified commit, you can provide a title used only for that commit:
codex review --commit <sha> --title "<commit-title>"
The four targets of the native CLI --uncommitted、--base、--commit, and custom PROMPT are mutually exclusive in pairs.--title The semantics of are the commit title, used only in the --commit scenario, and even if some CLI version does not reject other combinations, do not rely on that behavior. The complete prompt for the current changes is itself the target; do not write:
codex review --uncommitted "只检查与 X 相关的问题"
When the target is uncommitted changes but only problems within the scope of X may be fixed, use the complete current changes prompt, treat X as the filtering boundary of the Evaluate stage, and do not modify the review prompt again. Other custom prompts must also append the following verbatim text (do not repeat if already included):
Do not run codex, codex review, or invoke any other AI reviewer command.
The interactive TUI's /review also provides four presets: base, uncommitted, commit, and custom instructions, suitable for a user to manually initiate a review; this skill's automatic loop uses the non-interactive codex review, do not start the TUI in order to run the loop.
codex review There is no public overall review time limit parameter. Set the outer execution tool's timeout to at least 900000 ms (15 minutes); this is the caller timeout, not a CLI parameter. Native output may include tool logs, the full diff, and repeated final conclusions; read the last complete reviewer conclusion, and do not prematurely judge the result just because the earlier output is very long.
Select the review target
Select R in the following order:
- When the user explicitly specifies a target, use that target.
- When the user says "current changes", "uncommitted changes", "before committing", explicitly specifies
--uncommitted, or only asks to review the just-completed modifications until clean, use the complete current changes prompt. - When the user says "relative to main/develop", "PR/MR", "entire branch", use
--base <branch>。 - When the user gives a SHA or asks to review a submitted change set, use
--commit <sha>。 - Use another custom only when the built-in targets cannot express the review object
PROMPT; the prompt must contain a stable, reproducible target description and recursion protection.
Do not abandon an already clear just to use custom criteria --base or --commit target. Current changes are the exception: they always use a prompt with recursion protection. For example, "review uncommitted changes, fix only issues related to the login callback" uses that complete prompt, then uses X to limit the fix scope.
--commit The fix boundary of
--commit <sha> Each time, the same immutable commit is reviewed. After problems are found:
- Before entering automatic repair, the working tree is required to be clean, and the current HEAD must equal the target commit or contain that commit. Otherwise, only deliver the commit findings and pause to confirm which branch or separate worktree to repair in; do not automatically stash, switch branches, or overwrite existing changes.
- When authorization to rewrite history has not been obtained, you can write the fix into the working tree and review the fix patch with the complete current changes prompt; if the base is known, you can also use
--baseto review the overall branch containing the original commit and the fix. - Do not automatically
commit --amend, rebase, or move branches without authorization. - The final report must distinguish between "findings of the original commit", "the fix patch is clean", and "whether the original commit was rewritten".
Loop process
1. Establish boundaries
First perform a read-only precheck according to R:
- Current changes prompt: check
git status、git diff、git diff --staged. If there are no uncommitted changes, stop; do not run an empty review. --base <branch>: Confirm that the branch can be resolved, and confirm that the current branch has pending changes to review relative to the merge-base.--commit <sha>: Confirm that the SHA can be resolved, and usegit show --stat --oneline <sha>to verify the target; also record whether the working tree is clean and whether HEAD equals or contains the target commit. Read-only review does not require a clean working tree, but automatic repair must satisfy the aforementioned commit repair boundary.- Custom
PROMPT: Confirm that the prompt clearly states the review object and completion criteria, and includes recursion protection.
Before the first review, briefly explain the boundaries to the user:
项目:<project-path>
改动意向 X:<one sentence>
审查目标 R:<current changes prompt / base branch / commit / custom>
命令:<exact codex review command>
停止条件:review 没有 findings;或修复需要改变 X、扩大范围、改写历史;或多轮未收敛(最多 10 轮)。
If the target contains multiple obviously unrelated change topics, and it cannot be determined from context which topic X corresponds to, pause first and suggest that the user choose or split them; do not mix repairs of unrelated topics in one loop.
2. Review
Run the selected native command in the project path. Keep R unchanged in each round; the only exception is when --commit switches to the fix patch target according to the aforementioned immutable target rule, and record the reason for the switch.
Keep the key information of each review round:
- Round number
- Actual command and target
- Finding title and priority
- Files involved
- Whether related to X
- Handling decision
When the native CLI output is long, use the last complete reviewer conclusion as authoritative. If the outer tool still shows the process running, continue polling instead of starting a second review; if the output is truncated before the conclusion, obtain the result again with a larger output budget. Failure to obtain a complete conclusion cannot be regarded as clean.
3. Evaluate
Evaluate findings one by one:
相关: The finding points to a correctness, security, performance, compatibility, or maintainability issue on a path introduced or modified by X.不相关: The finding points to a problem that already existed before X, or belongs to another change topic.不确定: Judgment requires business intent, compatibility commitments, release strategy, or user preference.
Handling rules:
- Fix
相关issues with a clear fix plan. - Do not fix
不相关issues, but list them in the final report. 不确定Do not guess at- issues; gather all items in this round that require user decisions and ask them all at once, then continue after receiving answers.
4. Fix
When fixing, stay surgical:
- Only change files directly related to the finding and X.
- Do not refactor unrelated code.
- Do not fix historical issues along the way.
- Do not expand the functional scope of X.
- Do not, due to
--commitreview, automatically rewrite the commit history.
If a fix would change X's behavior, public API, data migration, permission model, persistence format, or commit history, pause first and explain the tradeoffs.
5. Verify
After each round of fixes, run verification matching the risk of the changes:
- Prefer the project's existing tests, lint, and typecheck.
- When there is no explicit verification command, at minimum run the smallest available check targeting the modified module.
- If verification cannot be run, record the reason and continue to the next review round; the final report must state the unverified items.
6. Repeat
Run again the native command corresponding to the current R. Loop until:
- the review output explicitly indicates there are no findings; or
- two consecutive rounds have only false positives / unrelated issues left; or
- an issue requiring user decision appears, and the relevant items for this round have been summarized; or
- the fix requires expanding X, changing the review target, or rewriting history, and must be confirmed by the user; or
- 10 rounds have already been run but new findings keep appearing: pause and report the current state, leaving it to the user to decide whether to continue.
Do not stop just because "several places have already been fixed." The stop condition must be tied to the review results.
Codex output judgment
Different versions of codex review may use different wording to indicate that no issues were found. All of the following can serve as clean signals:
No findingsno findingsdid not find any discrete functional regressionI did not find any ... regression- The final reviewer summary explicitly indicates there are no actionable issues
If the last complete conclusion contains Review comment:、Full review comments: or explicitly listed findings, treat it as having findings. The native CLI may print the final conclusion twice; duplicate content counts as only one review result.
Review failed (not clean)
The following situations indicate that the review itself did not run successfully:
codex reviewNon-zero exit.- Output
Reviewer failed to output a response.。 - The process was terminated by an outer timeout.
- The output was truncated, or there was no complete reviewer conclusion at the end.
When encountering a failure, retry one round first; if it still fails, pause and report. Do not mistake "no findings captured" for "no findings."
Final report
At the end, deliver a brief report:
完成状态:clean / paused / blocked
项目:<project-path>
改动意向 X:<one sentence>
审查目标 R:<target>
Review 轮次:<n>
修复摘要:
- ...
验证:
- <command>: passed/failed/not run
未修复 findings:
- <finding>: <不相关/误判/等待用户决策>,原因...
If --commit was used and the fixes were left in the working tree, clearly report that the original commit is unchanged, and whether the final clean conclusion corresponds to the fix patch or the entire branch. If the final state is not clean , explain what decision the user needs to make next.
Example triggers
对 /path/to/repo 的未提交改动做 codex review,自动判断改动意向并循环修到 clean以 main 为 base 审查当前分支,只修这次支付重试相关 findings,直到没有问题审查 commit abc123;发现问题就修,但不要 amend,修复补丁继续 review 到 clean用自定义 review 指令检查这个并发修复,反复修到没有可执行 findings