/ia-code-review

name: ia-code-review
class: discipline
description: >-
  Structured code reviews with severity-ranked findings and deep multi-agent
  mode. Use when performing a code review, auditing code quality, or critiquing
  PRs, MRs, or diffs.

Code Review

**Caller contract:** when the invoking task already defines scope, base SHA, or an output contract (subagent protocols, orchestrated reviews), skip Scope Resolution, Review Mode Selection, and Output Format — apply only the review discipline (two-stage check, severity, evidence rules, anti-patterns) within that contract.

Two-Stage Review

**Stage 1 -- Spec compliance** (do this FIRST): verify the changes implement what was intended — check the PR description, issue, or task spec for missing requirements, unnecessary additions, interpretation gaps. If the implementation is wrong, stop here -- reviewing quality on the wrong feature wastes effort.

**Stage 2 -- Code quality**: only after Stage 1 passes, review for correctness, maintainability, security, and performance.

Scope Resolution

**Pre-flight**: verify `git rev-parse --git-dir` exists before anything else. If not in a git repo, ask for explicit file paths — ask via AskUserQuestion (Claude Code; load with ToolSearch `select:AskUserQuestion` if not loaded) or request_user_input (Codex); fall back to numbered options in chat. Later asks reuse this channel.

When no specific files are given, resolve scope via this fallback chain: 1. User-specified files/directories (explicit request) 2. Session-modified files (`git diff --name-only`, unstaged + staged) 3. All uncommitted files (`git diff --name-only HEAD`) 4. Untracked files (`git ls-files --others --exclude-standard`) -- often the most review-worthy 5. **Zero files → stop.** Ask what to review (ask channel above).

Exclude: lockfiles, minified/bundled output, vendored/generated code.

Base-branch resolution for branch reviews

When the review target is a branch (not a working-tree diff), the comparison range is the **merge-base**, not the working-tree delta — resolve it before reading any diff. Fallback chain (PR base → default-branch inference → `origin/*` → `git merge-base` → unshallow retry), stacked-branch detail, and the "never fall back to `git diff HEAD`" rule in [scope-resolution.md](./references/scope-resolution.md). Stacked branches: prefer the platform's `base_sha` (`gh pr diff`) — a local merge-base over-covers.

**Off-scope filter (always, after any branch review): intersect finding paths with the change's `--name-only` set; discard non-intersecting findings.**

Review Mode Selection

**Run this BEFORE reading the full diff.** Use metadata only (`git diff --stat`, file list from scope resolution) — reading the diff first creates analysis momentum that bypasses mode selection.

**Exceptions first** — these change types stay single-pass regardless of signal count: pure documentation/markdown changes; mechanical refactors (renames, moves) with no logic changes; single-file changes under 50 lines.

**Verification-mechanism carve-out:** even when a change stays single-pass by the exceptions above, if it *is* a verification mechanism (CI/CD gate, merge-block check, coverage/lint gate, build/deploy step, or test infra/mock that could mask a real failure), apply the "can this silently false-pass?" lens during the single-pass review — the mechanism can go green while the thing it guards is red. In deep review this same lens runs as a size-independent red-team trigger (see [deep-review.md](./references/deep-review.md)).

| Signal | Threshold | |--------|-----------| | Lines changed (excluding test files) | >300 | | Files touched (excluding test files) | >8 | | Top-level directories spanned (non-test) | >3 | | Security-sensitive paths (auth, crypto, payments, permissions) | any | | Database migrations | any | | API surface changes (public endpoints, exported interfaces) | any |

**Test file exclusion:** filter test paths out of the size signals with `git diff --stat -- ':!tests/' ':!*.test.*' ':!*.spec.*' ':!*_test.*'` and report both totals: "450 lines changed (280 excluding tests)."

**3+ signals → deep review.** Inform the user, then dispatch parallel specialist agents per [deep-review.md](./references/deep-review.md). Pass the diff to agents -- do NOT read it first. **Stop here -- skip the Review Process section.**

**2 signals → suggest** (ask channel above): "This touches N files across M modules. Deep review?"

**0-1 signals → standard review.** Proceed to Review Process below.

Override: `deep` forces multi-agent, `quick` forces single-pass.

Review Process

**Standard reviews only** -- deep review is handled by the dispatched specialists.

1. **Context** — before reading code:

• **Scope drift**: compare `git diff --stat` against the PR's stated intent. Classify CLEAN / DRIFT DETECTED / REQUIREMENTS MISSING; on drift, ask the author: ship as-is, split, or remove?
• **Intent**: read the PR description, linked issue, or task spec. Deviation or under-delivery is a finding — the wrong problem solved correctly is still wrong.
• **Prior discussions**: reconcile existing review comments so resolved issues aren't re-raised. Gate on a presence check; commands in [scope-resolution.md](./references/scope-resolution.md).
• **Automated gates**: run the project's test/lint suite (canonical commands in CI config).

2. **Structural scan** -- architecture, file organization, API surface; flag breaking changes. Added (`A`) files on a remote branch: use the diff content, not the working tree. 3. **Line-by-line** -- correctness, edge cases, error handling, naming, readability. Category checklists (correctness, maintainability, performance, adversarial, AI-code lens) in [check-categories.md](./references/check-categories.md); load the profile matching the diff's file extensions from [language-profiles.md](./references/language-profiles.md) (TS/React, Python, PHP, Shell/CI, Config, Data, Security, LLM Trust). Prefer