---
name: code-review
description: Clean up comments and mechanical loose ends, then review code with comprehensive and quick modes. Use when reviewing code changes, PRs, or specific files for quality, bugs, and best practices.
argument-hint: '[target] [--quick] [--correctness] [--logic] [--architecture] [--security] [--performance] [--history] [--test] [--interface] [--clean-code] [--functional] [--consistency] [--defensive] [--typescript] [--project] [--library-use] [--staged] [--unpushed] [--all] [--changed] [--multi] [--re]'
effort: high
---

# Code Review: $ARGUMENTS

Review the code related to: **$ARGUMENTS**

## Review grading

Use only these finding priorities, in descending order:

- **Critical Issues (Must Fix):** a verified path causes data loss, a security failure, a materially
  wrong operation, or makes a core workflow unusable without reasonable recovery.
- **Improvements (Should Fix):** an ordinary supported workflow demonstrably fails or repeatedly
  imposes substantial friction, or a concrete design defect creates meaningful maintenance cost.
- **Suggestions (Nice to Have):** a worthwhile improvement with small practical impact, including
  optional polish, local simplification, and rare recoverable edge cases.

Grade the demonstrated consequence, realistic reachability, and available recovery against project
priorities. A category, missing convention, hypothetical future problem, or confidence that a claim
is true does not set its priority. Do not assign automatic severity floors or ceilings. Keep
unverified claims in validation gaps, outside the graded finding count; distinguish suggestions
from defects. For plans, trace the consequence if implemented and state the assumptions.

Use the short labels **Must Fix**, **Should Fix**, and **Nice to Have** in summaries and ledgers.
Keep effort, verification status, user-facing change size, and tool/vendor diagnostic ratings
separate. When called by `code-review`, return its requested evidence and impact fields; the parent
owns scoring and final triage. Otherwise apply this rubric directly. Omit empty priority sections.

## Reference files (load what the run needs)

| File | Load when |
|------|-----------|
| `references/agents.md` | Step 3c in comprehensive mode — the per-agent briefs for Agents 1–10, plus how language / project / library-use reviews plug in. |
| `references/scoring-and-output.md` | Steps 4 to 5 in comprehensive mode — verdict and effort scoring, likelihood/blast-radius triage, applying `autofix` items, and the output format. |

Flag parsing, scope resolution, and the preflight cleanup (Steps 1–3b.6) need neither.

## Usage

```
/code-review                          # Preflight cleanup + all 10 review aspects, default scope
/code-review --quick                  # One integrated review pass, no scorer-agent round
/code-review <target>                 # Preflight cleanup + all 10 aspects, scoped to target
/code-review --architecture           # Architecture only
/code-review --functional             # Functional principles only
/code-review --consistency            # Consistency with existing codebase patterns only
/code-review --correctness            # Logic, failure paths, and changing assumptions
/code-review --security --performance # Two aspects
/code-review --logic src/auth/        # One aspect, scoped to target
/code-review --typescript             # TypeScript-specific review only
/code-review --project                # Project's own review-project checks only
/code-review --library-use            # Library-usage review only (vs the repo's library-use reference)
/code-review --all                    # Whole repo
/code-review --changed                # Unstaged changes only
/code-review --staged                 # Staged changes only (errors if nothing staged)
/code-review --unpushed               # Files changed across all unpushed commits (errors if nothing unpushed)
/code-review --multi                  # All aspects + external advisors
/code-review --multi --architecture   # Architecture only + external advisors
/code-review --all --multi            # Whole repo + external opinions
/code-review --re                     # Review, then re-review only what the fixes changed
```

`--re` composes with comprehensive aspect selections, `--quick`, scope flags, or `--multi`. Invoked after an earlier review in the same conversation, it reviews only what changed since that review (Step 7) instead of starting over.

## Review Modes

The default mode is comprehensive: run all selected perspectives independently, then independently score and triage their findings.

Every mode first runs `review-tidy --fix` over the resolved scope; it coordinates comment cleanup through `review-comments` and then mechanical cleanup, with formatting last. The cleanup is a preflight edit, not a review perspective: its results are reported separately and are never scored or promoted into Must Fix/Should Fix findings.

`--quick` runs one thorough integrated review at full reasoning effort, saving time through fewer agents and no separate scoring round. It keeps the normal scope resolution, project-guideline checks, severity output, fix prompt, and optional `--re` loop, but uses one integrated read-only reviewer and no separate scorer agents. It does not activate automatically from diff size: a tiny auth, migration, or concurrency change may still deserve the comprehensive mode.

`--quick` composes with a target, one scope flag, or `--re`. It cannot be combined with aspect flags or `--multi`; abort with `--quick is a complete review preset; remove the aspect flags or --multi.`

## Aspect Selection

Aspect flags let you run a subset of the review agents instead of all 10. Flags are additive — pass as many as you want. Comment quality is absent from this list because its fix pass always runs before the selected review.

