Code Review

---
name: code-review
description: Review the diff since a fixed point on two axes, Standards (the AGENTS.md ladder, ADRs, design notes) and Spec (the originating GitHub issue). Use to review a branch, a PR, or work in progress.
---

Two parallel sub-agents review `git diff <fixed-point>...HEAD`, one per axis, so neither pollutes the other's context. This skill pins the inputs, dispatches both, and reports them side by side. Fit and comment debt are separate manual skills: `/fit-review`, `/comment-debt`.

## 1. Pin the fixed point

The user's ref if given, else `main`. Confirm `git rev-parse <ref>` resolves and the three-dot diff is non-empty before dispatching anything. Keep the diff command and `git log <ref>..HEAD --oneline` for every prompt.

## 2. Find the spec

In order: an issue number in the branch name, commit messages, or open PR body (`gh pr view --json body`), fetched with `gh issue view <n> --comments`; a path the user passed; a plan under `docs/design/draft/` matching the branch. Nothing found: ask once, and if there is no spec the Spec axis reports "no spec available" and is skipped.

## 3. Find the standards

For each changed file, the nearest `AGENTS.md` up the tree plus the root one, and any ADR in `docs/decisions/` or `design/` note the change touches. On top of those, the smell baseline below. Two rules bind the axis:

- **The repo overrides.** A documented standard wins; where it endorses something the baseline flags, suppress the smell.
- **Tooling is out of scope.** Anything `make lint`, `make typecheck`, `make deadcode-ts-check`, or `make license-check` would catch is not a finding.

## 4. Dispatch the two sub-agents

**Standards prompt:** the diff command, commit list, the standards files from step 3, the smell baseline pasted in full, and the brief: "Read every standards file. Report, per file or hunk, (a) every place the diff breaks a documented standard, citing file and rule; (b) every baseline smell, named, with the hunk quoted. Documented breaches may be hard violations; smells are always judgement calls. Under 400 words."

**Spec prompt:** the diff command, commit list, the fetched spec, and the brief: "Report (a) requirements missing or partial; (b) behaviour the spec did not ask for; (c) requirements that look implemented but wrong. Quote the spec line for each finding. Under 400 words."

## 5. Report

Print both under `## Standards` and `## Spec`, verbatim or lightly cleaned, then one line per axis: finding count and the worst issue. The axes stay separate because a change can pass any of them while failing another; never merge or rerank across them.

## Smell baseline

Fowler's code smells (_Refactoring_, ch. 3), applied on top of the documented standards. Each line reads *what it is* → *how to fix*.

- **Mysterious Name**: a name that does not reveal what the thing does or holds. → rename; if no honest name comes, the design is murky.
- **Duplicated Code**: the same logic shape in more than one hunk or file of the change. → extract the shared shape.
- **Feature Envy**: a function reaching into another type's data more than its own. → move it onto the data it envies.
- **Data Clumps**: the same few fields or params travelling together. → bundle them into one type.
- **Primitive Obsession**: a primitive or string standing in for a domain concept. → give the concept its own small type.
- **Repeated Switches**: the same `switch` or `if` cascade on the same type recurring across the change. → one map or polymorphism both sites share.
- **Shotgun Surgery**: one logical change forcing scattered edits across many files. → gather what changes together into one module.
- **Divergent Change**: one file edited for several unrelated reasons. → split so each module changes for one reason.
- **Speculative Generality**: abstraction, params, or hooks for needs the spec does not have. → delete; inline until a real need shows.
- **Message Chains**: long `a.b().c().d()` navigation the caller should not depend on. → hide the walk behind one method on the first object.
- **Middle Man**: a type or function that mostly delegates onward. → cut it, call the real target.