Review gallery
Visual work is judged by looking. Describing it in chat, or handing over a folder of files, makes the user do the sorting. This skill turns a round of visual work into one local page they read top to bottom, mark, comment on and paste back as a numbered list, and turns that list into the next round of work.
The loop
- Capture the real thing at the sizes it is used (phone and desktop for UIs, in context and a 100 % crop for
art). Anything that moves becomes a looping GIF, side by side BEFORE | AFTER for a change
(
scripts/make_gif.py). Details:references/capture.md. - Write a spec (
review.json): title, a short intro, and one item per request / screen / asset, each with the user's number, their words quoted, plain "what I did" lines, and before / after / options media. Format and the three page shapes (inventory, fix round, options):references/spec.md. - Build and open:
python <skill>/scripts/build_review.py review.json --openwritesindex.html,img/thumbnails andmedia/next to the spec and opens the page in the user's browser. It exits 1 and lists any missing file; fix those first. Open the page the moment the round's work is complete, without waiting to be asked, and do not just print the path. - Tell them how to answer in one or two lines ("mark each item, press Copy feedback and paste it here"), then stop and let them review. Do not keep piling on work they have not seen. When parallel agents produce the round, build and open as soon as the last one reports; a late item can be added to the same page, their marks persist.
- Read the paste. Their text is a header line, then
N. [area] verdict — notelines (python <skill>/scripts/parse_feedback.pyturns it into JSON). Act on every line, in their order:Looks good: done; do not show it again.Needs work/More options/Fix this+ note: the note is the spec for the next attempt.Pick B: apply that option (the note may refine it).- Items they left unmarked were accepted. A pick item with no pick keeps the current version. Save durable preferences you learn (taste, things they dislike) to memory if the project keeps one.
- Next round: a new folder and page (
...-round2,...-round3) with only the items still open, the same numbers, and before = the last round's after.
Language
The page speaks the user's language. Write titles, requests and "what I did" lines in that language; the buttons
follow: en, ko, ja and zh (Simplified Chinese) are built in (scripts/locales.py), chosen by "lang" in the spec or, when it is left out,
by the language the spec is written in. For any other language pass the translated words in "labels";
parse_feedback.py --spec review.json then understands them.
Making the page worth reading
- Their numbers and their words. Quote each request so they can see it was answered as asked; keep their numbering across rounds.
- "What I did" in plain sentences: no file names, CSS terms or internal ids.
- Change only what was asked, and show it; an extra redesign goes in a separate option they can decline.
- Options: start each caption with its label (
A ...,B ...) so each picture gets its own pick button, show each option in real context plus one comparison sheet, keepKeep currentas a choice, and leave the shipped version unchanged until they pick. - Same capture for before and after (size, state, timing), plus desktop when the product has a desktop layout. In the viewer the arrow keys step through the pictures, so a matching pair can be flipped in place.
- GIFs for motion, stills for detail. Keep GIFs under about 8 MB.
Where it lives
- Put the page in the project's scratch or output area (for example
output/<round>-<date>/index.html), never in shipped source. - It is a local file with no network requests. Do not upload unreleased art or private screens to an external service to show it. If the user explicitly wants a shareable link, ask first.
- Parallel agents: each writes
notes.json(items in the spec format) in its own folder; merge them into one spec (see the end ofreferences/spec.md).
Files
| path | what |
|---|---|
scripts/build_review.py | spec to self-contained index.html: thumbnails, GIF / video, viewer with arrow keys and full-size zoom, sticky bar coloured by state, light and dark, marks kept in localStorage, Copy feedback, phone-safe layout. Needs Pillow |
scripts/page_template.html | the page's HTML, CSS and JS (edit here to restyle) |
scripts/locales.py | UI words per language |
scripts/make_gif.py | one clip, or BEFORE | AFTER side by side, as a looping GIF via ffmpeg |
scripts/parse_feedback.py | pasted feedback text to JSON items (no, area, verdict, pick, ok, fix, memo) |
references/spec.md | spec format, the three page shapes, merging agents' notes |
references/capture.md | how to capture screens, motion and art so the page can be judged |
references/lessons.md | what makes a review round work, and mistakes to avoid |
assets/example-review.json | a small spec showing every mode (copy it to start) |