Code review exchange

Code Review Exchange

A review is only useful if the requester knows what was checked and the reviewer knows what to check. Freeform "can you look at this?" wastes both sides: the reviewer guesses at scope, the requester gets vague findings. This skill fixes the shape of both halves of the exchange.

Part 1 — Requesting a review

Produce a review request with these fields. Keep it tight; link to a handoff ([[agent-handoff]]) for deep context rather than duplicating it.

# Review request: <title>

## Scope
What to review and what to skip. "Review the new auth middleware; the existing user model
is out of scope."

## What changed
The diff or the exact files/commits to review (e.g. `git diff main`, or list paths).
Point at concrete changes — don't make the reviewer hunt.

## Intent
What this code is supposed to do, so the reviewer can judge correctness against intent,
not just style.

## Concerns / focus areas
Where you're unsure and most want eyes: "I'm not confident the token refresh handles
expiry races." Naming your own doubts gets the highest-value review.

## How to verify
The command(s) to run tests / reproduce behavior, so the reviewer can check, not just read.

Part 2 — Responding to a review

Review against intent and correctness first, style second. Report findings with explicit severity so the requester knows what's blocking versus optional.

Severity tags (required on every finding)

• [blocker] — must fix before merge. Bugs, security issues, data loss, broken behavior, missing critical tests.
• [major] — should fix; real problem but not merge-blocking on its own.
• [minor] — worth fixing: clarity, naming, small inefficiencies.
• [nit] — optional/stylistic; the requester can ignore freely.
• [question] — you need an answer to judge; not yet a finding.

Response format

# Review: <title>

## Verdict
One of: **Approve** / **Approve with comments** / **Request changes**.
State it first — the requester needs the bottom line up front.

## Findings
- `[blocker]` `path/file.ts:42` — <what's wrong> → <why it matters> → <suggested fix>.
- `[minor]` `path/other.ts:10` — <observation> → <suggestion>.
- `[question]` <what you need clarified>.

## What I verified
What you actually ran/checked (tests, manual repro) vs. what you only read. Be honest —
"read only, did not run tests" is a valid and important statement.

Reviewer discipline

• Every finding is actionable. State the problem, why it matters, and a concrete suggested direction. "This is bad" is not a review.
• Separate fact from preference. A [blocker] must be defensible as a real defect, not a style opinion. Tag opinions as [nit].
• Verify before asserting correctness. If you claim something is broken, show how it breaks. If you didn't run it, say so under "What I verified".
• Don't rewrite; recommend. Point to the fix; let the author apply it unless asked.

Part 3 — Receiving the review back

When you get findings, do not perform agreement or blindly apply suggestions. Evaluate each on technical merit, push back where a finding is wrong (with reasoning), and fix what's real. Address every [blocker] before merge. This mirrors [[receiving-code-review]]: verification and honest reasoning over reflexive compliance.