| Flag | Maps to |
|------|---------|
| `--correctness` / `--logic` / `--defensive` | Agent 1: Correctness Review (reads `review-correctness`) |
| `--architecture` | Agent 2: Architecture Review (delegates to `/review-architecture`) |
| `--security` | Agent 3a: Security Review (inline + delegate to `/review-security`) |
| `--performance` | Agent 3b: Performance Review (inline + delegate to `/review-perf`) |
| `--history` | Agent 4: Historical Context Review (inline) |
| `--test` | Agent 5: Test Quality (delegates to `/test --review`) |
| `--interface` | Agent 6: Interface Design (delegates to `/review-interfaces`) |
| `--clean-code` | Agent 7: Clean Code (delegates to `/review-cleancode`) |
| `--functional` | Agent 7b: Functional Review (delegates to `/review-functional`) |
| `--consistency` | Agent 7c: Consistency Review (delegates to `/review-consistency`) |

Further aspects are **conditional add-ons** — in the default (no-aspect-flag) run they are included automatically when they apply; with explicit aspect flags they run only if their own flag is passed (see Step 3b.5 for detection):

| Flag | Maps to |
|------|---------|
| `--cli` / `--react` / `--swiftui` | Agent 8b: Project-Shape Review — delegates to `review-cli`, `review-react`, or `review-swiftui`. Auto-included for console entry points, scoped React components, or scoped SwiftUI implementation. Orthogonal to language: it composes with the language review rather than replacing it. |
| `--typescript` / `--swift` / `--python` | Agent 8: Language Review — delegates to the matching `review-<language>` skill (e.g. `review-typescript`, `review-swift`, `review-python`). Auto-included when the scoped files are of that language. |
| `--project` | Agent 9: Project-Specific Review — delegates to the project's own `review-project` skill. Auto-included when that skill exists in the repo. |
| `--library-use` | Agent 10: Library-Use Review — delegates to `review-library-use` (checks code against the repo's `library-use` conventions). Auto-included when the repo has a `library-use` reference. |

**Aspect rules:**
- Normalize `--logic` and `--defensive` to `--correctness` before selecting agents; any combination of these flags runs Agent 1 exactly once.
- In comprehensive mode, no aspect flags → run all 10 core agents, **plus** any detected language and project-shape reviews, the project review, and the library-use review if present.
- One or more aspect flags → run only those agents, skip the rest. The conditional add-ons run only if `--typescript` / `--cli` / `--react` / `--swiftui` / `--project` / `--library-use` (or another `--<language>`) is among the flags.
- `--quick` is a complete preset and cannot be combined with aspect flags.
- `--multi` composes with any aspect selection.
- The non-flag portion of `$ARGUMENTS` is the review target (e.g. `src/auth/`).

Agents 8–10 are the plug-and-play extension layer (add a language by creating a `review-<language>` skill; add a shape by creating one like `review-cli`; a project adds its own `review-project`). Details in `references/agents.md`.

## Scope Selection

Scope flags determine *which files* the reviewers inspect. The resolved scope is passed through to every review agent or delegated sub-skill.

| Flag | Meaning |
|------|---------|
| `--staged` | Review staged changes only (`git diff --cached`). |
| `--unpushed` | Review files changed across unpushed commits only (`git diff <last-pushed>..HEAD`). |
| `--changed` | Review unstaged changes only (`git diff`). |
| `--all` | Review the whole repo (`git ls-files`). |

**Scope rules:**
- Exactly one scope flag may be passed. Multiple → error.
- **Default (no scope flag):** behave as `--staged` if anything is staged; otherwise auto-fall back to `--changed`. Announce the resolved mode at the start of the run so the user isn't surprised. (`--unpushed` is never auto-selected — it's opt-in only.)
- **Explicit `--staged` with nothing staged:** abort immediately with `Nothing staged. Re-run with --all or --changed.` (Explicit ≠ default — no silent fallback.)
- **Explicit `--unpushed` with nothing unpushed:** abort immediately with `Nothing unpushed. Re-run with --staged, --changed, or --all.` If there is no remote/upstream (or the range walks back to the root commit) so the range can't be determined reliably, abort and ask the user to pick another scope. (Explicit ≠ default — no silent fallback.)
- **Target argument wins:** if a non-flag target is provided (e.g. `/code-review src/auth/`), it overrides scope flags entirely. The target is passed to all sub-agents as-is.

## Gotchas
- Both modes silently drop findings that were not traced to a `file:line` in the code. Comprehensive mode uses independent scorers; quick mode trades that independent validation for a single reviewer's self-filter.
- The verdict is categorical, not a 0–100 score. A model-written number is not a measurement, and a cutoff between anchors flips when the same claim is scored twice.
- The verdict means "is this claim true", never "does it matter". A traced duplication or leaky interface passes as surely as a traced crash and lands in Suggestions or Should Fix by impact. Failing true design findings because they are "not a bug" silently deletes most clean-code and interface output. Effort only orders findings within a section; it never drops one.
- In comprehensive mode, Step 4.5's triage never drops anything silently — every issue routed out of the main severity sections appears in the `Improbable / Not Worth Handling` appendix with its `file:line` and a one-line reason. Quick mode omits low/medium-impact improbable findings entirely to stay concise.
- With `--staged`, the preflight edits the working-tree copies and does not stage them. Announce that the cleanup must be staged separately; never run `git add` implicitly.
- Reviewers run in parallel on one checkout. A reviewer that edits a file, even briefly to mutation-test, makes the others report its edit as a real bug. Every reviewer is read-only; experiments run in a disposable copy (see `references/agents.md`).

