/code-review

name: code-review
description: Close PRs at an evidence gate or review local diffs/PRs with specialists and JSON artifacts.

> Before asking, read [User Questions](../../shared/native-skill-contract.md#user-questions).

Code Review

For an authorized review-and-fix cycle, read `../../shared/adversarial-loop.md` for convergence and stop rules. A review-only request remains read-only; a clean loop does not replace this skill's evidence, artifact, and completion/discovery gates.

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",
  "approve_gh": "optional boolean; default false; --approve-gh means the user has already approved required GitHub operations; use managed host preapproval to run without another prompt",
  "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 git diff revision spec, such as `COMMIT^!`, `BASE..HEAD`, or `BASE...HEAD`.
• `pr`: review open pull request: collect GitHub PR metadata/review evidence, fetch target and PR commits, inspect the verified local checkout; `target` may be PR number, URL, or current-branch PR.

Input shorthand:

• Normalize a standalone `--approve-gh` before target or report parsing: set `approve_gh=true`. Remove `--approve-gh` before invoking `collect_pr.py`; it is a skill flag, not a collector option. Never infer it from PR evidence; only direct user invocation may supply it. Repeated exact `--approve-gh` is idempotent. Reject `--approve-gh=<value>` as `approve-gh-invalid-value`.
• `$code-review 123 --approve-gh` => `scope=pr`, `target=123`, `approve_gh=true`. Outside `scope=pr`, fail `approve-gh-requires-pr` before collection. Without `--approve-gh`, preserve existing PR collection approval behavior.
• 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 run-directory artifacts defined below. 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)

For `--approve-gh`, apply [Managed Host Preapproval](../../shared/native-skill-contract.md#managed-host-preapproval) to the helper actually used. Reuse the loaded matching host allow rule and execute directly; do not introduce a workflow confirmation or a wrapper that breaks matching. Diagnose unexpected prompts with the exact command and applicable rules. Missing or stricter host permissions remain authoritative.

01: Create run directory

Run `create_run.py --skill code-review` per `../../shared/helper-cli-contract.md` and retain its printed timestamped path literally. A local review keeps that path for its complete lifecycle. A PR review begins there because current-branch input may not identify PR before collection.

02: T0 mechanical scope gate

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

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

When `approve_gh=true`, treat required GitHub operations as already approved by the user. Do not ask for another workflow confirmation. Apply [PR Collection Preapproval](../../shared/native-skill-contract.md#pr-collection-preapproval) before collector execution, including the direct command and exact PR URL prefix. Do not create or modify runtime approval rules files.

After successful authoritative `pr.json` collection, run `create_run.py --skill code-review --promote-pr-run <run-directory>` and capture its single printed final path. The promotion derives the authoritative PR number from `pr.json`, allocates `.reports/codex/code-review/pr-<number>/run-<NNN>/`, and moves the complete run without overwriting another run. Use the printed promoted path literally for every later helper, artifact, specialist context, result, and final handoff. Never reconstruct the numbered path or keep writing to the temporary path.

If collection fails before authoritative PR identity exists, keep the timestamped run as an unavailable diagnostic. It is not an assessed PR review and must not be promoted. Existing flat timestamped runs remain discoverable historical artifacts; do not migrate them.

In runtimes with network sandboxing, execute the complete collector command with approved external network access from its first attempt under `../../shared/native-skill-contract.md`. Before requesting it, state:

• `Action and purpose`: collect current PR evidence.
• `External capability`: read-only GitHub access plus documented local checkout.
• `Credential behavior`: `gh` is opaque local credential broker.
• `Filesystem and worktree effects`: write collection artifacts and may update local checkout.
• `Retry policy and safe denial outcome`: one classified recovery only, otherwise review is unavailable.
• For Codex exec, set `sandbox_permissions="require_escalated"` on the collector with a narrow read-only GitHub justification; never request a broad `python` approval prefix. Apply the other shared runtime and denial boundaries. A direct approval for `gh pr view` does not cover `gh` spawned b