Communitygithub.com

demo-review-flow

Use when asked to add, change or redesign anything users see or operate in a UI - layout, where a control sits, an interaction, a keyboard shortcut, styling, an animation - including "small" tweaks and requests under deadline; when a session resumes UI work that has a review board; or when tests and code review pass but the user keeps finding the UI wrong.

What is demo-review-flow?

demo-review-flow is a Claude Code agent skill that use when asked to add, change or redesign anything users see or operate in a UI - layout, where a control sits, an interaction, a keyboard shortcut, styling, an animation - including "small" tweaks and requests under deadline; when a session resumes UI work that has a review board; or when tests and code review pass but the user keeps finding the UI wrong.

Works with✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/whats2000/demo-review-skills/tree/HEAD/skills/demo-review-flow

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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

  1. 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.
  2. 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.
  3. Build the demo as a feat() entry that really works: clicks, keys, motion incl. exits, light + dark, narrow width. → references/add-feature.md
  4. Record it: a changes row and features/<id> → review.
  5. 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.
  6. Pick up decisions at the start of every UI session and whenever the user says they reviewed: read features. approved → 7. changes → the note is the request → 3. User says they approved but the DB disagrees → the click did not save: say so, set it for them.
  7. Port at once — the user does not review plans; their bar is step 9. Set porting; brief per references/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.
  8. Ship only with live evidence (measurements, per-frame motion, both themes, the user's widths): shipped + a changes line + what to check.
  9. 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

ThoughtReality
"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.
  • shipped without live evidence; verified without 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.

Related Skills