# The review table

> Read and write a UI review as Before | After | Why rows, scan code against the checklist, and scope a review to what a change actually broke.

Module: Directing your agent · Level: beginner · 8 min · https://school.agents.org.in/foundations/agents/the-review-table

Here is a review you have probably received: "The animation could be smoother, the transition is a bit long, consider a different easing curve."

You read it twice. You still don't know what to type.

  **Prose review (avoid):**

The modal could be smoother. The transition is a bit too long and the scale starts too small. Consider a different easing.

  **Table review (do this):**

`transition: transform 0.6s ease` → `0.25s cubic-bezier(0.25, 1, 0.5, 1)`. Under 300ms feels responsive.<br />`scale(0)` → `scale(0.95)`. Nothing real appears from nothing.

## Three columns, every time

The skill makes every UI review a table with three columns. Emil Kowalski calls this format non-negotiable, because it forces concrete diffs instead of advice.

| Column | What goes in it |
|---|---|
| **Before** | The real line from your code, quoted. Never paraphrased. |
| **After** | The replacement. Same job, better feel. |
| **Why** | One short sentence, ending with the skill node that goes deeper. |

**If you can't write the Why in one sentence, you're probably reaching.** Drop the row.

  **Step: One issue per row.** Three problems in one line of CSS get three rows.

  **Step: Order by impact.** The thing that breaks keyboard users goes above the hairline.

  **Step: Nothing actionable in the prose.** Prose around the table is context only: "Three issues in the modal entrance:".

  **Step: Nothing to fix is a valid review.** "Looks good, nothing to change" beats invented nitpicks.

## The checklist: a scan before taste

Before anyone argues about taste, there is a floor. The review checklist (Thirty-nine common UI mistakes, each with a quick way to spot it and a fix, scanned before anyone argues about taste. A floor, not a ceiling) is thirty-nine common mistakes, each with a quick way to find it and a fix: `transition: all`, `scale(0)`, `ease-in` on UI, a removed focus ring, `z-index: 9999`, `100vh` on phones, placeholder names like "John Doe".

Edit the CSS below. Each rule is one of those quick checks; fix a line and its row disappears.

*[Interactive demo: A slice of the checklist, running live. The table is the review.]*

Two warnings come with it. The checklist is a **floor, not a ceiling**: the best reviews catch what isn't on it. And it is a flag, not a law: a 500ms animation is fine on a rare celebration moment. Read the context before writing the row.

**Ask for a proper review (paste into your agent):**

```text
Review src/Modal.tsx as a Before | After | Why table.
Scan it against the review checklist first.
Quote my real lines in Before. End each Why with the node that owns it.
Three to five rows, most important first. If nothing fails, say so.
```

## Reviewing a change, not a codebase

Now picture a pull request: a set of changes you want merged. The author is asking one question: *did I make this worse?*

A review that answers "here is everything wrong with this codebase" buries the two lines that matter under thirty that don't. A change-scoped review (A review of what one change (a branch or pull request) did, not of the whole codebase. Each finding is marked Introduced, Regression or Pre-existing by what caused it) answers the real question.

*[Interactive demo: A branch review: the scope first, then the removed lines, then a Status on every row.]*

### Resolve the scope

With no target named, the agent reviews the commits your branch has that main doesn't, **plus** anything uncommitted, and says how many of each. With nothing changed, it asks what to review instead of inventing a scope.

### Follow the blast radius

A changed file is evidence, not the subject. Its blast radius (Every screen a changed file shows up in. Change a shared token or component, and every place that uses it is part of the review) is every screen that renders it. Change a token, and every component using that token is in scope.

### Read the removed side

**Regressions are invisible in the after state.** A `<button>` that became a styled `<div>` in a "move to the new design system" refactor looks identical. Only the deleted lines show it.

So the agent searches the removed lines for signals that left: `aria-*`, `<label>`, `:focus-visible`, `prefers-reduced-motion`, a token swapped for a literal. Each is a lead, not a finding. `aria-label` replaced by `aria-labelledby` on visible text is fine; read the hunk before deciding.

*(The button-to-div swap is the regression people miss most.)*

### Status by cause

Every finding gets a status, decided by what caused it, not by where it sits:

| Status | Means | Blocks the merge? |
|---|---|---|
| Introduced | the change created it | yes |
| Regression | the change weakened something that worked | yes |
| Pre-existing | it was already there, not made worse | no |

An untouched screen whose contrast now fails because a shared token changed is **Introduced**. A bug three lines from the edit that the edit didn't touch is **Pre-existing**. List at most three of those, plainly marked as not this change's job. Thirty is another review.

**Review my branch (paste into your agent):**

```text
Review this branch as a change-scoped review.
Scope: commits ahead of main plus uncommitted files; tell me how many.
Read the removed lines for lost signals.
Columns: Severity | Status | Location | Before | After | Why.
Introduced and Regression only, then at most three Pre-existing.
```

**Check yourself:** A pull request changes one shared color token. An untouched settings screen now fails contrast. What status does that finding get?

- [ ] Pre-existing, because the settings file wasn't edited
- [x] Introduced, because the change caused it
- [ ] Regression, but only if the file is in the diff
- [ ] None: untouched files are out of scope

*Why:* Status follows cause, not location. The token change caused the failure, so it is Introduced, even though the settings file never appears in the diff.

## In the skill

- https://school.agents.org.in/skill/meta/review-format.md
- https://school.agents.org.in/skill/meta/review-checklist.md
- https://school.agents.org.in/skill/meta/change-scoped-review.md