cycle-atlas/.agents/skills/hyperframes/references/review-loop.md

# The review loop — plan, sketch, build

How a `storyboard: yes` run earns fidelity one pass at a time: the plan is reviewed as text in chat, the layouts as stills on the board (`boards/storyboard.html`), and the finished piece as the assembled video. Collaborative mode waits at each checkpoint. Autonomous mode posts the same checkpoint summaries and continues, keeping exactly one question before render.

This is the shared process for any workflow that plans on a storyboard. The contracts it leans on live next door: interaction mode and gate types in `brief-contract.md`; the `STORYBOARD.md` format and the `outline → built → animated` statuses in `storyboard-format.md`. How to make the storyboard itself, and the page it is reviewed on, is `hyperframes-creative/references/storyboard-recipe.md`. A workflow's SKILL.md says **when** its steps hit each pass and supplies its **sketch stand-ins** (what the plain blocks represent); how the loop runs is defined here, once. The stage mechanics between the passes — audio, frames, assembly, transitions, captions, verify — live in `production-loop.md`; this file owns only the user-facing pauses.

## § 1 — The plan, in chat

Write the decisions and beat list into `STORYBOARD.md` following the recipe, and present the plan in chat as a proposal (shape: `hyperframes-creative/references/story-spine.md` § 3): open by echoing **"This video tells [audience] that [message]"**, then the frame table — one row per frame: frame · beat (type, duration) · on screen · why (its `narrativeRole`, traced to the message). Feedback arrives as a reply here, one revision loop.

In the same message ask two things: **(a)** approve or request changes, and **(b)** **sketches first** (recommended — a quick look at the layouts right after this approval) or skip sketches and build in one go. Iterate until approved: revise exactly the frames the reply names and re-present.

This is a **checkpoint gate** (`brief-contract.md` § 1). A run that starts autonomous normally has `storyboard: no` and does not enter this loop. If mode switches to autonomous mid-run, keep `STORYBOARD.md` current, post the same summary as a heads-up, and continue without waiting; the one kept question comes at § 4.

## § 2 — The sketch pass (collaborative, unless skipped)

The moment the plan is approved, sketch every frame yourself — no sub-agents, no waiting on other steps (sketches don't use timings), straight from the approved frame table.

A sketch is a **static frame, not an unstyled one**: the frame's layout at its key moment, posed in the composition with the full `frame.md` treatment (real fonts, real colors, the actual headline / stat / label text placed where it will live) as `storyboard-recipe.md` § 1 describes, using plain blocks only for panels, charts, diagrams, and media the workflow hasn't produced yet (the workflow says what its blocks stand in for). **No motion** — that arrives with the build pass; the layout, copy and brand treatment are already locked here.

Mount the posed frames in `index.html`, snapshot every still in one run into `boards/stills/` and write the board, `boards/storyboard.html` (`storyboard-recipe.md` § 1–2), then hand the user the board. Mark each frame `built` in `STORYBOARD.md` as its still lands. `snapshot` is the only CLI here — no `lint` / `check`, no rendering. When every frame is `built`, pause and ask one thing: does the board look right, or which frames change? This is a **checkpoint gate**; feedback arrives in chat: re-pose **only the frames named** and replace only their stills (`storyboard-recipe.md` § 1 step 4), rewrite the page, re-present, and loop until the layout is confirmed. Only then does the workflow's visual design get written onto the confirmed layouts.

A confirmed board is also a valid place to **stop**. When the user asked for a storyboard rather than a finished video — a plan to pitch, review, or hand off — `boards/storyboard.html` is the deliverable: confirm it, hand over the path, and go no further unless asked to build.

In autonomous mode, or when the user chose to skip sketches at § 1, skip this pass — frames go straight from `outline` to `animated` in the build.

## § 3 — Building on confirmed layouts

However the workflow builds — sub-agent workers per frame, or inline scene by scene — a confirmed sketch's **composition is settled**: placement, hierarchy, and copy were approved on the board, so building means dressing that layout (full design treatment, real assets, motion), never redrawing it. Workflows that dispatch workers put "this frame has a **confirmed sketch** (its posed composition, still in `boards/stills/`)" in the worker's context and carry the keep-the-layout rule in their worker prompt; a landed frame must still read as the approved wireframe, fully dressed.

Mark each frame `animated` as it lands. The build gate carries the loop's condition: in collaborative mode, the board was confirmed at § 2.

## § 4 — The final look

After the workflow's checks pass, use the **final composition preview**. In both modes open the Studio preview — on the user's own machine it opens in their browser by itself; on a remote machine or sandbox, say where it runs, since localhost may not reach them — hand the timeline URL and ask one thing: render now, or what changes? In autonomous mode this is the one question the mode keeps, and the preview still opens first: a user who asked only for a video has no other way to learn they can watch and edit it before the render. Render only on approval. Leave the preview running after the render, since the user may keep editing there, and say how to stop it: `npx hyperframes preview --stop`.

**After approval, offer the recipe — once.** An approved run is a proven bundle. At delivery, offer to freeze it: `media-use` → `scripts/recipe.mjs freeze --name <name>` (the workflow comes from BRIEF.md; pass `--workflow` only in a project without one) keeps the design spec, the storyboard skeleton (structure kept, content blanked), the brief skeleton, and the confirmed brief values, and the next run of this type starts from it (the intent layer checks for a matching recipe before its first question). When the freeze lands, teach the recall in the confirmation — "Saved as **<name>** (v<N>). Next time say _make another <name>_, or just _like last time_." — the name is something the system reminds the user of, never something they must remember. In autonomous mode don't ask — name the freeze command in the delivery note instead.