1---
2name: ui-review-loop
3description: Run UI feedback rounds so each of the owner's notes lands in one pass. Covers intake of screenshot batches and streamed nits, routing each item to the agent that owns that code, sub-agent briefs that carry the owner's words, restating ambiguous specs before building, questions with a recommended answer, and the report that closes a round. Use this whenever the person you're building for sends UI feedback, screenshots, "img1… img6" lists or a stream of small notes; when briefing sub-agents on UI work; when deciding whether to ask or proceed on a UI taste call; and when reporting a UI round.
4---
5
6# UI review loop
7
8The owner's attention is the scarce resource. A good round lands every note
9once: nothing gets lost, nothing comes back, and nothing needs explaining twice.
10
11This skill covers running the round. `ux-testing` covers checking the work and
12what counts as evidence. `ui-craft` and `ux-flows` cover what good looks like.
13
14The examples come from Clover's apps: Snowbound, Clover Chat and the snow globe
15dashboard. The quotes are hers.
16
17## 1. Questions
18
19- **Ask decisions up front, as multiple choice.** Put the recommended option
20 first, with a tiny ASCII preview. Ask one decision per question, and tie each
21 to the rework it prevents. Use AskUserQuestion in Claude Code, or
22 `request_user_input_async` in Codex. Clover praised a round like this on
23 Clover Chat's backend plan: "the beautiful research round you just did
24 (amazing questions)".
25- **Put many open questions in one doc.** Give each just enough context and a
26 lean, so the owner can answer by number. Clover asked for exactly this:
27 "collect all the questions from everything into a markdown doc that explains
28 just enough context".
29- **Put decisions in questions, not commentary.** Owners skim progress notes
30 and answer questions: "i havent been reading messages but i saw the
31 questions".
32- **Re-send any pending question after the owner sends a message.** Queued
33 questions can be dismissed when they type: "i saw a question was queued but
34 it disappeared when i sent my message".
35- **Never park scope behind a question overnight.** Take the lean, proceed, and
36 list it as a taste call. On the dashboard, questions left the run "blocked"
37 overnight, and Clover's answer was to wire everything.
38- **Answer behaviour questions yourself first**, from the reference app
39 (`ux-flows`, section 1).
40
41## 2. Intake
42
43- **Number every item in the owner's message**, whether img1…imgN or bullets,
44 and map each one to an owner so nothing gets dropped. Owners stream notes as
45 they go ("sorry if im streaming a ton of things randomly as i go"), and the
46 loop is built for that.
47- **Small notes mid-round are normal.** "is it ok if i send a bunch of tiny
48 things as you go?" Yes. Route each note to the agent already in that code, or
49 fix it inline if it takes a minute.
50- **Restate anything spatial or numeric before building.**
51 - Order, as an ASCII row: `[notebook] ← → [tabs]`.
52 - Motion, as the numbers `ui-craft` lists.
53 - Both readings of an ambiguous noun: does "theme" mean the section colour or
54 the app's appearance?
55
56 When the owner gives one value for several surfaces, apply it to every surface
57 they named. Applying "half" to one surface instead of two cost a round, and a
58 misread order cost another.
59- **Build the literal surface the owner named.** Flag adjacent additions as
60 extras so they aren't mistaken for the ask. A recent-servers list once landed
61 on the welcome screen when Clover meant the ⌘P menu.
62- **Confirm a bug before sending an agent to fix it.** "no i just literally
63 typed ??? because i didnt know what to call that song."
64
65## 3. Briefing UI agents
66
67Use `references/agent-brief.md`. These parts made briefs land:
68
69- **The owner's words verbatim, then your reading of the job.** Paraphrase loses
70 what they cared about. The Live Share doc that got "this doc is peak" started
71 from Clover's long message, verbatim.
72- **What it looks like now.** List the current screen's defects and point to the
73 existing component to reuse. The agent then fixes the real screen, not an
74 imagined one, and doesn't invent a second chart style.
75- **Decisions already made.**
76- **Ownership.** Assign it by function, CSS section or data array, and list who
77 else edits what. One agent owns each UI surface; others hand off to it. Give
78 each agent its own checkout where possible (see `maintain-it`). If they share
79 one, they make small targeted edits and re-read on conflict.
80- **Hard rules:**
81 - the repo's own version-control and safety rules, from its AGENTS.md or
82 CLAUDE.md;
83 - no editing other layers;
84 - `ui-copy` before any string;
85 - never touching the owner's screen.
86- **A verify block** from `ux-testing`: driver, port, widths, themes, states,
87 and an acceptance probe per item that counts effects ("a remove sends exactly
88 one DELETE").
89- **Taste calls.** Pick one and list the alternative. Never decide taste
90 silently.
91- **The report shape:**
92 - per item: done, or skipped and why;
93 - a small figure;
94 - four to six screenshot paths;
95 - what couldn't be verified;
96 - any ask for another agent, written so the owner can forward it.
97- **Effort by judgement:** cheap for observation and research, medium for edits,
98 strongest for intricate work and design. Use whatever tiers your harness
99 offers, whether sub-agent types or reasoning effort.
100
101## 4. During the round
102
103- **When the owner approves a pattern on one page, apply it everywhere in the
104 same round**: "can you apply the redesign philosophy to the other pages too?"
105- **A nit names one instance; fix the whole class.** A hover rotation removed
106 from one icon was still on another, and lowercase labels came back after a
107 rename.
108- **On vague feedback about an approved design, make the smallest change that
109 keeps the approved shape.** If you misread it, revert: "wait for the wire
110 attaching i didnt mean like that … can you revert and apply the correct fix".
111- **Wiring real data never deletes display code** (see `ux-flows`, under Status).
112- **Review your agents' work before anything reaches the owner.**
113 - Spot-check their screenshots and send defects back.
114 - Smoke-test the merged build.
115 - Check that claimed verifications actually ran and that reported commits
116 exist.
117
118 Clover asked for exactly this on the dashboard: a substantial self-review
119 pass over everything the sub-agents built, before any handoff.
120- **Before touching anything near another agent's area, name the exact files
121 and layer.** Put cross-agent contracts in one file the owner can forward: "you
122 can write a file i can bump it with".
123
124## 5. The report
125
126Lead with what the owner will see, with images inline. The evidence rules are
127in `ux-testing`, section 8.
128
129```
130<one line: what changed, and where to see it: a URL that loads now, the build or commit>
131
132| # | Their item | Outcome |
133| 1 | <their words, short> | done (<screenshot>) / changed: <how it differs> / skipped: <why> / needs your eye |
134
135Taste calls: <choice made>. Alternative: <other>
136Yours to decide: 1. <decision>: <options and their consequences>
137Not verified: <what, and why>
138```
139
140- **Label status precisely:** queued, running, landed or installed. Clover's
141 questions show why: "are your four issue refs completed or just
142 acknowledged", and "btw your new build was not installed".
143- **Make background builds and releases visible**: "OH its building the release
144 i assumed it was done because i didnt see sub-agents lol."
145- **Owner-reserved decisions** (see `ux-flows`) go in the report as proposals,
146 never as shipped changes.