code-review

---
name: code-review
description: Review a diff against what this team actually flags, not a generic checklist.
  Mines past PR review comments and discussions, the lessons library, and recent reflections
  to build the rubric, then reviews the change against it. Use when the user says "review
  this", "/code-review", before opening a PR, or after a push that wants a second pair of eyes.
---

# Code Review

Every team has a shortlist of things it keeps catching in review. It is never the generic
checklist - it is the four or five habits this particular codebase punishes. That list
already exists, scattered across old PR comments, and nobody has written it down.

This skill reads the history first, turns it into a rubric, and reviews against that. A
finding backed by "this team has asked for it eleven times" carries weight that a style
guide never will.

## Steps

1. **Scope the diff.** `git diff <base>...HEAD`. Note the files, the shape of the change
   (new surface, refactor, bug fix), and skip vendored or generated paths.

2. **Build the rubric from history**, cheapest source first:

   - `docs/lessons/` - lessons already promoted. Settled. Treat them as rules.
   - `reflections/` - what recent sessions got wrong. Not settled yet, still predictive.
   - Past review comments, the line-level ones and the conversation:

     ```bash
     # inline review comments, the ones attached to a line of code
     gh api "repos/{owner}/{repo}/pulls/comments?per_page=100&sort=created&direction=desc" \
       --jq '.[] | "\(.path): \(.body)"'

     # PR conversation, where the design arguments actually happen
     gh api "repos/{owner}/{repo}/issues/comments?per_page=100&sort=created&direction=desc" \
       --jq '.[] | .body'
     ```

     Cluster them by theme and count each theme. **A comment made once is somebody's
     preference. A comment made five times is a rule.** Keep the recurring ones and drop
     the one-offs - the point is to find what this team reliably cares about, not to
     relitigate every note anyone ever left.
   - `docs/AGENT_CHECKLIST.md` - the standing gates every change owes regardless.

3. **Cache the rubric.** Write the clustered result to `docs/lessons/review-rubric.md`: one
   line per theme, its count, and one real comment as the example. Later runs read the cache
   and only re-mine when it has gone stale. This is the step that matters - it turns the
   team's taste into a file in the repo instead of something only the senior reviewer holds.

4. **Review against the rubric.** Hand the diff and the rubric to `senior-swe-reviewer` for
   correctness and to `pm-reviewer` for scope and user impact. Give them the diff itself,
   never a summary of it.

5. **Rank and report.** Most severe first. Each finding names the file and line, what breaks,
   and the concrete input or state that triggers it. Drop anything you cannot state that
   way - an unfalsifiable finding costs the author more time than it saves.

6. **Close the loop.** If a finding is not in `docs/lessons/` and this is not the first time
   it has come up, say so and name it as a `promote-lessons` candidate. A review that fixes
   only today's diff is worth less than one that retires the whole class of mistake.

## Rule

Findings cite evidence. "Flagged in 6 previous PRs" or "docs/lessons/async.md says X" beats
"this looks wrong". And if the rubric has nothing to say about a line, that is a signal the
line is fine - not an invitation to invent a rule on the spot.