Review cards and shots

How an agent shows the client a change as a card with a before and an after, reads the client's verdict, and works through what the client raises, with golo review and golo shot.

Every visible change reaches the client as a CARD in the portal, beside the live app. Everything the client raises (a bug, a request) is an ITEM of the same store. An agent acts on both with golo review only, never in a chat: nobody reads a chat. The client's side of it: Review cards.

A card for one change#

bunx golo shot orders --at HEAD --out .loco/shots/before.png   # before any edit: the app as committed
# edit the code, let the app reload
bunx golo shot orders --out .loco/shots/after.png              # after: the app as it runs now
git add src/collections/orders && git commit -m "orders: overdue badge" -- src/collections/orders
bunx golo review add --answers <item> --commit $(git rev-parse --short HEAD) \
  --title "Overdue orders show a red badge" \
  --what "In the Orders list:
- **the red badge** on orders past their due date" \
  --before .loco/shots/before.png --after .loco/shots/after.png

Shoot the before FIRST. --at HEAD serves the app at that commit, apart from the running one.
Commit BEFORE the card. An uncommitted change is lost to the next agent run.
One subject is one card. Other angles of it (phone and desktop, empty and full) are VIEWS of that card: --view "<label>" a.png, or golo review add-view <id> "<label>" a.png later.
A change always shows a before and an after. A lone image of a changed screen is no card.
Open every image before you add it: the change is the obvious thing in the frame.
--title is one line. --what is short markdown: one line of context, then bullets, the thing to judge in bold.
--answers <item> links the card to the item it fixes: one bug, one thread, one verdict.
A clip (mp4, webm) goes wherever an image goes, for anything that moves.
--draft makes work in progress the client can comment on but not judge. golo review ready <id> makes it a card.

add refuses a card that an open thread already covers (same record, same screen and topic, or a close title) and names it. Then supersede it, add a view to it, or say why it is new with --new --why "<reason>".

The client's answer#

verdict	what to do
`approved`	nothing. Only the client approves; never call a look validated yourself
`approved-with-fix`	the comment and rectangles are a small follow up: do it, then `golo review done <id> "<what changed>"`, or a new card if it needs the client's eyes
`rejected`	fix it, then a new card with `--supersedes <id>`
`archived`	set aside: nothing to do

A follow up SUPERSEDES the card. Superseding an approved card needs --keeps "<what stays>": an approval locks the look.
Rectangles are normalized to 0..1 on their view, with side on a before and after pair and t on a clip.
golo review inbox lists every unseen verdict and word of the client. golo review seen <id> marks it read once you acted on it.
golo review watch prints one line per verdict or message as it lands and never exits. Run it unfiltered.

What the client raises#

new ─dispatch→ open ─claim→ claimed ─a card answers it→ asks ─approved→ closed
 ├─ask→ question ─reply→ new         ├─fixed→ closed
 └─drop→ closed                      ├─blocked→ blocked (the client's move)
                                     └─wontfix→ closed

The state is derived from the thread, never stored. The client's move: asks, question, blocked. An agent's move: new, open, claimed.
One session at a time is the dispatcher (golo review dispatcher --as <name>). It routes new items to a topic, asks, or drops. It never fixes.
A worker takes the oldest open item of a topic with golo review next <topic>, or claims one with golo review claim <id>, before any edit. Only the claimant ends it.
A question goes ON the item: golo review ask <id> "<question>", then the agent ends its turn. The client's answer comes back to the same worker.
Acting verbs take --as <name>, or the LOCO_AGENT variable.
Topics are the app's: loco.config.ts review.topics, else ui, data, server.

golo shot#

bunx golo shot [route] [--size phone|desktop|WxH] [--at <rev>] [--video <s>] [--wait <selector>|idle|<ms>] [--out file]

The route goes without its leading slash: orders, orders/12, nothing for the home page.
--size phone is 390x844, desktop 1440x900 (the default). Shoot a before and its after at one size.
--wait idle for a page that loads its data after the first paint, --wait "#list" for one element.
--video 5 films 5 seconds (at most 30); --out then ends in .mp4 or .webm.
It prints the file, its size, the time, then one page: line per page error. A shot of a broken page is no card.
add reads the route and the viewport from the png. A down shot service is not the agent's to fix: it asks on its item and ends its turn.

The store#

The store lives in the app's workspace, apart from its data: .loco/review.db (_review_* tables) and its media in .loco/review/<id>/. Never read or write those tables yourself: golo review and the portal go through one module that checks every act and never rewrites a message. The full verb list: The golo cli.

This page as markdown