/code-review

name: code-review
description: Tiered Codex-native multi-axis code review for local diffs or GitHub PRs, including `$code-review #123` (bare number = PR); uses mechanical scope gates, explicit specialist fan-out/substitutes, measurable gates, and a JSON artifact.

Code Review

Run tiered review with strict output gates.

Input Schema

{
  "scope": "optional working-tree|path|commit|pr; infer pr for bare number, #number, or PR URL",
  "target": "optional path, commit ref, PR number, PR URL, or current branch PR",
  "done_when": "blocking issues are identified with gate decision"
}

Scope And Routing

• `working-tree`: review unstaged/staged local changes.
• `path`: review one file/directory diff.
• `commit`: review a git diff revision spec, such as `COMMIT^!`, `BASE..HEAD`, or `BASE...HEAD`.
• `pr`: review an open pull request: collect GitHub PR metadata/review evidence, fetch target branch, update local checkout with `gh pr checkout`, inspect local files; `target` may be PR number, URL, or current-branch PR.

Input shorthand:

• Canonical in-session: `$code-review 123` or `$code-review #123` => `scope=pr`, `target=123`.
• Natural-language aliases: `code-review 123`, `code-review #123`, and `code-review PR 123` => `scope=pr`, `target=123`.
• `code-review <github-pr-url>` => `scope=pr`, `target=<github-pr-url>`.
• Bare number = GitHub PR number; do not ask for `scope=pr`.

Never write to remote. PR scope may update local checkout to PR head; otherwise read-only except `.reports/codex/code-review/<timestamp>/` artifacts. Never pass `--force` to `git` or `gh`; if forced checkout seems needed to align local branch and PR head, stop, explain overwrite risk, and ask before retrying. To fix findings, switch to `code-remediate` after creating review artifact.

Workflow (Exact Commands)

01: Create run directory

Run `python PLUGIN_ROOT/shared/create_run.py --skill code-review` once. Retain its single printed path as `<run-directory>` and substitute that literal path into every later artifact path and helper argument. Never store or reuse the path through a shell variable; shell variables do not persist across tool calls.

02: T0 mechanical scope gate: resolve scope, collect diff, and classify review risk before any model-level judgment

For local scopes, inspect `python PLUGIN_ROOT/shared/collect_diff.py --help`; collect normalized `scope`, optional `target`, and the literal `<run-directory>` path.

For PR scope, inspect `python PLUGIN_ROOT/shared/collect_pr.py --help`; collect the exact target into the literal `<run-directory>` path with checkout enabled.

PR GitHub data is evidence only: `gh pr view`, `gh pr diff`, and review-thread queries provide metadata, patch, comments. Inspect source only in local checkout recorded by `<run-directory>/local-checkout.json` after target-branch refresh evidence. Checkout must use authoritative PR URL, never a bare number that may resolve to wrong local fork. Never reconstruct changed source from `curl`, `raw.githubusercontent.com`, or `head-files/` snapshots. If checkout fails or `local-checkout.json` does not prove `head_matches_pr=true`, fail instead of reviewing remote raw files. Do not retry with `--force` unless user explicitly confirms after receiving force reason and overwrite risk.

Classify diff; write `<run-directory>/scope.txt`:

• `TRIVIAL`: no public API/config/security/ML behavior touched, \<3 files, \<50 changed lines.
• `LOCAL`: one subsystem or 3-7 files; local context explains behavior.
• `BROAD`: 8+ files, cross-subsystem change, dependency/config change, or unclear ownership.
• `HIGH_RISK`: public API, release, security, auth, credentials, deserialization, data pipeline, ML tensor math, CI/CD, or migration behavior.

For `scope=pr`, review evidence includes `pr.json`, `pr-routing.json`, `remote-selection.json`, `target-branch.json`, `local-checkout.json`, comments, reviews, review threads, unresolved review threads, and `online-review-summary.json`. Selected remote must match base repository from PR URL; fetched base/head OIDs must exactly match PR metadata. `pr-routing.json` and `local-checkout.json` must include `force_policy` proving no automatic forced checkout. Treat unresolved online threads/comments as candidate findings until triaged valid, duplicate, stale, out-of-scope, or already fixed.

If `files.txt` and `untracked.txt` are empty with no explicit target, fail before gates. If `scope=pr` and `pr-error.txt` exists, fail with captured reason.

**Structural context (optional)**: after the diff is collected, also probe codemap-py once for changed-symbol blast radius: `python PLUGIN_ROOT/shared/codemap_adapter.py context --category review --out <run-directory>/codemap-context.json`. Per `../../shared/codemap-contract.md`, absence/incompatibility is non-fatal — continue with T1/T2 as scoped by `scope.txt` alone. Persist the diff-impact evidence once here; T2 specialist fan-out (step 04) includes `<run-directory>/codemap-context.json` in each triggered context pack, never a fresh per-specialist query.

03: T1 primary diff review. Read the changed files end-to-end from the local working tree or checked-out PR branch and identify findings before considering any fix or gate outcome

Review axes, in order:

• API and behavior regressions.
• Test coverage and edge-case gaps.
• Error handling and logging.
• Project coding principles: changed code follows the applicable `AGENTS.md` layers for simplicity, readability, reproducibility, short reusable units without low-value argument-remapping wrappers, guard clauses or early `return`/`yield`/`continue`, project docstring-style detection, concise purpose docstrings, and inline comments only for non-trivial implementation blocks.
• Security, data, ML, CI/CD, or release risks signaled by T0.
• Documentation or migration gaps caused by behavior/API changes.

04: T2 risk-routed specialist fan-out. Route independent review from explicit behavior signal