Better with Kent · draft

Stop Reviewing Diffs.
Start Reviewing Systems.

Review primitives and architecture — not line-by-line code.

composes
extends
adds

Hook

3,848 lines added

I didn't read most of them.

kody PR #662 · MCP client support · I reviewed the system

The problem

Diffs show what changed — not where

  • Syntax and style opinions don't scale
  • Agents ship more code, faster — review surface explodes
  • Reviewers need system altitude, not grep skills

Inspiration

Steve changed how he reviews PRs

  • Steve (Builder.io) — visual recap skill for code review
  • High-altitude system summary right in the PR
  • Same thesis: review systems, not diffs

Why I rolled my own

No account. No deploy. No inference token.

  • Steve's skill needs signup or self-host + an inference token
  • My agent is already on the PR — it writes the recap itself
  • His before/after screenshots and mini-demos are genuinely cool
  • Cursor already gives me screenshots and video — yours may differ

Ported the core idea to kcd-skills — GitHub renders it, no extra service

Visual recap

System recap block in the PR

primitives.yaml → classify → system map → invariants

GitHub renders mermaid in the description — no extra service

Classification

Three impact levels

Level Meaning Review posture
composes Uses primitives as-is Low risk — wiring and call sites
extends Changes behavior or contract Medium — read the diff for that primitive
adds New primitive in the map High — system design review

Source of truth

Your primitives map

  • Machine-readable map: docs/contributing/architecture/primitives.yaml
  • Every non-trivial PR classifies against it
  • New primitive? Update the map in the same PR

Demo setup

Two PRs — same domain, different risk

PR #662 adds MCP client servers — new primitive
PR #686 composes MCP onboarding — wiring only

Demo · high risk

PR #662 — live recap

github.com/kentcdodds/kody/pull/662

Expand the system recap block — table, system map, sequence diagram, invariants

PR #662

Adds mcp-client-servers

Primitive Impact What changed
mcp-client-servers adds Hub DO, OAuth, settings, synthesized domains
capability-registry extends Runtime merge synthesizes mcp:<server>
d1-app-db extends New mcp_server_settings table
account-export composes New table in export/deletion targets

PR #662

System map

flowchart LR
  appUi["app-ui"] --> mcpClient["mcp-client-servers\nNEW"]
  capReg["capability-registry"] --> mcpClient
  capExec["capabilities-execute"] --> mcpClient
  mcpClient --> d1["d1-app-db"]

Red node on GitHub = new primitive

PR #662

What you're actually reviewing

  • per-user-isolation — hub DO scoped by userId
  • compact-mcp-surface — no new top-level MCP tools
  • no-secrets-in-chat — OAuth tokens stay in DO storage

Architecture questions — not "is this idiomatic TypeScript?"

Demo · low risk

PR #686 — live recap

github.com/kentcdodds/kody/pull/686

Same MCP topic — totally different review posture

PR #686

Composes existing primitives

Primitive Impact What changed
app-ui composes /onboarding, home/account banners
app-sessions composes Auth-gated onboarding handlers
mcp-oauth composes listUserGrants for first-connection check
mcp-server composes Displays request-scoped /mcp URL

PR #686

System map

flowchart LR
  appUi["app-ui"] -->|"banner + /onboarding"| sessions["app-sessions"]
  appUi -->|"needsOnboarding"| oauth["mcp-oauth"]
  appUi -->|"shows /mcp URL"| mcp["mcp-server"]

All green on GitHub — wiring only, no contract changes

Contrast

Same domain · different review

  • #662 — did we add a primitive correctly?
  • #686 — did we wire existing pieces safely?
  • The recap tells you which question to ask first

Primitives episode

Design the playground first

  • Design Primitives Agents Can Actually Use — create, combine, delete, expand
  • I built my own OpenClaw — Kody's primitive stack
  • Good primitives → most PRs are composes

Install

Get the visual-recap skill

github.com/kentcdodds/kcd-skills

  • Star the repo — skills install into Cursor / agents
  • Plan mode before you implement
  • Recap mode when the PR ships

Vision

PRs become living architecture docs

  • Reviewers focus on system shape and invariants
  • Diffs are for the primitives you actually changed
  • Future tools can ingest the same recap block via GitHub API

Homework

Try it on your next PR

Map your primitives.
Run visual recap before you open the diff.

Lowest-risk outcome: the plan requires no primitive change

Better with Kent

Review systems — not syntax

  • Classify every change: composes · extends · adds
  • Install visual-recap from kcd-skills

Subscribe · like · comment · share