review-pr · v1.0.0 · 2026-05-23 · sha256 abe9ca628dc6e265

review-pr v1.0.0A

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

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_3o25q3hnnc6k3uc6/abe9ca628dc6e2658d7388800821ec8aa98995e77281d295e1e369bdba1288bf.json

Then /plugin install review-pr@markdownregistry-3o25q3hnnc6k3uc6 in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: review-pr
description: >-
  Forensic, timeline-first pull request review that reconstructs the commit
  narrative before forming opinions. Use when the user says "review PR",
  "review this PR", "look at PR #N", "what happened in this PR", "why did
  they change X", "is this PR good", "review the diff", "check this branch",
  or any variation of wanting to understand, evaluate, or critique a pull
  request. Also use when asked to compare branches, analyze a contributor's
  changes, or assess whether changes were necessary.
license: MIT
metadata:
  author: jcottam
  version: "1.0.0"
---

# Review PR

A forensic, timeline-first approach to pull request review. The core insight: most bad reviews happen because the reviewer looks at the final diff in isolation and either misses the *why* behind changes or doesn't notice that intermediate churn netted to zero.

Reconstruct the narrative before forming opinions.

## Phase 1 — Orientation

Before reading any code, establish context.

### 1. Identify the hosting platform

Determine whether the repo uses GitHub, Azure DevOps, GitLab, or another host. Check git remotes:

```bash
git remote -v
```

Use the appropriate tooling:
- **GitHub** → resolve the PR and branches first:

```bash
gh pr view <N> --json baseRefName,headRefName,title,body,commits,files,statusCheckRollup,reviews
```

Use `baseRefName` as `<base-branch>` and `headRefName` as `<pr-branch>` for all subsequent commands. Do not guess the base branch.

- **Azure DevOps** → `az repos pr show --id <N>` or git log with branch inspection
- **GitLab** → `glab mr view <N>`
- **No CLI access** → fall back to `git log` on the branch

### 2. Read the PR description and commit messages

The PR description and commit messages are the contributor's stated intent — hypotheses you test against the code. Extract what the PR *claims*; do not treat claims as established fact until the net diff confirms them.

```bash
git log <base-branch>..<pr-branch> --reverse --format="%h %s%n%n%b"
```

Extract:
- What the PR claims to do (from title/description)
- How many commits are on the branch
- Whether the commit messages tell a story (tried X → fixed Y → finalized Z)

Form your own judgment of scope and risk **before** reading existing review comments or the user's stated opinion of the PR.

### 3. Check CI status

Before deep code review, inspect `statusCheckRollup` (GitHub) or equivalent CI status. If checks are failing, lead with that — a correct-looking diff that breaks the build is still a blocker.

### 4. Get the shape

```bash
git diff --stat <base-branch>...<pr-branch>
```

Note which files were touched and their rough magnitude. Flag anything unexpected:
- Utility/shared files touched by a "feature" PR
- Large line counts in files unrelated to the stated goal
- Test files present or absent

## Phase 2 — Timeline Reconstruction

This is the most valuable and most frequently skipped step.

### Walk commits in order

```bash
git log <base-branch>..<pr-branch> --reverse --oneline
```

For each commit, read the diff:

```bash
git show <sha> --stat
git show <sha> -- <file-of-interest>
```

Build a mental timeline:
- What was attempted first?
- Were there course corrections?
- Did the contributor fix their own mistakes within the branch?

### Identify reversals and churn

Look for patterns where commit N adds something and commit N+M removes it. This is normal healthy engineering — it means the contributor showed their work. Do not penalize them for it.

Flag it only if the churn is *not* cleaned up (i.e., intermediate complexity still exists in the final state).

### Compare net diff to merge base

The net diff is what actually lands on the target branch:

```bash
git diff <base-branch>...<pr-branch>
```

This is the ground truth. Individual commit diffs are useful for understanding *why*, but the net diff is what matters for the review verdict.

## Phase 3 — Categorize Changes

For each file touched in the net diff, classify the change:

| Category | Definition | Review posture |
|----------|-----------|----------------|
| **Primary** | Directly serves the PR's stated goal | Full scrutiny on correctness |
| **Supporting** | Necessary plumbing to enable primary changes | Check it's minimal, not over-engineered |
| **Opportunistic fix** | A real bug fix discovered along the way | Verify the bug was real; consider if it should be a separate PR |
| **Scope creep** | Unrelated improvement or refactor | Flag for discussion, don't block |
| **Churn** | Added and then reverted within the same PR | Confirm it truly nets to zero in the final diff |

When a change touches a **shared utility** (libraries, helpers, common components), apply extra scrutiny:
- Is the API change justified by more than one caller?
- Could the same result be achieved without modifying the shared surface?
- Are existing callers still correct?

## Phase 4 — Evaluate

Phase 4 is a draft assessment. Phase 5 may surface issues missed here; Phase 6 must reflect the updated picture.

