review

<!-- lifecycle-handoff-protocol:start --> Lifecycle handoff (standalone /review): When no parent orchestrator (one-shot, work) owns the pipeline, invoke /compound then /ship after review — do not end at the review summary. In pipeline mode, emit the compact ## Review Phase Complete marker only (see Step 3 pipeline detection). <!-- lifecycle-handoff-protocol:end -->

Dynamic-workflow alternative (opt-in). A Workflow-tool port of this skill's engine lives at [workflows/review.workflow.js](./workflows/review.workflow.js) — deterministic change-class fan-out, per-finding adversarial verification, and CONCUR-gated filing. Run it with Workflow({ scriptPath: "plugins/soleur/skills/review/workflows/review.workflow.js", args: "<PR#>" }). See [workflows/README.md](./workflows/README.md). The prose skill below stays the default; the two coexist during calibration.

Review Command

<command_purpose> Perform exhaustive code reviews using multi-agent analysis, ultra-thinking, and Git worktrees for deep local inspection. </command_purpose>

Introduction

<role>Senior Code Review Architect with expertise in security, performance, architecture, and quality assurance</role>

Prerequisites

<requirements>

• Git repository with GitHub CLI (gh) installed and authenticated
• Clean main/master branch
• Proper permissions to create worktrees and access the repository
• For document reviews: Path to a markdown file or document

</requirements>

Main Tasks

0. Setup

Load project conventions:

# Load project conventions
if [[ -f "CLAUDE.md" ]]; then
  cat CLAUDE.md
fi

Read CLAUDE.md if it exists - apply project conventions during review.

ASK WHAT A GATE NORMALISES AWAY BEFORE TRUSTING IT AS COVERAGE. And check every claim the diff's PROSE asserts about the system, not only its code — a correct fix with a false rationale teaches the next reader the thing a post-mortem exists to prevent. For each causal/universal sentence the diff ADDS, name the command that falsifies it and run it; the highest-yield targets are claims about a platform's execution model, a credential's liveness, and what a shared marker name buys. Why: #7516 shipped three: "each cloud-init runcmd - | item is its OWN shell" (shellify() concatenates them into ONE /bin/sh — stated in cloud-init.yml twice, nic-wait-gate.test.sh, and a post-mortem), "GHCR retained as break-glass" (AP-016 LAPSED — the PAT is revoked, so that leg 401s and the host's boot depends entirely on the new path), and "one query covers both hosts" (the two emitters reach Sentry and Better Stack respectively, so no query sees both). Each was refuted by one grep, and the first had already been used to report a defect catch whose mechanism was wrong. When a check compares two artifacts by normalising a dimension away, everything else that lived in that dimension becomes a precise, enumerable blind spot — and a PR whose subject is "make these two agree" is exactly the PR that writes into it. Name the normalisation, then ask what else those bytes encoded. Why: #7349 — the legal mirror-drift gate's normaliser collapses ](gdpr-policy.md) and ](/legal/gdpr-policy/) to one token, which is CORRECT for body equivalence and is what made it blind to link FORM; the PR whose headline was "we fixed a legal-doc 404" shipped three new ones onto the published surface (main had zero, HEAD had three) with every gate green. Corollary for the reviewer: a same-text edit applied to BOTH surfaces still fails a drift ratchet when the line was ALREADY drifting, and the ratchet's "port the enclosing passage instead" remedy is usually the substantive fix in disguise — pre-existing drift on a published surface generally means the public copy is the impoverished one. See knowledge-base/project/learnings/2026-08-12-every-blocking-finding-was-the-defect-class-the-pr-existed-to-close.md.

1. Determine Review Target & Setup (ALWAYS FIRST)

<review_target> #$ARGUMENTS </review_target>

<thinking> First, I need to determine the review target type and set up the code for analysis. </thinking>

Immediate Actions:

<task_list>

• [ ] Determine review type: PR number (numeric), GitHub URL, file path (.md), or empty (current branch)
• [ ] Check current git branch
• [ ] If ALREADY on the target branch (PR branch, requested branch name, or the branch already checked out for review) → proceed with analysis on current branch
• [ ] If DIFFERENT branch than the review target → offer to use worktree: "Use git-worktree skill for isolated Call skill: git-worktree with branch name
• [ ] Fetch PR metadata using gh pr view --json for title, body, files, linked issues
• [ ] Set up language-specific analysis tools
• [ ] Prepare security scanning environment
• [ ] Make sure we are on the branch we are reviewing. Use gh pr checkout to switch to the branch or manually checkout the branch.

Ensure that the code is ready for analysis (either in worktree or on current branch). ONLY then proceed to the next step.

</task_list>

Change Classification Gate

Before spawning review agents, classify the PR to avoid spawning agents whose expertise is irrelevant to the change.

1. Run git diff --name-only origin/main...HEAD | head -n 200 to get the list of changed files. Also capture status letters and line counts. Use git rev-parse --git-dir to resolve a writable tmp path that works in both regular checkouts and worktrees: in a worktree .git is a file (gitdir pointer), not a directory, so > .git/review-*.txt fails with Not a directory (os error 20). The resolver returns the worktree's actual gitdir (e.g., <bare>/worktrees/<name>/):

``bash REVIEW_TMP="$(git rev-parse --git-dir)" git diff --name-only origin/main...HEAD > "$REVIEW_TMP/review-changed.txt" git diff --name-status origin/main...HEAD > "$REVIEW_TMP/review-status.txt" git diff --numstat origin/main...HEAD > "$REVIEW_TMP/review-numstat.txt" ``

All downstream cat .git/review-.txt references in the predicates below must use "$REVIEW_TMP/review-.txt" instead. The pre-existing .git/... literals work in non-worktree checkouts but silently break in worktrees (where every PR review increasingly happens by default).

1. Check for override: scan $ARGUMENTS for "deep review" or "full review". Also run gh pr view --json body,title --jq '.body + " " + .title' and check for the same phrases. If override detected, skip classification and spawn all 8 agents.
2. Apply the four-class decision tree below in order; first match wins (override always trumps):

``text If $ARGUMENTS or PR body/title contains "deep review" / "full review": class = code (full override) → 8 agents Else if every changed file matches the lockfile glob OR (lockfile glob + optional knowledge-base/** or .md edit) AND zero source-code extensions are present: class = lockfile-only → 2 agents (git-history-analyzer + security-sentinel) Else if total_files > 0 AND total_lines > 0 AND (deleted_files 100 / total_files) >= 80 AND (deleted_lines * 100 / total_lines) >= 80 AND zero source-code extensions are present in the diff: class = deletion-dominated → 2 agents (git-history-analyzer + security-sentinel) Else if any changed file has a source-code extension: class = code → 8 agents Else: class = non-code → 4 agents ``

The "zero source-code extensions" guard on deletion-dominated closes a piggyback class: a 1000-line cleanup PR that adds a 50-line .ts file would otherwise route to 2 agents and bypass pattern-recognition / code-quality / architecture / data-integrity / performance / agent-native review on the new source file. Mirroring lockfile-only's $has_source empty requirement keeps the savings on legitimate orphan-cleanup PRs while routing any deletion-