Review Presentation

Review presentation format

Every draft review is handed to the maintainer in the same five slots, in this order. She reads dozens of these; the shape has to be identical every time so she never has to hunt for where the verdict went.

"when we do review the important pieces are: what problem, what was solution, did API update and how, any breaking considerations (API, visual, theme), review judgement — please present these to me in a consistent format we remember."

---

The template

**#<number> — <title>** (<author>, <bucket>)

**Problem.** What was broken or missing, and who hit it. The reason, not the diff.

**Solution.** What the PR does about it, and how. The mechanism, not the files.

**API.** none | added X | changed X | removed X — and whether it is public surface.

**Theme targets.** none | added X | changed X | removed X.

**Ossification.** *(only when either of the two above is not "none")* Which class
of problems does this serve, and who else is in that class?

**Breaking.** API: … · Visual: … · Theme: …

**Judgement: <verdict>** — one line of why.

---
<the review comment, quoted, ready to post>
---

<inlines, if any: `file:line` — ≤20 words each>

Rules

1. Two to four sentences per slot, at most. This is the summary, not the brief.

2. Never skip a slot. "No API change" and "nothing breaks" are answers and carry information. Silence does not — it is indistinguishable from not having checked.

3. New surface must earn itself. Props and theme targets both ossify the system: once shipped, a prop cannot quietly change meaning and a theme target cannot quietly move. The bar is a class of problems, not one problem — name another real member of the class or the answer is "not yet, wait for the second case". A single-case addition becomes the precedent cited for the next one, and the surface ratchets. Theme targets get their own slot precisely because they look free: no runtime behavior, so nobody counts them. See R1g-surface.

4. Breaking is three axes, always all three:

   axis	the question
   API	does an existing call site stop compiling, or change meaning?
   Visual	does anything already on screen move, resize, recolor?
   Theme	do existing theme targets, tokens and overrides still resolve?

   Visual and theme are the two a reviewer forgets to ask about, and they are exactly the ones that reach a user with no compiler saying anything.

5. The review text comes last, quoted — so the summary is judged before the wording.

6. Everything else comes after, or not at all. Evidence, what was run, what could not be verified: only if asked.

Why this order

Problem before solution, because a solution to the wrong problem is the expensive mistake and it should be visible in the first line. API, theme targets and breaking before judgement, because those are what usually move a verdict — and because new surface is the most expensive thing a PR can contain. Judgement before the review text, because if the verdict is wrong the wording does not matter.

Enforced by R16 in Critic Rules; the reviewer's own output block is in the Reviewer Brief.