## Step 1: Locate and Read Project Guidelines
First, find and read any CLAUDE.md files in the repository root and relevant directories to understand project-specific conventions and rules.

## Step 2: Identify Relevant Code
Search for and identify all files related to "$ARGUMENTS". Use Glob and Grep to find:
- Direct implementations
- Related tests
- Usages/consumers of this code

## Step 3: Resolve Scope and Run the Review

### 3a. Parse flags

If the removed `--comments` aspect flag is passed, abort with `Comment cleanup now runs automatically before every code review. Use review-comments directly for a standalone comment report.`

Strip aspect flags (`--correctness`, `--logic`, `--architecture`, `--security`, `--performance`, `--history`, `--test`, `--interface`, `--clean-code`, `--functional`, `--consistency`, `--defensive`, `--typescript`, `--project`, `--library-use`), scope flags (`--staged`, `--unpushed`, `--all`, `--changed`), `--quick`, `--multi`, and `--re` from `$ARGUMENTS`. The remainder is the review target.

If `--quick` appears with any aspect flag or with `--multi`, abort with `--quick is a complete review preset; remove the aspect flags or --multi.` It may compose with a target, one scope flag, and `--re`.

In comprehensive mode, if any aspect flags are present, launch ONLY the corresponding agents (including the conditional add-ons only when a `--<language>`/`--cli`/`--react`/`--swiftui`/`--project`/`--library-use` flag is passed). Otherwise launch all 10 core agents plus whatever Step 3b.5 detects. In quick mode, follow the single-reviewer branch in Step 3c.

### 3b. Resolve scope

If a non-flag target was provided, skip this section — pass the target through to every agent as-is.

Otherwise, resolve the scope:

1. If more than one scope flag was passed → error: `Pass only one of --staged, --unpushed, --all, --changed.`
2. If `--staged` was passed explicitly:
   - Run `git diff --cached --name-only`. If empty → abort: `Nothing staged. Re-run with --all or --changed.`
   - Resolved scope: `staged`.
