ninja nerdingReview the system, not the diff: Kent C. Dodds's visual recap
Review the system, not the diff: Kent C. Dodds's visual recap
Agents now write pull requests too big to read line by line. In an 8-minute episode, Kent C. Dodds shows his fix: the agent that did the work writes a short recap into the PR. Which building blocks it touched, whether it only uses them, changes one or adds a new one, and one diagram of what happens. You read that first, then only the code it points at.
Jump to composes, extends, adds, his two PRs, or try it with no install.
The video
8 minutes, posted Jul 28, 2026 on Kent's channel, episode 12 of Better with Kent. He talks over his own GitHub pull requests. The chapters are his. Every timestamp on this page opens the video at that moment.
- 0:00 Still reviewing git diffs?
- 0:25 Spectrum: not every line, not zero review
- 0:43 Review the system, not just the diff
- 0:51 Steve's visual recap (Builder.io)
- 1:17 Why I rolled my own
- 2:30 System recap + PR #662 (adds)
- 5:08 PR #686 (composes, low risk)
- 5:54 Primitives playground callback
- 6:57 Install kcd-skills visual-recap
- 7:35 Homework + close
Ten signals
The whole episode in ten boxes. Each links to the part of this page that explains it.
- 013:11
Agent pull requests are too big to read
His MCP change added 3,848 lines. He didn't read most of them. He reviewed what it did to the system instead.
How - 020:24
How much to read is a sliding scale
Not “read every line” and not “never look”. It depends on how much is riding on the project if you get it wrong.
How - 033:00
Your app is made of building blocks
He calls them primitives: the database, the sign-in, the website, the tool list. A recap says which blocks a change touched.
How - 042:50
Every change composes, extends or adds
Composes uses blocks as they are: low risk. Extends changes how one works: medium. Adds a new block: high.
How - 055:16
The label tells you what to ask first
An add asks “did we design this new piece right?” A compose asks “did we wire the old pieces safely?”
How - 061:41
The agent that did the work writes the recap
It already knows the change. It reads the diff, fills in a fixed block, and pastes it into the pull request.
How - 071:16
GitHub draws the pictures
The diagrams are Mermaid, plain text that GitHub turns into drawings. No account, no extra service, no extra AI bill.
How - 083:53
The flow shows how the agent read your ask
A step-by-step diagram of what happens for the user. If the steps look wrong, the agent misunderstood you.
How - 095:51
It only works with a good map
Write down your app's blocks first. Keep them few, and keep creating, merging, deleting and growing them on purpose.
How - 107:27
You can still read the code
The recap comes first, not instead. AI code reviewers still check the lines. You read the parts the recap points at.
How
Words on this page
27 terms, in plain words. Skip this if you already review pull requests.
- Agent
- An AI that works in steps on its own: reads files, runs commands, edits code. Claude Code, Codex and Cursor's agents are examples.
- Diff
- The list of every line a change added or removed, shown red and green. “Reviewing the diff” means reading those lines.
- Pull request (PR)
- A proposed change to the code, opened on GitHub so people can check it before it joins the main version.
- PR description
- The text at the top of a pull request that says what it does. The recap lives here.
- Review
- Checking a change before it goes in: is it right, is it safe, is it what we asked for?
- System
- Your whole app seen as connected parts, instead of as a pile of files.
- Primitive
- One building block of your app, the smallest piece that means something on its own: the database, sign-in, the website, the list of tools.
- Primitives map
- A short file that names every building block and which folders hold it. Kent's is called primitives.yaml.
- YAML
- A simple text format for lists and settings, using indents and dashes. Easy for people and programs to read.
- Composes
- The change only plugs existing blocks together. Low risk.
- Extends
- The change alters how an existing block behaves or what it accepts, such as a new database column. Medium risk.
- Adds
- The change creates a brand-new block. High risk: it needs a design review.
- Invariant
- A rule that must always stay true, whatever changes. Kent's include “one user never sees another user's data”.
- Recap block
- The fixed-shape section the agent writes into the PR description, between two hidden markers so it can be replaced later.
- Mermaid
- A way to write a diagram as plain text. GitHub turns it into a drawing on the page.
- Sequence diagram
- A diagram of who sends what to whom, in order: user, then website, then server, and back.
- Flowchart
- Boxes joined by arrows. In the July recaps it showed which blocks connect.
- Skill
- A folder with a markdown instruction file (SKILL.md) that teaches an agent one job. You can copy and edit it.
- Plan mode / recap mode
- Plan mode writes the block before any code exists, from the plan. Recap mode rewrites it from the finished change.
- Base and head
- Base is the version you started from (usually main). Head is your latest change. The diff is the gap between them.
- Migration
- A small script that changes the shape of the database, such as adding a table. Kent says these are worth reading.
- MCP
- Model Context Protocol, a standard way for AI apps to plug into tools and data. Both PRs in the video are about it.
- OAuth
- The “Sign in with…” handshake that lets one app use another for you without sharing your password.
- Kody
- Kent's own AI assistant, the project both PRs belong to.
- Cloud agent
- An agent that runs on someone else's computer, not yours. Kent's Cursor cloud agents can open his app, take screenshots and record video.
- GitHub Action
- A job GitHub runs for you automatically, for example on every new pull request.
- gh
- GitHub's command-line tool. The skill uses it to read and edit the PR description.
A visual recap, in plain terms
A short section the agent writes at the top of its pull request. It doesn't replace reading code; it tells you which code is worth reading. Kent's version is a free skill, but the idea works with any agent and no install.
Reviewing the diff
- 63 files, 3,848 green lines, in folder order.
- You rebuild the design in your head, file by file.
- Everything looks equally important.
- The risky part is somewhere in file 41.
Reviewing the system
- One line: adds a new building block, high risk.
- A table of the seven blocks it touched and how.
- One diagram of what happens for the user.
- Three rules to check. Then the diff, where it points.
How much to read · his sliding scale
“It's a spectrum based on the situation that you're in… how many people's lives are on the line if you mess up.” He thinks most of us are moving toward the right, from code toward the system. 0:24
Six uses, three basic and three advanced. The 3,848-line one is Kent's; the rest are ours, written the way he describes.
Basic
01A new page on your site
Solo builder, one agent
The agent adds a pricing page. Its recap says composes, low risk: website plus the existing database read. You skim the drawing, look at the screenshot and merge.
02Before the agent starts
Plan mode
You ask for the plan as a recap block first. It says “no change to any building block”. That's the lowest-risk answer there is, and you know it before any code is written.
03You don't read code at all
Non-engineer founder
You read only the one summary line. Composes: go ahead. Adds: you ask an engineer friend to look at that one new piece, not the whole 3,000 lines.
Advanced
04A 3,848-line agent PRhis example
Kent's PR #662
The recap says adds, high risk: a new block for outside tool servers. He reviews the design of that block and the three rules it touches, and lets AI reviewers handle the lines.
05Catch the agent misreading you
Change flow
The step-by-step diagram shows the agent sending people to a sign-in page you never asked for. You correct the plan in one comment instead of finding it in file 41.
06Keep the map honest
Team, every PR
Each new block updates the map in the same PR, and a check script fails if the map points at folders that no longer exist. The PRs become a running record of how the system grew.
Everything named
To start you need a coding agent and a GitHub repo. Everything else is optional.
Map to merge: who does what
The whole loop in ten steps, from the skill and the video. Filter by who does each step, click a step for the detail, or follow one of Kent's PRs through it. Steps 4, 7 and 10 use the scripts as they are today, three months after the video.
10 steps from map to merge. You do 3 of them.
Map to merge · click a step
Step 5 of 10 · Agent
Watch at 2:50Decide: composes, extends or adds
Label each block, then label the whole PR with the highest one.
Adds beats extends beats composes. The script can tell which blocks were touched; the agent still decides from the diff whether a block was only used (composes) or changed (extends). A new map entry is always adds.
Watch out: Any touched rule from the map gets called out, whatever the label.
Follow one PR through it
Kent wants Kody to connect to other people's MCP tool servers. 63 files, 3,848 lines added. Press Start and watch which step lights up.
01 · Map your building blocks You
Write primitives.yaml once: each block's id, group, one-line summary and folders. Add the rules that must always hold. This is the step everything else leans on. Kody's map has 58 blocks in 5 groups and 13 rules. Yours can start at ten. Your agent can draft it; you decide what counts as a block.
Watch out: Only update it when a block is added, removed or reshaped. It's a vocabulary, not a changelog.
02 · Hand the agent a task You
Ask for the work as usual. For anything non-trivial, ask for a plan-mode recap first. In plan mode the agent writes the block before coding, from its plan, marked “Mode: plan”. If the plan touches no block at all, it must say so. You can correct the design here, before 3,000 lines exist.
03 · The agent does the work and opens a PR Agent
Code, tests, screenshots. Kent's Cursor agents also attach video of the UI. Kent's point: this agent already understands the change, so it should write the recap. Steve's version runs a separate job on every PR instead.
04 · Sort the changed files into blocks Script
The classifier lists the changed files and matches each to a block by folder. It uses the longest matching folder from the map. Files that match no block come back as “unmatched”, which is itself a hint that the map is missing something. Added after the video.
node .agents/skills/visual-recap/scripts/classify-primitives.mjs --base main --head HEAD --json
05 · Decide: composes, extends or adds Agent
Label each block, then label the whole PR with the highest one. Adds beats extends beats composes. The script can tell which blocks were touched; the agent still decides from the diff whether a block was only used (composes) or changed (extends). A new map entry is always adds.
Watch out: Any touched rule from the map gets called out, whatever the label.
06 · Write the recap block Agent
Summary line with the label and risk, a table of blocks touched, a sequence diagram of the change, the rules touched. Written from git diff, not from memory: every claim has to be checkable against the change. Session context can explain why, never what. The block sits between two hidden markers, inside a fold-out.
Watch out: Leave a blank line after the summary and around every diagram, or GitHub won't draw it.
07 · Paste it into the PR Script
The upsert script swaps the old block for the new one, or adds it at the end. Nothing outside the markers changes. Run steps 4 to 7 again after every big push, so the recap always matches the latest change.
node .agents/skills/visual-recap/scripts/upsert-recap-block.mjs <pr-number> recap.md
Watch out: This script also runs a diagram checker that only exists in Kent's own repo. In yours it stops with an error until you or your agent remove that check.
08 · GitHub draws it GitHub
The Mermaid text becomes a diagram in the PR description. No service, no account, no extra AI cost. The recap stays with the PR forever, so merged PRs become a record of how the system changed.
09 · Review the system first You
Read the summary line and the table. Let the label pick your first question. Then open the diff only where it points. Composes: did we wire the old pieces safely? Extends: read the diff for that block. Adds: review the new block's design and its rules. AI reviewers keep checking the lines either way.
10 · If it adds, update the map Agent
A new block goes into primitives.yaml in the same PR, and the map check runs. The check fails on duplicate ids, missing summaries, summaries over 120 characters, and folders that don't exist. Kent's #662 updated the map; his #686 didn't need to.
node .agents/skills/visual-recap/scripts/check-primitives-map.mjs
PR #662 · adds
- Step 1: The map already exists. Kody's primitives.yaml names every block. There's nothing for outside MCP servers yet.
- Step 3: A Cursor agent builds it. Settings page, sign-in flow, a per-user hub, a new database table, tests, two demo videos.
- Step 5: Seven blocks touched. One brand new (mcp-client-servers), five changed, one only used. The highest wins: adds, high risk.
- Step 6: The block is written. Table of seven blocks, a map of how they connect, a 10-step sign-in flow, and three rules it touches.
- Step 9: Kent reviews the design. Not TypeScript style. Is each user's data kept apart? Did the tool list stay small? Do sign-in tokens stay out of chat?
- Step 10: The map grows. mcp-client-servers goes into primitives.yaml in the same PR. Merged Jul 8.
PR #686 · composes
- Step 2: The ask. New users who never connected an agent should see a clear first step.
- Step 3: The agent builds it. A “Connect your AI agent” banner, an /onboarding page, a short doc.
- Step 5: Four blocks, all only used. Website, sessions, MCP sign-in, MCP endpoint. Nothing changed inside any of them: composes, low risk.
- Step 6: The block is written. Four-row table, an all-green map, and a short flow: no grants means banner, then onboarding.
- Step 9: Kent checks the wiring. Do these blocks make sense for this task? The UI he already saw in Cursor's demo video. Easier than 18 files.
Composes, extends, adds
Every change gets one of three labels, and the whole PR takes the highest. The label decides your first question. Meanings from his slides; the “also” column is the skill today. 2:50
- 1composeslow risk
Uses blocks as they are. Wiring and call sites only.
AskDid we wire the existing pieces safely?
e.g.A banner that reads existing sign-in data (#686).
AlsoNothing extra.
- 2extendsmedium risk
Changes what a block does, accepts or returns. A new table or column counts.
AskRead the diff for that block. What depends on it?
e.g.#662's new database table in d1-app-db.
AlsoProve it works locally as a real test user. A preview deploy only if local can't.
- 3addshigh risk
Introduces a new block: a new entry in the map.
AskIs this new piece designed right? Should it exist?
e.g.mcp-client-servers, new in #662.
AlsoUpdate primitives.yaml, run the map check, and the same local proof.
Which one is my change? · three questions
Does the change create something that isn't on your map yet?
A new kind of thing: a new service, a new data store, a new permission system.
Three more rules
- Removing a block is as big as adding one. “We're removing a primitive, also big.” 2:58
- A touched rule (an invariant) is called out at every risk level, even on a compose.
- In plan mode, “this needs no change to any primitive” is the best answer, and it should be said out loud.
His two PRs: same topic, different review
63 files · +3,848 / −53 · merged Jul 8, 2026
System recap — adds a new primitive (high risk)
Classificationadds — introduces the mcp-client-servers primitive (per-user MCP client hub DO + D1 settings + synthesized kody.mcp domains). primitives.yaml is updated in this PR.
First questionDid we add a primitive correctly?
1 adds · 5 extends · 1 composes
Blocks touched · grouped as in his map · click one
Entry points
Assistant
Runtimes
Storage
- adds · new
- extends · changed
- composes · only used
- context · not touched
- On GitHub: red, amber, green, grey.
adds · new
mcp-client-servers
New: outside tool servers Kody can call
New primitive: a per-user hub, saved settings, the sign-in callback and a mcp_servers set of actions.
Connects to
mcp-client-servers (adds · new): New primitive: a per-user hub, saved settings, the sign-in callback and a mcp_servers set of actions.
capability-registry (extends · changed): Now also lists each connected server's tools.
capabilities-execute (extends · changed): New kody.mcp handle beside kody.remote, so code can call a server's tool.
app-ui (extends · changed): New MCP servers settings page and the sign-in return page.
package-runtime (extends · changed): Packages get the same kody.mcp handle.
d1-app-db (extends · changed): New mcp_server_settings table (migration 0053).
account-export (composes · only used): The new table is added to export and account deletion.
mcp-server (context · not touched): Not changed. Shown because it reads the capability list.
remote-connectors (context · not touched): Not changed. Shown because it sits next to the new block.
Change flow · his sequence diagram as rows
User (browser) · Worker (app routes) · McpClientHub (per user) · Remote MCP server. Solid arrow: a request. Dotted: the answer coming back.
- 01User (browser) → Worker (app routes)POST add { name, url }
- 02Worker (app routes) → McpClientHub (per user)addServer(callbackUrl)
- 03McpClientHub (per user) → Remote MCP serverconnect
- 04Remote MCP server ⇠ McpClientHub (per user)401 + OAuth metadata
- 05McpClientHub (per user) ⇠ User (browser)state authenticating + authUrl
- 06User (browser) → Remote MCP serverauthorize in browser
- 07Remote MCP server → Worker (app routes)GET …/oauth/callback?code&state
- 08Worker (app routes) → McpClientHub (per user)handleOAuthCallback(url) (session-cookie scoped)
- 09McpClientHub (per user) → Remote MCP servertoken exchange + connect + discover tools
- 10Worker (app routes) ⇠ User (browser)303 /account/mcp-servers?auth=success
Rules this PR touches
- per-user-isolationEach user's hub, settings and sign-in callback are looked up by that user only. No lookup crosses users.
- compact-mcp-surfaceNo new top-level MCP tools. Management goes in as actions behind search and execute.
- no-secrets-in-chatSign-in tokens stay in the hub's storage. Never in results, snapshots or the UI.
What the flow told him
“What was the agent thinking, and how did the agent interpret my prompt?” If the order of steps is wrong, you correct the agent before anyone reads code. 3:53
What he left to others
AI code reviewers check “the code is not doing some weird things”. Cursor's demo videos show the UI. The recap covers the part only he can judge: the system. 4:05
The visual-recap skill
One SKILL.md, one example block and three scripts. Free (MIT), from kcd-skills. The repo's README says most of its skills are tuned to Kent's own setup and invites you to fork them. 6:57
What and when
Writes and keeps one recap block in a PR description. Use it for any non-trivial change: when you plan one (plan mode), when you open or update a PR (recap mode), or when you ask for a “visual recap”, “visual plan”, “system review” or “PR recap”.
What you type
- “Write a visual recap for this PR.”
- “Visual plan first, before you code.”
- Or nothing: it triggers when the agent opens or updates a PR.
Install · one skill
npx skills add kentcdodds/kcd-skills --skill visual-recap
Or just print its instructions
npx kcd-skills@latest visual-recap
What it does, in order
- 1Reads the map, docs/contributing/architecture/primitives.yaml.
- 2Gets the facts from git: the diff between base and head, plus the list of changed files.
- 3Runs the classifier: changed files to blocks, by longest matching folder.
- 4Labels each block composes, extends or adds, and the PR with the highest.
- 5Writes the block in the shape of references/block-format.md: summary, table, sequence diagram, rules.
- 6Pastes it into the PR description with the upsert script, replacing any older block.
- 7If it added a block: updates primitives.yaml and runs the map check.
- 8Re-runs after every significant push.
Watch-outs · from reading the scripts
- The README says most kcd-skills are tuned to Kent's own setup. Fork and edit; it invites that.
- The scripts expect the map at docs/contributing/architecture/primitives.yaml, counted from the skill folder. Put it there or edit the path.
- The upsert script calls tools/check-mermaid-syntax.ts, which only Kody has. Remove that check or ask your agent to paste the block with gh pr edit.
- Semicolons break Mermaid sequence notes. The skill says to keep them out.
- The extends and adds rows mention a “control CLI” and a seeded user. Those are Kody's. Swap in however you test your app locally.
- Cloud agents sometimes can't edit PRs (“Resource not accessible by integration”). The script then prints the full new description to paste.
- A health check or a login test is not proof for extends or adds. Test the thing that changed.
Kent's example block · references/block-format.md, as shipped
<!-- system-recap:start -->
<details>
<summary>System recap: <b>composes existing primitives</b> (low risk)</summary>
**Mode:** recap · **Base:** `main` @ `abc1234` · **Head:** `def5678`
**Classification:** composes. No primitives added or changed.
### Primitives touched
| Primitive | Group | Impact |
| --------------------- | --------- | -------- |
| `mcp-server` | surfaces | composes |
| `capability-registry` | assistant | composes |
### Change flow
MCP search and execute read the capability registry.
```mermaid
sequenceDiagram
participant mcpServer as mcp-server
participant registry as capability-registry
mcpServer->>registry: search and execute read the registry
```
</details>
<!-- system-recap:end -->Changed since the video · July vs October 2026
He says in the video he'd already changed the system map after #662. 3:31 The skill has since dropped it from the example block in favour of one sequence diagram.
Your map of building blocks
“This only really works if you have a good set of primitives to start with.” 5:51 The areas and the four moves are from his earlier video, Your Coding Agent Needs Better Primitives.
What a primitive is
“The smallest unit of meaning that your system exposes.” Pieces you can put together without rebuilding how each one works. 1:32
Four moves, for the life of the project · 5:00
1Create
Add the block before the feature that needs it.
His example: Kent stopped a feature to have a separate agent build admin and user roles first.
2Combine
Two blocks doing nearly the same job become one.
His example: Three combo boxes at PayPal became one, which became his open-source Downshift.
3Delete
Remove what nobody uses. Fewer things the agent can misuse.
His example: Instagram began as a check-in app and cut everything but photos.
4Expand
Grow a flexible block instead of keeping a rigid one.
His example: Kody's email handler shrank to “publish an event”; packages grew to subscribe.
FakeNerd starter map · a small shop site
# docs/contributing/architecture/primitives.yaml
# A starter map (FakeNerd's example for a small shop site).
# Update only when a block is added, removed or reshaped.
version: 1
groups:
- id: surfaces
name: What people use
- id: data
name: Data and storage
- id: money
name: Payments
- id: auth
name: Accounts
primitives:
- id: site-ui
group: surfaces
name: Website pages and components
summary: Pages, layout and shared components.
code:
- app/
- components/
- id: products
group: data
name: Product catalogue
summary: Products, prices and stock.
code:
- lib/products/
- id: orders
group: data
name: Orders
summary: Carts, orders and line items.
code:
- lib/orders/
- id: checkout
group: money
name: Checkout and payments
summary: Payment provider calls and webhooks.
code:
- lib/payments/
- app/api/webhooks/
- id: accounts
group: auth
name: Accounts and sign-in
summary: Sign-up, login, sessions and roles.
code:
- lib/auth/
invariants:
- id: no-card-numbers
summary: Card details never touch our servers or logs.
- id: own-orders-only
summary: A customer can only read their own orders.Reading the file
- groups: the headings blocks sit under.
- primitives: one entry per block. The id is what recaps name.
- code: the folders that hold it. The classifier matches changed files by the longest folder.
- summary: one line, under 120 characters, or the check fails.
- invariants: the rules that must always hold.
Kent's real one for Kody is on GitHub: 58 blocks in 5 groups, 13 rules. Ours is a made-up shop, to copy and change.
Prompts
Kent gives two in his homework, both spoken, not typed on screen. The fill-ins below are ours, built from the skill.
This episode's homework: no install, just point your agent at the skill.
7:39Kent's homework · said, close wording
Read this skill: https://github.com/kentcdodds/kcd-skills/blob/main/skills/visual-recap/SKILL.md Hey, can you generate this for me?
The primitives video's homework: ask the agent about your building blocks.
14:46Kent's primitives question · said, close wording
What are the primitives that currently exist in the system, and what should we create, combine, delete or expand among these primitives? What's missing? What looks kind of the same? What needs a little bit more so that it can be more powerful?
FakeNerd fill-in · recap a finished change
Read Kent C. Dodds's visual-recap skill and its example block: https://github.com/kentcdodds/kcd-skills/blob/main/skills/visual-recap/SKILL.md https://github.com/kentcdodds/kcd-skills/blob/main/skills/visual-recap/references/block-format.md Write a system recap for [this branch / PR #___] against [main]. - Work only from git diff [main]...HEAD and --stat. Every claim must be checkable in the diff. - We [have / don't have] a primitives map. [If not: first list the 8 to 15 building blocks you see in this codebase, one line each, and use those.] - Label each block composes, extends or adds. Label the whole change with the highest. - Name any rule that must always hold that this change touches, such as [users only see their own data]. - One sequence diagram of what happens for the user, in Mermaid. - Then tell me in one sentence what I should read in the diff first, and why. Don't push or edit the PR. Show me the block.
FakeNerd fill-in · plan-mode recap before code
Before you write any code for [task], write a plan-mode system recap in the shape of: https://github.com/kentcdodds/kcd-skills/blob/main/skills/visual-recap/references/block-format.md Mode: plan. List the building blocks this plan will touch and label each composes, extends or adds. If the plan needs no change to any block, say so plainly. Include one sequence diagram of the intended flow. Stop after the recap and wait for me.
FakeNerd fill-in · draft your map
Look through this codebase and draft docs/contributing/architecture/primitives.yaml in the format of: https://github.com/kentcdodds/kody/blob/main/docs/contributing/architecture/primitives.yaml - 8 to 20 building blocks, grouped. Each: id, group, name, a one-line summary (under 120 characters), and the folders that hold it. - Prefer folders over file lists. Keep the map small. - Add 2 to 5 rules that must always stay true (invariants), one line each. - Then list anything that looks duplicated, unused or missing, and stop. I'll decide what to change.
“That's the beautiful thing about skills. It's just markdown files you can copy and paste.” Run the homework a few times, then keep the parts that work as your own skill. 7:50
Try it, smallest version first
Seven steps, in any coding agent: Claude Code, Codex, Cloudroom or bb. Steps 1 to 4 need no install and no map. The starter prompt is ours.
- 01
Pick one finished change
Any branch or PR your agent made this week, in any repo on GitHub. Bigger is better: ten files or more.
- 02
Do Kent's homework: no install
Paste the fill-in recap prompt below into Claude Code, Codex, Cloudroom or bb. It links the agent to the skill and asks for the block. No map yet? The prompt has the agent list your blocks first.
- 03
Read only the top
The summary line and the table. Decide your first question from the label before you open a single file.
- 04
Open the diff where it points
Extends: that block's files. Adds: the new block, its folder and any database migration. Composes: skim the flow diagram and the screenshot.
- 05
If it helped, write the map
Use the map prompt. Read what the agent proposes and cut it down. You decide what counts as a building block.
- 06
Install the skill and fix the two paths
Install it, put the map at the path it expects, and have your agent remove the Kody-only diagram check from the upsert script.
Install
npx skills add kentcdodds/kcd-skills --skill visual-recap
- 07
Next task: plan mode first
Ask for the plan-mode recap before any code. Correct the design there, then let it build and rewrite the recap from the diff.
FakeNerd starter · recap your last agent PR
Read Kent C. Dodds's visual-recap skill and its example block: https://github.com/kentcdodds/kcd-skills/blob/main/skills/visual-recap/SKILL.md https://github.com/kentcdodds/kcd-skills/blob/main/skills/visual-recap/references/block-format.md Write a system recap for [this branch / PR #___] against [main]. - Work only from git diff [main]...HEAD and --stat. Every claim must be checkable in the diff. - We [have / don't have] a primitives map. [If not: first list the 8 to 15 building blocks you see in this codebase, one line each, and use those.] - Label each block composes, extends or adds. Label the whole change with the highest. - Name any rule that must always hold that this change touches, such as [users only see their own data]. - One sequence diagram of what happens for the user, in Mermaid. - Then tell me in one sentence what I should read in the diff first, and why. Don't push or edit the PR. Show me the block.
Next to the others
Kent built his after trying Steve Sewell's. The table is our comparison, from both skills and both videos.
Steve's: his 5-minute demo and the skill on GitHub.
FakeNerd's take
The three words are the gift
Composes, extends, adds is useful even with no skill and no map. Ask it of every change, from an agent or a person, before you open a file.
The map is the real work
The recap is only as good as primitives.yaml. Writing that file teaches you your own app. Budget an afternoon, and expect to argue with your agent about what counts.
Read it, don't trust it blindly
The agent grading its own change can call an extend a compose. The rule that every claim must be checkable in the diff helps; a quick look at the files list still catches the rest.
Pair it with Steve's if you build UI
Kent skips UI because Cursor's videos cover it for him. If you don't get screenshots, his recap won't show you what the user sees. Steve's does.
Attribution
- Kent C. Dodds, “Stop Reviewing Diffs. Start Reviewing Systems.” Better with Kent, episode 12, Jul 28, 2026, with his slides. The idea, the three labels, the chapters and both PRs are his. Quotes come from the captions.
- The visual-recap skill and its example block are Kent's, MIT licensed. The page describes the skill as it is on Oct 25, 2026, and marks what changed since July. The watch-outs come from reading its scripts, not from Kent.
- The recap blocks, primitive ids, flows and rules are copied from PR #662 and PR #686 on GitHub, the pages he scrolls in the video. We didn't check them frame by frame against the video.
- The idea started with Steve Sewell (Builder.io), whose own /visual-recap Kent credits throughout. The primitives section draws on Kent's Jul 15 video.
- Disclosure: Kody is Kent's own project, and his PRs were built by Cursor cloud agents. The video doesn't say it's sponsored. Kent also co-teaches MEGA, a paid course; it isn't mentioned here.
- The plain names for each block, the six examples (except #662), the step notes and runs in the map, the picker, the starter map, every fill-in and starter, the Kent-vs-Steve table and the takes are FakeNerd's. Not sponsored by anyone on this page.
Example block also at references/block-format.md.