review-demo

Files (1)

• SKILL.md

SKILL.md (first lines)

# The demo check

The demo check decides whether a change needs a visual to be understood, and
delivers the right one when it does. Need comes first: would a reviewer
understand this change better by seeing it than by reading the diff? Modality
comes second: what is the cheapest visual that shows it? When no visual helps,
the check approves with a one-line note and attaches nothing.

This check holds the specialist stance: load `gc-toolkit.specialist-stance`
before you judge. This file is the visual lens. Whether the change is correct
is the `correctness` check's. Whether it is the right thing to ship, and
presents itself so the operator can decide, is the `pm` check's.

## What it reads

The anchor `<anchor_bead>` for what the change is for, then the diff at
`<reviewed_oid>`, in `<worktree>`: `git diff origin/<review_base>...HEAD`. The
draft PR, `<review_pr_url>`, and its preview where the rig's host deploys one.
The rig's guidance for this check, the reviewed commit's `docs/review-demo.md`,
which the review formula printed when the commit carries one: a rig names its
own visual surfaces there, and how to serve its app for a capture.

### When it runs

The check index places `demo` at the `open-as-draft` phase. Triage adds it before
the PR exists, the refinery opens the PR as a draft, and this check runs against
that draft. Where the rig's host deploys previews for pull requests, the draft
has one. The PR does not leave draft for human review until every pre-open and
open-as-draft check reads green, this one included.

## What it judges

### When triage adds it

Triage adds `demo` when the diff changes a surface a person looks at:

- a rendered page, component, board, or dashboard;
- a layout or styling change;
- a new or changed interactive flow;
- output a person reads in a terminal, such as a command's report;
- markdown the city posts on GitHub, such as a review comment or a PR body.

Logic, refactors, internal plumbing, tests, and docs read as text need no
visual, and triage adds nothing for them. That is the common case. The default
check set is the baseline, `correctness,triage`, so under it `demo` runs only on
a diff triage added it to.

### Decide need

Triage made a coarse call when it saw a surface in the diff. Yours is the fine
call: does seeing the change explain it better than reading it? A change to a
page's source that alters nothing the page renders, or a style change too small
to notice in a capture, needs no visual.

An explicit request for a visual, in the anchor or from a human on the PR,
settles need: a visual is needed.

When no visual helps, approve with a one-line note that says why, attach
nothing, and record `--visual none`.

### Pick the modality

When a visual helps, pick the cheapest one that conveys the change.

| Modality | What it shows | Pick it when |
|---|---|---|
| `repo-artifact` | a visual the repo already carries: a diagram, an image, or a clip in the diff or named by the change | a committed visual already shows what changed, so nothing needs capturing |
| `screenshot` | one rendered state of an app page, of a command's output in a terminal, or of markdown as GitHub renders it | a single frame carries the change: a page or a board, a report a command prints, a comment the city posts |
| `video` | motion, or a flow across several steps, with narration | the change happens over time: an interaction or a sequence |

Prefer the cheaper modality unless the change needs the richer one. A static
layout change is a screenshot, not a video. A new multi-step flow is a video.

### Produce it and deliver it

The pack's scripts named here sit in the directory `gc <binding> scripts-dir`
prints, where `<binding>` is the name in front of this skill's: `gc-toolkit` in
`gc-toolkit.review-demo`. A capture takes minutes, so it runs under the
claim-lease keepalive the review formula names, from the review workspace, the
directory that holds `<worktree>`, so the engine's working files stay out of
the reviewed tree.

Every modality reaches the PR the same way. `demo-deliver.sh --file <path>
--subject <anchor_bead>` resolves the PR from the anchor and attaches the file
to it in a comment, inline and uncommitted. It refuses a PR outside the rig's
origin and exits non-zero when it cannot attach. `doctor/check-demo-toolchain`
reports whether the `gh` it needs is present.

- `video`: record it in this review with `rig-demo-capture.sh --script demo.md
  --output demo.mp4 <app target>`, the rig-demo mol's capture core. Do not pour
  `mol-rig-demo` for it. A pour runs later in another session, so this verdict
  could not judge its clip, and by then the reviewed worktree is gone.
  The skill `gc-toolkit.gc-demo-script` writes the `demo:capture` script from
  the anchor and the diff. Keep the script and the clip in the review workspace.

  The app target is the draft's preview, `--base-url <url>`, where one
  deploys. Otherwise serve the reviewed worktree, so the clip shows the
  reviewed commit: `--serve-dir <worktree>/<dir>` for a static build, or
  `--serve "<command>" --cwd <worktree>` for a dev server. Exit 0 is a clip
  in which every step's proof held, exit 3 is a clip in which at least one
  step failed its proof, and exit 1 is no clip. The last line names the clip
  and says whether it is narrated. Narration needs `OPENAI_API_KEY` in the
  session. Without it the clip is silent and captioned, and it still shows the
  change. `doctor/check-demo-toolchain` reports which parts of the capture
  toolchain resolve in this session.
- `repo-artifact`: list the visuals the reviewed commit already carries.

  ```bash
  "$(gc <binding> scripts-dir)/demo-repo-artifact.sh" candidates --base "origin/<review_base>" --oid "<reviewed_oid>" --anchor "<anchor_bead>" --repo "<worktree>"
  ```

  Each line gives a reason and a path. `changed` is a visual the diff adds or
  edits. `named` is one whose path appears in a line the diff adds or in the
  anchor. `near` is one in a directory close to a changed file's, nearest
  first. Exit 3 means the commit carries no such visual, so this modality does
  not fit. Open an image candidate at `<worktree>/<path>` before you pick it.
  A committed visual shows what its author recorded, not a run of the reviewed
  commit. Pick one that matches what the diff does, because one that shows a
  state the reviewed commit no longer produces would mislead the human.

From zookanalytics/gc-toolkit, MIT.

More from zookanalytics/gc-toolkit