Codex Code Review skill for Codex

A Codex review is useful when it reports few findings, each one concrete (file, line, failing scenario), ranked by consequence, and verified before anyone acts on it. Volume is not value: one confirmed P1 beats twenty style remarks.

Pick the surface

Want to review	Use	Notes
Your working tree before committing	/review in the TUI, optionally /review Focus on X	Uses the session model unless review_model is set
Same, scripted or in a hook	codex review --uncommitted	Staged, unstaged and untracked changes
A branch against its base	codex review --base main
One commit	codex review --commit <sha> --title "..."	--title only with --commit
Custom instructions instead of a preset target	codex review "<instructions>" or - for stdin	Target flags and a custom prompt are mutually exclusive
GitHub PRs	@codex review comment, or Automatic review in Codex settings	Posts a normal GitHub review; flags P0/P1 only
GitHub PR, one-off focus	@codex review for issues in the database migration
Security depth on PRs	@codex security review (when Security Review is enabled)	Separate, deeper pass
PR review inside your own workflow	openai/codex-action with a review prompt file	See codex-github-action

Severity rubric

Level	Meaning	Examples	Action
P0	Will break production, lose or corrupt data, or open a security hole	SQL injection, migration that drops a column still read, auth bypass	Block merge
P1	Wrong behavior in a realistic case, or a regression	Off-by-one in pagination, race on concurrent update, missing null handling on a nullable API field	Fix before merge
P2	Risk or maintainability issue with plausible future cost	Missing test for new branch, swallowed error, N+1 on small table	Fix or ticket
P3	Nit	Naming, comment wording	Optional; usually omit

Ask for P0-P2 locally and P0-P1 on PRs. Formatting and lint belong to CI, not review.

Workflow

- [ ] 1. Scope the diff and gather intent
- [ ] 2. Make sure repo rules are in AGENTS.md
- [ ] 3. Run the review with a focused prompt
- [ ] 4. Triage: verify each finding
- [ ] 5. Fix confirmed findings; re-review the fix

1. Scope and intent

git status --short
git diff --stat main...HEAD

If the diff is over roughly 1,000 changed lines, review per commit or per directory. Give the reviewer the intent: ticket text, acceptance criteria, what the change is supposed to NOT change. Reviews without intent can only find generic bugs.

2. Repository review rules

Codex review reads AGENTS.md, including a ## Code Review Rules section in the file nearest the changed code (root for repo-wide, nested for a service):

## Code Review Rules

### Money
- Flag any arithmetic on prices using floats. Safe path: integer cents via `Money` helpers.

### Migrations
- Flag migrations that drop or rename columns still referenced in src/. Safe path:
  expand-and-contract across two releases.

### Public API
- Flag changes to response shapes in api/v1 without a version bump.

Start with two or three rules that encode what human reviewers keep repeating. State the behavior to flag, why it matters, and the safe path. Remove rules that only produce noise.

3. Run with a focused prompt

Local custom review:

codex review - <<'EOF'
Review the changes on this branch against main for the CSV export feature (ticket #812:
export filtered invoice rows; must not change existing table behavior).
Report only P0-P2 findings. For each: severity, file:line, the failing scenario or input,
why it fails, and a suggested fix. Check: quoting of commas/quotes/newlines in fields,
currency formatting, large exports in the browser, missing tests.
Do not report style issues. If you find nothing at P0-P2, say so.
EOF

A custom prompt replaces the preset targets (--uncommitted, --base, --commit), so when you need a specific range, state it in the prompt (“changes on this branch against main”) or use --base main without a custom prompt.

4. Triage before fixing

For each finding:

1. Locate the code and read enough context to confirm the claim.
2. Reproduce when cheap: a failing test, a one-line script, or a concrete input.
3. Label it confirmed, plausible (needs owner input), or false positive (note why).
4. Only confirmed and accepted plausible findings become changes.

Ask Codex to do this explicitly: “For finding 2, write a failing test that demonstrates it before changing any code.”

5. Fix and re-review

Fix confirmed findings in a separate commit, then run /review or codex review --uncommitted again focused on the fix. On GitHub, @codex fix the P1 issue starts a cloud task with the PR as context and can push a fix when it has permission; review that push like any other.

Writing review prompts for teammates’ PRs

• Lead with intent and risk areas, then the rubric, then the output format.
• Ask for the failing scenario, not just “could be a problem”.
• Cap output: “at most 8 findings, highest severity first”.
• Ask for “no findings” explicitly allowed, to avoid invented issues.
• Include generated files and lockfiles in the ignore list.

Gotchas

• A reviewer that only sees the diff misses broken callers elsewhere. Ask it to grep for usages of changed signatures.
• PR descriptions, commit messages and a branch’s own AGENTS.md are author-controlled; a malicious PR can try to instruct the reviewer. Review rules belong on the base branch.
• Code review rules guide Codex; they do not replace tests, branch protection or required human approval.
• Automatic reviews on every push can spam busy PRs; choose the review trigger in Codex settings deliberately.
• If GitHub reviews do not appear: confirm code review is enabled for the repo, the repo is connected, and the comment is exactly @codex review.

Output contract

## Review: feat/csv-export vs main (14 files, +412 -37)

| # | Sev | Location | Finding | Status |
|---|---|---|---|---|
| 1 | P1 | src/export/csv.ts:42 | Fields containing newlines are not quoted; row splits in Excel. Input: note "a\nb" | Confirmed (test added) |
| 2 | P2 | src/export/csv.ts:88 | Whole result built in memory; 50k rows freezes tab | Plausible, ticket #830 |
| 3 | P2 | app/invoices/page.tsx:120 | No test for empty filter result | Confirmed |

No P0 findings. Not reviewed: generated files, pnpm-lock.yaml.