### Review discipline

- **Test the PR's premise, don't validate it.** Check whether the net diff actually proves what the description claims before evaluating implementation details.
- **Seek disconfirming evidence.** Before approving, actively look for reasons the change could fail (missing edge cases, broken callers, rollback risk). If you find none, say so explicitly in Phase 6.
- **Confidence tags on findings.** Tag each substantive concern or approval reason as `[high confidence]`, `[moderate confidence]`, `[low confidence]`, or `[unknown]`. Example: "Race on concurrent writes [high confidence]" vs "May increase memory under load [moderate confidence — no benchmark run]."
- **Independent assessment.** Do not anchor on the PR author's framing, existing review comments, or the user's opinion until you have formed your own view from the diff and timeline.

### Primary changes

- Does the implementation match the stated intent?
- Are schemas, types, and contracts correct?
- Are edge cases handled?
- Is there test coverage for new behavior?

### Supporting changes

- Is this the minimum plumbing needed?
- Could the primary goal be achieved without this supporting change?
- Is the abstraction level appropriate (not over-engineered for a single use case)?

### Opportunistic fixes

- Was the original bug actually real? (Check git blame, production behavior, existing tests)
- Is the fix correct?
- Should it have been a separate PR for cleaner history?

### Scope creep

- Does it make the PR harder to review or revert?
- Is it entangled with the primary changes or cleanly separable?
- Note it but don't block unless it introduces risk.

### Churn

- Confirm the net diff shows zero residue from the intermediate state.
- If residue exists (dead parameters, unused imports, vestigial config), flag it.

## Phase 5 — Read the current state

For any file with significant changes, read the **current state** of the file (not just the diff). Diffs show what changed but hide whether the result is coherent. A clean diff can still produce incoherent code.

```bash
git show <pr-branch>:<path/to/file>
```

Check:
- Does the file read well as a whole?
- Are there leftover artifacts from the PR's development process?
- Is naming consistent with the rest of the codebase?

If Phase 5 reveals issues missed in Phase 4, Phase 6 must reflect the updated assessment.

## Phase 6 — Synthesize

### Tone

- Start with findings, not praise. No "great PR", "nice work", or "solid approach" openers.
- **Lead with the strongest concern** when the verdict is Request changes or Needs discussion. Steelman the contributor's approach first, then explain why it still fails the bar.
- **Separate code from contributor.** Critique the diff; do not attribute intent or competence.
- **Show reasoning for the verdict.** Cite specific files, lines, or commit SHAs — not vague impressions.

Produce a structured summary with these sections:

### 1. What the PR does
One to two sentences. What lands on the target branch?

### 2. Commit timeline
Ordered narrative of what happened on the branch. Include course corrections — they show the contributor's reasoning process.

### 3. Net impact
What actually changes after churn is removed. Distinguish "files touched" from "meaningful changes."

### 4. Change categories
Map each significant file change to its category (primary, supporting, opportunistic fix, scope creep, churn).

### 5. Concerns
Organized by severity. Tag blockers and substantive concerns with confidence levels; skip tags on pure style nits unless the nit reflects a real convention violation.

- **Correctness** — bugs, logic errors, missing edge cases
- **Scope** — changes that don't belong in this PR
- **Complexity** — over-engineering, unnecessary abstractions
- **Risk** — shared utility changes, migration concerns, rollback difficulty

### 6. Verdict
One of:
- **Approve** — changes are correct and well-scoped
- **Approve with nits** — minor suggestions that don't block merge
- **Request changes** — specific issues that need addressing before merge
- **Needs discussion** — architectural or scope questions that need team input

Always include reasoning for the verdict. Add these sub-bullets **proportionally**:

- **Steelman:** strongest case for merging as-is. Required for Request changes / Needs discussion. Optional one-liner for Approve with nits. Skip for trivial Approve (typo fixes, single-line changes).
- **Disconfirming evidence checked:** what you looked for and what you found. Required before any Approve verdict on non-trivial PRs; one sentence is enough for small changes.

## Principles

- **Never judge a diff without reading commit messages first.** The diff is the "what"; the message is the "why." You need both.
- **Always check the net diff, not just individual commits.** A 3-commit PR can have 500 lines of churn that nets to 50 lines of real change.
- **Distinguish "code in the PR" from "code landing on the target branch."** Follow-up fixups within the same branch are self-correcting, not problems.
- **Don't penalize showing work.** A commit history of "tried X → realized Y was better → switched to Y" is healthy engineering.
- **Flag shared-utility changes with extra scrutiny.** When a PR touches code that other features depend on, verify the change is justified and existing callers still work.
- **Assume good intent.** A wrong assumption that was later corrected is not incompetence — it's iterative development.
- **Separate the review from the reviewer.** Comment on the code, not the person.
- **Accuracy over agreeability.** A review that misses a real bug to avoid friction is a failed review. Deliver blockers plainly.