code-review

When running a code review, follow the process outlined here.

Project Context

• git installed: !which git
• CLAUDE.md: !find . -maxdepth 1 -name "CLAUDE.md" -type f
• project-discovery.md: !find . -maxdepth 3 -name "project-discovery.md" -type f

Review Constraints

Severity levels:

• Critical — Must fix before merge. Security vulnerabilities, data corruption risk, breaking API changes, data isolation failures.
• Warning — Should fix. Bugs that don't corrupt data, significant performance issues, missing required tests, missing error handling.
• Suggestion — Consider improving. Style improvements, optional performance gains, documentation gaps, refactoring opportunities.

Severity calibration is governed by Step 3.3 (the authoritative home for size-based demotion). Manual findings from Steps 4 to 6 follow the same size-based rules as agent findings classified at Step 7: Small changes escalate only Critical findings and default uncertain ones to the lower severity, Medium changes escalate Critical and Warning, Large changes prefer the higher severity when in doubt. Read {size} from Step 3.1. Include file_path:line_number references and code examples for suggested fixes.

Finding caps: Manual review findings (Steps 4-6) and agent findings (Step 7) are each capped at 30 items. Prioritize by severity: all CRIT first, then WARN, then SUGG. If either cap is exceeded, note that additional items were omitted and another code review is recommended after addressing current items. Security findings are not capped (see classification rubric).

Project pattern deference: A pattern that differs from general best practices but is consistent within the project is not a review finding. Only flag deviations from the project's own conventions.

YAGNI findings are a separate, non-correcting class. Apply the two-pass YAGNI procedure documented in references/review-checklist.md (Pass 1 runs the evidence test from ../../references/yagni-rule.md Gate 1; Pass 2 matches against the named anti-patterns) to every change in the diff. YAGNI findings are listed in their own ### 🟡 YAGNI section, separate from Critical / Warning / Suggestion, and do not appear under CRIT / WARN / SUGG. The YAGNI section opens with this exact statement: "These findings will not be corrected unless explicitly requested. They are documented so the team can decide consciously whether to keep, simplify, or defer the items." Each YAGNI finding records (a) the failing evidence type from Pass 1, (b) the matched anti-pattern from Pass 2, and (c) the simpler form considered. Severity calibration (the directive in Step 3.3, the authoritative home) does NOT apply to YAGNI; these findings are surfaced regardless of change size and are advisory, not corrective.

Automated tool boundary: If the project has a linter or formatter, trust it. Only flag style issues that automated tools can't catch.

Task ID Assignment

Assign a unique task ID to each review item:

• CRIT-### for critical items (e.g., CRIT-001, CRIT-002)
• WARN-### for warnings (e.g., WARN-001, WARN-002)
• SUGG-### for suggestions (e.g., SUGG-001, SUGG-002)
• YAGNI-### for YAGNI candidates (e.g., YAGNI-001, YAGNI-002) — these are advisory and listed in their own section; they are not corrected unless the user explicitly requests it

IDs are sequential within each category, starting at 001. Assign IDs in the order files are reviewed (alphabetically).

Category Assignment: When an issue fits multiple categories, use the first matching category from the checklist order in review-checklist.md.

Step 1: Identify Changes

Resolve project config: read CLAUDE.md's ## Project Discovery section for docs, ADR, and coding-standards directories plus test, lint, and build commands (look under ### Commands and Tests, not ### Frameworks and Tooling); fall back to project-discovery.md; fall back to Glob defaults (docs/, docs/adr/, docs/coding-standards/). Store found values for use in Steps 2, 5, and 6. Continue without any keys that remain unfound.

Detect review context

Check the git installed value from Project Context above. If it is empty, skip directly to Mode C below.

1. Run ${CLAUDE_SKILL_DIR}/scripts/detect-review-context.sh to detect the git environment. Capture the output — it contains key-value pairs describing git availability, branch name, default branch, and changed files.

Use the script output to determine the review mode. If the script reports git-available: false, skip to Mode C.

Mode A: Full git context — script reports git-available: true and changed-files-start block has content.

• Use the changed files list from the script output as the review scope
• Run git diff {default-branch}...HEAD to retrieve the full diff (fetch as a separate Bash command so large diffs are handled incrementally)
• Store the branch name from the script output for use in Step 3

Mode B: Git but no branch changes — script reports git-available: true but changed-files: none.

• Run git diff (unstaged) and git diff --cached (staged) to check for uncommitted work
• Run git status --short to identify modified, added, and untracked files
• If files are found, use those as the review scope (review files directly by reading them — no base-branch diff is available)
• Store the branch name from the script output for use in Step 3
• If no files found, fall through to Mode C

Mode C: No git / no changes found

• If the user provided file paths, glob patterns, or directories as arguments, use those to build the file list (expand with Glob)
• If no arguments provided, use Glob to discover source files in the current directory, excluding: node_modules/, .git/, vendor/, dist/, build/, __pycache__/, *.min.js, *.min.css, lock files
• Present the discovered files and ask the user to confirm the review scope
• Note: In Mode C, review files by reading them in full rather than comparing against a diff (no diff is available)

Bind $focus_areas. Read the user's free-form argument string from the invocation (everything after the optional $size positional). If non-empty, bind $focus_areas to that string verbatim. If empty, bind $focus_areas to the literal string none provided. This binding is consumed by every Step 3.5 agent prompt and by the Step 4 manual review.

Step 1.5: Load Branch Context

Load PR-level and branch-level context that the agents at Step 3.5 will need. Skip this step in Mode C (no git); for Mode A and Mode B, attempt the four sources below in order and combine what loads into a single $branch_context binding.

1. PR description (Mode A only). If gh is available, run gh pr view --json title,body,headRefName,baseRefName 2>/dev/null for the current branch and capture the body. If gh is not available or no PR exists for this branch, skip to source 2.
2. Local pr-body file. Look for a file named pr-body, PR_BODY.md, or .pr-body at the repo root. If present, read it.
3. Branch commit messages. Run git log {default-branch}..HEAD --pretty=format:%B (Mode A) or git log -n 20 --pretty=format:%B (Mode B) and capture the messages.
4. Implementation plan in the planning directory. Resolve the planning directory using this order:
   • Read CLAUDE.md's ## Project Discovery section for a plans: or planning: key naming the directory (e.g., plans: docs/plans/). Use that path if present.
   • If no key, Glob docs/plans/*/feature-implementation-plan.md and plans/*/feature-implementation-plan.md.
   • When the Glob returns multiple matches, pick the directory whose name matches the current branch name (treat - and _ as interchangeable). If no directory matches, log no planning artifact found for branch {branch} and skip this source.
   • Read the matched