Demo review flow
Tests and code review prove the mechanism. They cannot tell you the menu is in the wrong place, the close flashes, or the icon sits 2 px low — only the user can. So a look-or-operate change is designed as a working demo the user approves per feature before any product code, and it is closed only when the user accepts it in the real app. A review board (an Artifact page with a shared database) tracks every feature through six statuses.
Project config: .claude/demo-board.md (board URL, reference apps per area, widths to check, live app + whether it holds real data, workspace-copy ports, gate commands, spec file). Missing → create the board first: references/board-setup.md.
Which path
- Changes how something looks, where it sits, or how it is operated → this flow. No exception for size or deadline.
- Restores behaviour the spec or an approved demo already defines (crash, wrong data, overflow, regression) → fix directly with TDD, no demo. Tell the user which path you judged it to be.
- A bug reported on a shipped board item → back to
porting, fix, live check,shipped. A fix that changes the look → new demo round.
The flow
- Reference first. For the area, look up the apps users already know (config lists them). Record where the control sits, each key, the motion incl. exits. Deviate only with a stated reason. A survey of simulated users picks between options; it never replaces the reference.
- Measure the real UI. Screenshot the shipped screens the change touches at the user's widths, read-only, and measure gutters, sizes, alignment. Design on that layout.
- Build the demo as a
feat()entry that really works: clicks, keys, motion incl. exits, light + dark, narrow width. →references/add-feature.md - Record it: a
changesrow andfeatures/<id>→review. - Hand over and stop. Link + what to look at. No product code for this item until it is
approved. "Go ahead unless you object" is not approval. If approval cannot come before a deadline, offer the user what already ships for it — never build ahead. - Pick up decisions at the start of every UI session and whenever the user says they reviewed: read
features.approved→ 7.changes→ thenoteis the request → 3. User says they approved but the DB disagrees → the click did not save: say so, set it for them. - Port at once — the user does not review plans; their bar is step 9. Set
porting; brief perreferences/port-brief.md. One porting agent per file area. Migrations run on a workspace copy; on live data only with explicit approval and a backup. - Ship only with live evidence (measurements, per-frame motion, both themes, the user's widths):
shipped+ achangesline + what to check. - Verified is the user's call — their Accept click, or them saying in chat that this item is accepted (then you set it). A vague "looks fine" → ask which items. Never on your own judgement.
Statuses, who sets them, the DB schema, writes → references/lifecycle.md. Hand-offs with brainstorming, writing-plans, subagent-driven-development, verification and branch finishing → references/superpowers-integration.md.
Live-check safety
On a live app with real data: browse read-only, click only exact labels, never delete/remove/edit there — any check that changes data runs on a workspace copy.
Rationalizations
| Thought | Reality |
|---|---|
| "It's small / easy to undo" | Size is not the test; look-or-operate is. Small UI changes are where placement goes wrong. |
| "Deadline tomorrow" | A demo round is minutes; a wrong placement shipped to the demo costs more. Keep the order, state the timeline. |
| "I'll show screenshots and proceed unless they object" | Silence is not approval, and a screenshot of a finished build is not a demo they can operate. |
| "The right place is obvious from first principles" | Name the reference app. "Where users look" is how the unfindable switch got shipped. |
| "Tests, review and build are green, so it's done" | That is porting complete. shipped needs live evidence; verified needs the user. |
| "'Looks fine I guess' means accepted" | Acceptance is per item. Ask which. |
| "They'll approve anyway; I'll build ahead for the deadline" | Unapproved code is the wasted kind. Point them to what ships today; port the minute they approve. |
| "I'll invent a clearer status" | Six statuses only; the page and the user read these. |
| "Port and demo together to save time" | Only approved items get product code. |
Red flags — stop
- Opening a product component before the demo shows the design.
- A design with no named reference app, or no measurement of the real UI.
shippedwithout live evidence;verifiedwithout the user's word on that item.- Clicking Delete/Remove/Save in an app that holds real data.
- Two porting agents on the same files; running a migration on live data.