review-pr

Review a PR

A reviewer finds what matters, says it, and stays silent elsewhere. Prove nothing; assert what you found.

Setup

1. Read CLAUDE.md, docs/engineering/ (principles.md, coding-standards.md, coding-agents.md, relevant specialized standards), and the docs/patterns/ files for the concerns this PR touches.
2. Read the linked issue (gh issue view <n>) and the full diff (gh pr diff <n>).
3. Check out the branch (gh pr checkout <n>), seed the worktree (copy .env if present, then uv venv --python 3.12 && make install), run make check. It ends by naming the docs-site pages this diff affects: open every page the PR left unchanged and confirm it is still true. No CI job does this; it is where stale prose is caught (#409 shipped five stale references past a ticked box).
4. Run uv run scripts/quality_delta.py and PR_BODY="$(gh pr view <n> --json body -q .body)" uv run scripts/concept_budget.py. Hold the PR to its own ## Expected delta and ## Concept budget declarations; unexplained overrun beyond roughly 2x is a finding. These numbers go in the return to the orchestrator, never in the PR.
5. Sibling comparison: for each changed or new module, pick 2-3 canonical siblings from uv run scripts/repomap.py (same package, same responsibility class), read them, and verify the PR's own ## Analog claim against the code.

Phases

Work in order. Correctness before craft: a wrong design makes naming irrelevant. Copy this checklist into your own response and check off each phase as you complete it:

Review progress:
- [ ] 1. Claims: what does this PR assert, and what must be true
- [ ] 2. Attack: go after those claims (references/attack.md)
- [ ] 3. Craft: patterns, naming, tests as spec (references/craft.md)
- [ ] 4. Scope: should this be two PRs
- [ ] 5. Verdict: post it (references/templates.md)
- [ ] 6. Harvest: usually nothing (references/craft.md)

phase	does	writes on the PR
1. Claims	Two lines: what this PR asserts, what must be true for it to hold.	nothing
2. Attack	Go after those claims: lifecycle, event ordering, concurrency, failure paths, states the code cannot express. Edge cases belong here, not later; mutation-test anything the PR calls covered. Depth: references/attack.md.	inline (Template A)
3. Craft	Does it read like its neighbors: docs/patterns/, naming, error text, comment slop, test names that state contracts, the PR body's own verbosity. Depth: references/craft.md.	inline (Template A)
4. Scope	Should this be two PRs? Is anything here not asked for?	one line, only if there is something
5. Verdict	Draft the rubric row per phase (Claims/Attack/Craft/Scope) and findings by class, format fixed in references/templates.md (Template B). Before posting, re-read each finding and ask whether it names a concrete consequence; downgrade it to NIT if it does not. Only then post.	300 words max, hard cap
6. Harvest	Optional, non-blocking, gated: see below. The default is to write nothing.	an issue carrying the entry text, never a commit and never on the PR