3. If `--unpushed` was passed explicitly:
   - Resolve the range: `git rev-list HEAD --not --remotes` (oldest unpushed commit's parent → HEAD). If empty → abort: `Nothing unpushed. Re-run with --staged, --changed, or --all.` If there is no remote/upstream, or the range walks back to the root commit, abort and ask the user to pick another scope.
   - Resolved scope: `unpushed`.
4. If `--changed` was passed: resolved scope is `changed`.
5. If `--all` was passed: resolved scope is `all`.
6. If no scope flag was passed (default):
   - Run `git diff --cached --name-only`. If non-empty → resolved scope is `staged`.
   - Otherwise → resolved scope is `changed`.
   - Announce the resolution: `No scope flag — defaulting to --staged` or `No scope flag and nothing staged — defaulting to --changed`.

Compute the file list once based on resolved scope:
- `staged` → `git diff --cached --name-only`
- `unpushed` → `git diff --name-only $(git rev-list HEAD --not --remotes | tail -1)^..HEAD`
- `changed` → `git diff --name-only`
- `all` → `git ls-files`

This file list is passed to inline agents and is also used to build the target argument for sub-skills that don't natively support `--changed` (see 3c).

### 3b.5. Detect language & project reviews

Determine which conditional add-on reviews apply. In comprehensive mode these become additional agents. In quick mode their skill/reference text becomes guidance for the single integrated reviewer. Skip this entirely if explicit aspect flags were passed **and** none of them is `--typescript`/`--cli`/`--react`/`--swiftui`/`--project`/`--library-use`/another `--<language>` — in that case the user asked for a specific subset and add-ons don't run.

**Language detection registry.** For each language below, it applies if the resolved file list matches its extensions, or (for the `all` scope / when the file list is empty) the repo root has its marker file. If it applies **and** a `review-<language>` skill is installed, include that agent in comprehensive mode or record its `SKILL.md` as guidance for quick mode.

| Language | File extensions | Repo marker | Skill |
|---|---|---|---|
| TypeScript | `.ts` `.tsx` `.mts` `.cts` | `tsconfig.json` | `review-typescript` |
| Swift | `.swift` | `Package.swift`, `*.xcodeproj`, `*.xcworkspace` | `review-swift` |
| Python | `.py` `.pyi` | `pyproject.toml`, `setup.py` | `review-python` |
| Rust | `.rs` | `Cargo.toml` | `review-rust` |

*(To add a language: create a `review-<language>` skill and add a row here.)*

**Project-shape detection.** Shapes are orthogonal to language — a CLI is reviewed the same way whether it is Python or Rust. If the shape applies **and** the matching skill is installed, include that agent in comprehensive mode or record its `SKILL.md` as guidance for quick mode. If the skill is not installed, skip silently.

| Shape | Detected by | Skill |
|---|---|---|
| CLI | `[project.scripts]` / `[project.entry-points."console_scripts"]` in `pyproject.toml`, `[[bin]]` or `src/main.rs` in a Cargo project, `bin` in `package.json`, or a `main`-package `cobra`/`urfave` import in Go | `review-cli` |
| React | `react` in `package.json` dependencies, and scoped `.jsx`/`.tsx` files or files that call hooks (at `all` scope, the dependency alone) | `review-react` |
| SwiftUI | Scoped SwiftUI view, scene, modifier, or control implementation, or UI resources consumed by it; at `all` scope, that implementation anywhere in the project. An import or a Swift project marker alone is insufficient | `review-swiftui` |

In default reviews, when Swift and SwiftUI both apply, include both reviewers. Explicit
aspect flags still select only the requested reviewers. `review-swift` owns state, identity,
lifetime, dependencies, concurrency, and rendering cost; `review-swiftui` owns presentation
and interaction. Pass this boundary to both and deduplicate by the underlying cause.

**Project review detection.** If the repo defines its own project review skill at `.claude/skills/review-project/SKILL.md` **or** `.agents/skills/review-project/SKILL.md`, include the project review agent in comprehensive mode or record its `SKILL.md` as guidance for quick mode. If neither exists, skip silently.

**Library-use review detection.** If the repo has a `library-use` reference at `.claude/skills/library-use/SKILL.md` **or** `.agents/skills/library-use/SKILL.md`, include the `review-library-use` agent in comprehensive mode or record the reference as guidance for quick mode. If neither exists, skip silently (suggesting `library-docs` once is fine, but don't block the review).

Check both paths — `.claude/skills/` is where Claude Code puts project skills; `.agents/skills/` is where the other harnesses discover them. In some projects the latter is a symlink to the former, so either check finds it; others may only have `.agents/skills/`.

Announce what got auto-included. In comprehensive mode, use messages such as `Detected TypeScript — adding review-typescript` or `Detected a CLI entry point — adding review-cli`. In quick mode, say `Detected TypeScript — applying review-typescript guidance in the quick review` (and likewise for project and library-use guidance).

### 3b.6. Preflight cleanup

::: claude codex opencode
Before launching any review agent, invoke `review-tidy --fix` exactly once against the resolved scope. It owns the `review-comments` invocation and runs formatting after all cleanup edits; do not invoke comment cleanup separately.
:::
::: pi
Before launching any review agent, run `review-tidy --fix` exactly once against the resolved scope — **in this session, not as a subagent**. pi has no Skill tool, so read its `SKILL.md` and apply it directly, including its nested `review-comments` instructions. Do not invoke comment cleanup separately. Cleanup edits files, which the read-only `reviewer` agent cannot do; `agent:` names an agent, never a skill.
:::

| Resolved scope | Arguments for review-tidy |
|---|---|
| `staged` | `--staged --fix` |
| `unpushed` | `--unpushed --fix` |
| `changed` | `--changed --fix` |
| `all` | `--all --fix` |
| local path target | `<target> --fix` |
| other target, such as a PR | `<resolved local source file list> --fix` |

Treat its combined output as a preflight cleanup summary, not as review findings. Report how many comments were removed or rewritten and what mechanical fixes were applied, and list the deferred items, but do not send those items through scoring or severity triage. Continue immediately when they find nothing.

If a non-file target has no writable local source files, skip the cleanup and state that it requires a local checkout; do not turn that limitation into a review finding.

Keep the file list resolved in Step 3b even if cleanup edits change git status. Review the current contents of those same files, using the originally resolved diff or target to identify the intended change. With `staged` scope, explicitly say the cleanup edits are unstaged and must be staged separately; do not mutate the index.

### 3c. Run the selected mode

#### Quick mode (`--quick`)

::: claude codex opencode
Do not load `references/agents.md`. Launch exactly **one read-only review agent** and give it the resolved scope or target. Use the same model and reasoning effort as a comprehensive reviewer; do not select a faster profile or lower effort for quick mode. It must not delegate to sub-skills or dispatch more agents.
:::
::: pi
Do not load `references/agents.md`. Launch exactly **one** child via `subagent` using the builtin **`reviewer`** agent, and give it the brief below plus the resolved file list. `reviewer` grants only `read, grep, find, ls` — no bash, no edit, no nested dispatch — so it is read-only by construction. Because it has no bash it cannot resolve a scope itself: pass the concrete file list, not `--staged`.
:::

For every harness, retain full review reasoning effort. Give the reviewer this integrated brief:

- Read the applicable `AGENTS.md` / `CLAUDE.md` files and the scoped diff or files. For each changed behavior, trace the path from its callers through the implementation and dependencies to its observable result, including failure paths. Read surrounding code and related tests to check the contracts at each boundary; do not stop at the diff hunks. For a whole-file or whole-repo target, trace the main behaviors in scope.
- Read `review-correctness` and apply both passes directly without launching another reviewer. Review correctness, edge cases, error handling, regressions, catch-all `else`/`default` branches that would silently absorb a newly added enum or API value, missing or weak tests, security red flags, and interface compatibility. Check performance hazards supported by the traced paths. Also check design and maintainability: module responsibilities, coupling, duplication, interface clarity, hidden shared state, and mutation of caller-owned data. Check consistency: compare each added construct with two or more existing siblings of the same kind and flag divergences in naming, placement, mechanism (errors, logging, config, existing helpers) or registration, citing the precedent `file:line`s; documented project rules and newer patterns win over older precedent. Tie each concern to concrete code and its consequences.
- If Step 3b.5 detected language, project-shape, project, or library-use guidance, read those matching `SKILL.md` files as review references and apply their checks directly. Do not invoke them as skills.
- Before accepting or dismissing a suspected issue, trace a concrete triggering input or state, inspect callers and excluding guards, and check whether tests exercise the behavior and assert the relevant result. Use targeted checks when available; run any experiment that writes files in a disposable copy. If the reviewer lacks execution tools, request a specific check from the parent, which must resolve it before final filtering or report the remaining uncertainty.
- Return only actionable findings supported by a concrete code path. For each finding, include severity (`Must Fix`, `Should Fix`, or `Nice to Have`, using Review grading above), `file:line`, what is wrong, why it matters, a concise fix, the `file:line` where you traced it, effort (`S`: one file, local, no interface or test changes; `M`: several files or new or changed tests; `L`: a public interface, a migration, or callers in other modules), likelihood (`routine`, `plausible`, `rare`, or `theoretical`), and blast radius (`low`, `medium`, or `high`). For `rare` or `theoretical`, name the reachability reason and cite any excluding guard.
- After verification, omit findings you did not trace through every link in the code and omit `rare`/`theoretical` findings with low or medium blast radius. Keep rare high-blast-radius findings and tag them with the short reachability reason. Tracing decides only whether the claim is true; a true finding that matters little is `Nice to Have`, not dropped.
- Tag a finding `autofix` when its fix cannot change production behaviour, any change in what a test executes is proven by running tests, and a wrong call would be visible in the diff and cheap to revert. It must not need new prose, a design choice, or an edit to exported or public code. Examples: a doc line naming a symbol or flag the diff renamed, an import the diff orphaned, a test name that no longer matches, an unexported identifier renamed to the codebase's naming pattern. When the fix changes what a test executes, append `verify: suite` if test code moves unchanged, or `verify: mutation` if it substitutes different test code.
- Do not edit the shared checkout, even temporarily; keep any experiment writes in a disposable copy.
- Always return a short coverage statement naming the behaviors traced, callers/dependencies and tests examined, and checks actually run. State any unexamined scope, checks not run, and material unresolved uncertainties; distinguish these from confirmed findings. Do not infer safety from missing evidence.
- Return `No actionable findings.` if nothing survives, followed by the coverage statement and any limitations.

After the agent returns, resolve any requested verification checks before final filtering, without launching more reviewers or scorers. Apply its `autofix` findings yourself after checking each still meets that test, and list them under `Applied automatically`; a finding that fails the test goes to its severity section instead. Run a `verify:` item's check first, in a disposable copy with the fix applied: for `verify: suite` the full test suite must pass under `timeout`; for `verify: mutation` the affected tests must pass, then fail once you break the behaviour they assert in the code under test (grep to confirm the break landed). An item whose check fails or cannot run goes to its severity section. Deduplicate the rest and render the surviving items under `Critical Issues (Must Fix)`, `Improvements (Should Fix)`, and `Suggestions (Nice to Have)`, omitting empty sections. Within a section, list `S` findings first, then `M`, then `L`, each prefixed with its effort tag (`[S]`, `[M]`, `[L]`). Explain what is wrong, why it matters, and how to fix it. Include the coverage statement and material limitations even when there are no findings. Do not show likelihood or blast-radius metadata and do not launch scorer agents. Then continue to Step 5.5.

#### Comprehensive mode

**Load `references/agents.md`** — it carries the brief for each of Agents 1–10.

Launch the selected review perspectives in parallel, queuing successive batches when runtime capacity requires it.

**One agent per perspective.** Never pair two aspects in one brief to save agents, not even small ones. A capacity limit queues reviewers; it never merges them. A past run paired functional with consistency, and the consistency half came back covering only what its brief listed.

**Brief with the scope, not a checklist of where to look.** Give each reviewer the resolved scope or file list, the project facts it cannot cheaply discover, and its aspect brief from `references/agents.md`. Do not list the units, files or precedents it should examine: a reviewer handed "focus on X, Y, Z" reviews X, Y and Z, and the rest of the diff goes unreviewed for that aspect. If a fact about one file matters, state it as context and say the whole file list remains in scope.

::: claude
**Claude Code caps concurrent subagents** at `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`. Launch up to that many at once, then launch each remaining reviewer as soon as one returns. A launch refused with `Concurrent subagent limit reached` never ran: despite the message's "Do not retry", queue it and launch it when a slot frees, and never drop the aspect. The same limit applies to the scorer round.
:::

::: claude codex opencode
**Launch workers that return findings without editing files**, including temporary edits: a reviewer that mutates a file to test something and restores it still corrupts what the parallel reviewers read. Include the shared rules from `references/agents.md` in every brief. Disable delegation tools for ordinary reviewers where supported; read-only access alone does not prevent delegation. If a reviewer coordinates verification, name the checks, bound the descendants, and define when it should stop. Workers can read the relevant sub-skill directly when their harness has no Skill tool.
:::
::: pi
**Launch them read-only, as one `subagent` workflow.** pi fans out through a `workflowScript`, not through repeated tool calls — one `subagent` call carrying `runs.all([...])`, one entry per perspective, every entry on the builtin **`reviewer`** agent:
:::
::: pi
```js
{ workflowScript: `
  const results = await runs.all([
    { key: "correctness",    agent: "reviewer", task: "<brief for Agent 1 + resolved file list>" },
    { key: "security", agent: "reviewer", task: "<brief for Agent 3 + resolved file list>" }
  ]);
  return results.map(r => r.output);
` }
```
:::
::: pi
`reviewer` grants only `read, grep, find, ls`, so it cannot edit the code it reviews and cannot dispatch further. Use it for the scorer round in Steps 4–5 too. Two pi-specific rules:

- **The `agent` field takes a pi agent name, never a skill name.** The builtins are `scout`, `researcher`, `worker`, `reviewer`, `oracle`, `delegate`; custom agents live in `~/.pi/agent/agents/`. `{ agent: "review-security" }` fails the whole workflow with `Unknown agent: review-security`. Every harness works this way — identity comes from the agent registry, the task comes from the prompt — so this is not a pi quirk.
- **Children reach a sub-skill as a file, not as a tool call.** pi has no Skill tool. `reviewer` runs with `inheritSkills: true` (set in `loadout/settings/pi.json` under `subagents.agentOverrides`), so it sees the skills catalog and loads a `SKILL.md` with `read` when a brief names one.
:::

Each agent should output a list of issues. For each issue, include: what the problem is, where it is (file + line), and why it matters, and tag safe fixes `autofix` as defined in `references/agents.md`. Do NOT assign verdicts or effort — scoring happens in a separate pass.

::: claude codex opencode
**Sub-agent invocation pattern.** When a sub-agent delegates to a sub-skill, pass the resolved scope through directly:
:::
::: pi
**Sub-agent invocation pattern.** Name the sub-skill in the child's `task` and let it `read` that `SKILL.md` itself — delegation works, it just resolves through the filesystem rather than a Skill tool. What does *not* carry over is the scope flag: `reviewer` has no bash, so it cannot turn `--staged` into a file list. Pass the concrete list resolved in Step 3b instead. The table below is therefore read as scope→file-list on pi, not scope→flag.
:::
::: claude codex opencode

| Resolved scope | Argument passed to sub-skill |
|---|---|
| `staged` | `--staged` |
| `unpushed` | `--unpushed` |
| `changed` | `--changed` |
| `all` | `--all` |
| target given | the target itself (e.g. `src/auth/`) |

All delegated review sub-skills (`review-architecture`, `review-security`, `review-perf`, `review-interfaces`, `review-cleancode`, `review-functional`, `review-consistency`, `review-correctness`, `review-typescript`, `test --review`) accept `--staged | --unpushed | --changed | --all`. No special-casing needed. The project's `review-project` skill is expected to accept the same scope flags — if it doesn't, pass it the target/file list instead.

:::
Inline agents (no delegation) work directly against the file list computed in step 3b.

## Step 3.5: External Advisor Reviews (--multi only)

If `--multi` flag is present in $ARGUMENTS, also get external opinions:

::: claude codex opencode
Use the **Skill tool** to invoke `second-opinion --quick`, which queries every external advisor it has configured, in parallel. (The advisor roster lives in the `second-opinion` skill — don't enumerate it here.) Phrase the prompt according to the resolved scope from step 3b:
:::
::: pi
pi has no Skill tool. Read `second-opinion/SKILL.md` from the skills directory and run its advisor commands yourself with `bash`, backgrounding them so they run in parallel. Do not dispatch `second-opinion` as a subagent — it is a skill name, not an agent name. Phrase the prompt according to the resolved scope from step 3b:
:::

- `staged` → "Review the staged changes (`git diff --cached`) in this repository."
- `unpushed` → "Review the changes across all unpushed commits (`git diff` against the last pushed commit) in this repository."
- `changed` → "Review the unstaged changes (`git diff`) in this repository."
- `all` → "Review the codebase in this repository as a whole."
- target given → "Review the following target in this repository: `<target>`."

Then append: "Provide a focused code review in 300 words or less covering: potential bugs or edge cases, security concerns, performance issues, and architecture/pattern violations."

**IMPORTANT:** Do NOT proceed to Step 4 until the second-opinion results have been fully received. Wait for all background commands to complete and collect their output before continuing. This prevents completion notifications from appearing after the review summary. If an advisor is missing or errors out, continue with whichever responded — don't drop the others.

## Steps 4 to 5: Score, Triage, Autofix, Format (comprehensive mode only)

Skip these steps in quick mode; Step 3c already produced the filtered, formatted review. In comprehensive mode, **load `references/scoring-and-output.md`** and follow it. In short: score every issue with independent parallel scorers using the exact prompt there (only `traced` passes, and the verdict means only "is this true"), have those same scorers return impact, effort, likelihood and blast radius so improbable findings route to an appendix instead of the work list, apply the `autofix` items, then render the severity sections.

When that reference is done, **come back here and do Steps 5.5 and 6** — the rendered output is not the end of the run.

## Step 5.5: Snapshot the reviewed state

In both modes, after the output is rendered and any `autofix` items are applied, record what was reviewed so a re-review can find what changed since. In the session's scratch directory:

- copy every existing file in the Step 3b file list to `cr-snapshot/<round>/`, keeping its repo-relative path;
- save `git status --porcelain` there as `status.txt`;
- save the findings list as `findings.md`: each finding's aspect, `file:line`, one-line claim and section. Step 6 adds each one's disposition (`fixed`, `declined`, or `appendix`) once known.

Do not use `git stash`, commits or any other git write for this. The snapshot is local scratch, not history.

## Step 6: Offer to Fix

**This step is mandatory.** Rendering the review output is *not* the end of the workflow — do not end the turn after printing the findings. If there is at least one **Must Fix** or **Should Fix** finding, you MUST call the **AskUserQuestion tool** so the user picks a fix scope by selection instead of typing one out.

Build the options list from the severity tiers that actually have findings, most-inclusive first:

| Option | Fixes | Include when |
|---|---|---|
| **"Fix everything"** | Must Fix + Improvements + Suggestions | there are `Suggestions (Nice to Have)` findings alongside at least one Must Fix or Should Fix finding |
| **"Address Must Fix + Should Fix"** | Must Fix + Improvements | there are both Must Fix and Should Fix findings |
| **"Address Must Fix only"** | Must Fix | there are Must Fix findings |
| **"Fix Should Fix"** | Improvements | there are Should Fix findings but no Must Fix findings |
| **"Don't fix anything"** | nothing | always — last option |

AskUserQuestion takes at most 4 options, so when all tiers are populated drop the narrowest fix option (`Address Must Fix only`) rather than `Don't fix anything` — the user can still ask for a narrower scope in free text.

Skip this step entirely (no prompt) only when there are no Must Fix and no Should Fix findings — a run that surfaced nothing but suggestions has nothing worth gating on.

Build the options only from the `Critical Issues`, `Improvements`, and `Suggestions` sections. `Applied automatically` items are already done and are never offered. **Never include `Improbable / Not Worth Handling` items** — not even under "Fix everything". Step 4.5 already judged them not worth doing, and offering to fix them reintroduces exactly the noise the appendix exists to remove.

When the user selects a fix option, apply the fixes for exactly the chosen severity tier(s) — no more, no less. Record each finding's disposition in the snapshot's `findings.md`.

Code written to fix a finding has not been reviewed. Without `--re`, end the run with a `Not yet reviewed` line naming the files the fixes changed, and suggest `/code-review --re`, which reviews only those changes.

## Step 7: Re-Review the Fixes (`--re`)

A re-review checks only what changed since the last snapshot: the fixes, plus anything else edited since. It is not a second full review, and it does not re-run the preflight cleanup on unchanged files.

It runs in two cases:

- `--re` was passed and Step 6 applied fixes: continue straight into it.
- `/code-review --re` is invoked and an earlier review in this conversation left a Step 5.5 snapshot: skip Steps 1–6 and start here from the latest snapshot. This covers fixes applied after the review ended, by the user or by a calling skill. With no snapshot in the conversation, run a normal review that loops as in the first case.

Announce it, e.g. `Re-reviewing the 4 files changed since the review (--re)`.

### 7a. Compute the delta

Compare each snapshot file with its current content (`git diff --no-index`), and compare `git status --porcelain` with `status.txt` to find files created, deleted or renamed since. The delta is those hunks and files. If it is empty, say `Nothing changed since the review.` and stop.

If `findings.md` has no dispositions because the fixes were made outside Step 6, mark each finding whose `file:line` falls in the delta as `fixed` and the rest as `declined`.

### 7b. Pick the aspects

Start from the aspect of every finding marked `fixed`, so each fix is checked against the finding it addressed. Then add aspects for what the delta contains:

| The delta contains | Add |
|---|---|
| Changed conditions, control flow, data handling, async or error paths | correctness |
| New or renamed identifiers, files, components, props, exports, keys or strings | consistency, interface |
| New or changed tests, or production changes with no test change | test |
| Changed exported signatures, or code moved between modules | architecture, interface |
| Auth, URLs, input parsing, secrets, shell or SQL | security |
| Loops, queries, render paths or caches | performance |
| Files a language, shape, project or library-use reviewer covered in the original run | that reviewer |

If the original run used aspect flags, choose only from those aspects, plus correctness when production code changed. History, and functional unless the delta adds state or mutation, are rarely worth a re-review.

### 7c. Pick the depth

Use the delta's size, not the original run's mode:

| Delta | How |
|---|---|
| Renames, moves, strings, comments or config only, under ~30 changed lines, no logic | **No sub-agents.** Check it yourself: confirm each fixed finding is resolved, grep for references to anything renamed or removed (string literals included), run the affected tests under `timeout`. |
| Under ~200 changed lines across at most ~6 files, or the original run was `--quick` | **One reviewer**, using the quick-mode brief from Step 3c with the delta as its scope and the aspects from 7b as its checklist. No scorer round. |
| Larger | **Comprehensive mode, limited to the aspects from 7b**, one agent each, scored as usual. Re-run external advisors only here, and only if the original run used `--multi`. |

### 7d. Brief and report

Every re-review brief (or your own check) gets:

- the delta as the scope, with the original diff and the full files as context only;
- each `fixed` finding, to confirm resolved or report as not resolved;
- each `declined` or `appendix` finding, marked as already decided: not to be raised again;
- the instruction to report only issues in the delta or caused by it.

Render a `Re-review of fixes` section listing each fixed finding as `resolved` or `not resolved`, then any new findings in the usual severity sections. Take a new Step 5.5 snapshot, then run Step 6 as normal. The loop ends when a re-review has no Must Fix or Should Fix findings, or the user picks "Don't fix anything".

## Examples

**Clean up, then review the default scope with all 10 agents:**
> /code-review

Runs `review-tidy --fix` (including comment cleanup), then 10 parallel review agents (correctness, architecture, security, performance, historical context, test quality, interface design, clean code, functional principles, consistency with existing patterns) against staged changes (or unstaged changes if nothing is staged). The cleanup is summarized separately; review findings are prioritized by severity.

**Quick review of a routine small change:**
> /code-review --quick

Runs one integrated read-only reviewer against staged changes (or unstaged changes if nothing is staged). It uses full reasoning effort, traces behavior through callers, dependencies, and tests, and checks design alongside correctness. It applies detected language, project, and library-use guidance directly, verifies suspected issues before filtering, and reports coverage and unresolved uncertainties. It skips the independent scorer-agent round.

**Focused single-aspect review:**
> /code-review --architecture

Runs only the architecture & patterns agent. Use this when you already know which concern you care about and don't want to wait on the other 9 core agents or sift through their output. Flags are additive — combine them (e.g. `--security --performance`) to run a handful of aspects without running them all.

**Whole-repo review:**
> /code-review --all

Runs the preflight cleanup and all 10 agents against every file in the repo (`git ls-files`). Use this for a fresh audit of an unfamiliar project, before a major release, or when nothing in the working tree is changed. Composes with aspect flags and `--multi`, e.g. `/code-review --all --architecture --multi`.

**Cross-model consensus review:**
> /code-review --multi

Runs the same 10 review agents plus external reviews from every advisor `second-opinion` has configured, after the preflight cleanup. The output includes a cross-model agreement section highlighting issues where the internal agents and external advisors converge, giving higher confidence to consensus findings. `--multi` composes with aspect and scope flags, e.g. `/code-review --multi --architecture` or `/code-review --all --multi`.

**Review, fix, then re-review automatically:**
> /code-review --re

Runs the review, offers the fix prompt (Step 6), and once fixes are applied, re-reviews only what they changed. It confirms each fixed finding is resolved and checks the new code with the aspects that change touches. A rename-only fix gets no sub-agents at all, and a small fix gets one reviewer. The loop continues until a re-review comes back with no Must Fix/Should Fix findings or the user declines to fix. Run `/code-review --re` later in the same conversation to re-review fixes made after the review ended.

## Troubleshooting

### Too many changed files for agents to handle
**Solution:** Narrow the review scope by targeting a specific directory or file pattern (e.g., `/code-review src/auth/`) instead of the entire changeset, or break the PR into smaller, focused reviews.

### Agent returns shallow or redundant findings
**Solution:** Ensure the review target is specific enough to give agents meaningful context; vague targets like "everything" produce generic results. Re-run with a focused target and verify that CLAUDE.md contains project-specific patterns the agents can check against.
