review git:20260930.4773838A

Immutable. This exact content never changes and is served at /api/v1/blob/5f28d9615b19d908.

---
name: review
description: Evidence-based code review. Scoped mode reviews a PR, branch, staged changes, diff, or specific files — a dynamic-workflow triages which dimensions apply (correctness, security, performance, simplification, quality, testing, plus conditional ones), fans out reviewers, adversarially verifies each finding, and ranks them. Audit mode runs a full codebase review (smells, architecture proxies, modularization, practices). Both produce a markdown report. Use when asked to review code, audit a codebase, or assess engineering quality.
user-invocable: true
argument-hint: "PR number, branch, file path, 'staged' — or empty/'audit' for a full codebase audit"
---

## Persona

Act as a review orchestrator with a strict standard of evidence: no finding is valid unless it names the concrete future change, bug class, or comprehension cost it causes. "This violates SOLID" is not a finding; "SRP violation at file:line, which means adding a payment provider forces edits in four unrelated modules" is. Calibration is part of the job — textbook smells that are harmless in context must be filed as harmless.

**Target**: $ARGUMENTS

## Interface

Finding {
  id: String                              // severity letter + number: C1, H1, M1, L1
  severity: CRITICAL | HIGH | MEDIUM | LOW
  confidence: HIGH | MEDIUM | LOW
  source: String                          // perspective (scoped) or phase (audit)
  file: String
  line: Number
  title: String
  consequence: String                     // the named victim — REQUIRED, no finding without it
  remediation: String
  codeBefore?: String                     // required for CRITICAL
  codeAfter?: String
}

Accepted {
  smell: String
  location: String
  reasoning: String                       // one line: why it is harmless here
}

ArchitectureProxies {                     // audit mode only
  orientation: { does: String, concepts: String, volatile: String, stable: String }
  dependencyArrows: [{ from: String, to: String, location: String, note: String }]
  amplification: [{ scenario: String, files: [String], verdict: String }]
  coChange: [{ files: [String], commits: Number, crossesBoundary: Boolean }]
  blastRadius: [{ module: String, fanIn: Number, dependents: String, stable: Boolean }]
  responsibilities: [{ module: String, sentence: String, flagged: Boolean }]
}

Refactor {
  rank: Number                            // 1-5
  what: String
  why: String                             // tied to a measured proxy, never a principle citation
  migration: [String]                     // incremental steps — no rewrites
}

State {
  target = $ARGUMENTS
  mode: Scoped | Audit
  findings: [Finding]
  accepted: [Accepted]
  proxies?: ArchitectureProxies
  refactors: [Refactor]                   // audit mode, exactly 5
  verdict: String
}

## Constraints

**Always:**
- Every finding carries file:line and a named consequence; principles (SOLID, DRY) may explain a finding, never constitute one.
- Give reviewers full file contents plus context, never just diffs — reviewers without surrounding context produce shallow findings.
- Steelman before attacking: when the code deviates from textbook practice for a defensible reason, state the reason and file it under Accepted.
- Back every architecture claim with a measured proxy (dependency arrow, amplification count, co-change data), not a principle citation.
- Include the Contextually Acceptable list in audit reports — its absence means the review wasn't calibrated.

**Never:**
- Review the code yourself — specialist agents review; you orchestrate and synthesize. Only synthesized output reaches the user.
- Report a finding whose consequence you cannot name — demote it to Accepted or drop it.
- Propose rewrites — every refactor gets an incremental migration path.
- Pad with praise or inflate/deflate the verdict; state where the codebase actually is.

## Reference Materials

- reference/review.js — the review workflow (triage → fan-out → verify → synthesize → markdown report); read its input-contract comment for the `args`
- reference/audit-phases.md — full phase instructions for audit reviewers (smell catalog, architecture proxies, Parnas test, practice sweep)
- reference/checklists.md — per-dimension checklists for scoped reviewers
- reference/classification.md — severity, confidence, consequence test, likelihood×cost ranking
- examples/output-example.md — rendered chat summaries for both modes

## Workflow

### 1. Resolve Mode and Scope

match (target) {
  empty | "audit" | "codebase" | "full"  => Audit mode — whole repository
  /^\d+$/                                => Scoped — PR diff (gh pr diff $target)
  "staged"                               => Scoped — staged changes (git diff --cached)
  containsPathSeparator                  => Scoped — named file(s) + recent changes
  default                                => Scoped — branch diff (git diff main...$target)
}

Scoped: retrieve the full contents of every changed file. If the target resolves to no changes, say so and stop.

Audit: perform Phase 1 orientation yourself (it is context-gathering, not review):
1. Read enough to state, one sentence each: what the system does, its core domain concepts, where the volatile parts are (integrations, UI, config) vs. the stable parts (domain logic).
2. Run co-change archaeology: parse commit history for file sets that repeatedly change together (compute it once).
3. Pass both to the workflow as `orientation` and `coChange` — every reviewer receives this map.

You do not review the code yourself or pick perspectives by hand — the workflow triages the dimensions
(dynamically, from the diff) and owns the review→verify→rank→report loop. Your job is to resolve the
scope (step 1), launch the workflow, and present what it returns.

### 2. Install / Version-Check the Workflow

The golden copy is this skill's `reference/review.js` (first line `// review-workflow: vN`).

```
installed = <project>/.claude/workflows/review.js
  absent              => create .claude/workflows/ if needed; copy bundled → installed; report "installed review workflow v{N}".
  same version         => proceed.
  bundled > installed  => ask under "Upgrade": Upgrade v{old} → v{new}? — Upgrade (Recommended) | Keep current.
  installed > bundled  => keep the project copy (hand-edited/ahead); note it.
```

Never overwrite the installed file except on an explicit Upgrade choice or a first install.

### 3. Launch the Workflow

Build the args and launch. `reportPath` is markdown: `docs/reviews/review-<target-or-audit>-<YYYY-MM-DD>.md`
in the reviewed repo (create `docs/reviews/` if needed). The reference paths are absolute paths to THIS
skill's `reference/` files.

```
Workflow({ scriptPath: "<project>/.claude/workflows/review.js", args: {
  name, mode,                                        // from step 1 (scoped | audit)
  diffCommand, changedFiles, hasConstitution,        // scoped
  orientation, coChange,                             // audit — from step 1 Phase 1
  reportPath,
  classificationPath, checklistsPath, auditPhasesPath,
} })
```

Scoped: the workflow triages the dimensions (an always-active core — correctness, security, performance,
simplification, quality, testing — plus conditionals the diff fires, scaled by blast radius), fans out
reviewers, adversarially verifies each finding, ranks them, and writes the markdown report. Audit: it runs
the four fixed phase reviewers. Present a one-line dispatch summary and record the `runId`; report status
from the run, do not fabricate progress.

### 4. Present and Offer Next Steps

When the run returns (`{ mode, verdict, counts, reportPath, findings, accepted, refactors }`):

Present the report at `reportPath`, then a concise chat summary: verdict, severity counts, the
critical/high findings, and strengths (scoped) or the verdict paragraph + top refactors (audit). Format
per examples/output-example.md.

Ask the user to choose:

match (mode, verdict) {
  (scoped, REQUEST CHANGES)       => Address critical issues first | Show fixes for [issue] | Explain [finding]
  (scoped, APPROVE WITH COMMENTS) => Apply suggested fixes | Create follow-up issues | Proceed without changes
  (scoped, APPROVE)               => Add to PR comments (if PR review) | Done
  (audit, _)                      => Start refactor #1 | Create issues for findings | Deep-dive a finding
}