Visual Review

Visual Review

A visual recap is the reverse of a plan: instead of describing a change you are about to make, it describes the change that was just made, at a higher altitude than line-by-line review. A reviewer scans the shape of the change — what UI moved, which contracts changed, where the risky lines live — before spending attention on literal lines. Diffs hide the shape of a change; the recap restores it.

Heavily inspired by BuilderIO's visual recap skill, adapted for this stack: the deliverable is a single self-contained HTML file built from assets/template.html, theme-aware in light and dark. Choose Artifact, BitPlan, an explicit last-resort host, or a local file from the delivery rules below.

When to use — and when to skip

Build a recap when a change is large, multi-file, UI-heavy, or touches schema, API contracts, permissions, or architecture — anywhere a reviewer benefits from a map before the territory. Skip it for small, single-file, or obvious diffs: a recap is review overhead, and a tiny change reviews faster as a plain diff (bunx critique --web --open). The recap complements the raw diff, it never replaces it — recap first for shape, raw diff for lines.

Quick terminal alternative

For a fast local look without generating a recap page, bunx critique --web --open renders the current diff in the browser with syntax highlighting and split view (requires Bun). Use bunx critique main HEAD --web --open for a PR-style branch comparison.

Scope: recap the whole work unit

When invoked mid-session after work has happened, the default scope is the whole work unit — original implementation, later bug fixes, tests, docs — not just the most recent edit. Use the diff plus conversation context to separate work-unit changes from unrelated pre-existing dirty state, and exclude the unrelated edits. If scope is genuinely ambiguous, state your assumption in one line rather than blocking on a question.

Resolve the diff mechanically before authoring anything:

# PR / branch (three-dot: changes since divergence, not target drift)
git diff --numstat main...HEAD
git diff --name-status main...HEAD
git diff main...HEAD -- <file>          # per-file, for key changes
# single commit:      git show <sha>
# working tree:       git diff HEAD
# GitHub PR:          gh pr diff <number>

The grounding rule (the most important rule)

Structured sections are true by construction only if derived from the actual changed lines. File paths, field names, types, methods, routes, line numbers, and before/after code MUST come mechanically from the real diff — never inferred, rounded, or invented. You write freely only in the prose narrative: the why, the decisions, the risk read. A confidently wrong recap is worse than no recap, because a reviewer who trusts the summary skips the very line the summary got wrong. When the diff doesn't contain a fact, leave it out; when you infer something (like a rendered layout you didn't screenshot), label it inferred in a caption.

Canonical skeleton

Copy assets/template.html (in this skill directory) and fill it top to bottom. Every section maps to a template block; delete sections that don't apply rather than padding them.

1. Header — title (≤70 chars), repo + ref, file/line stats as pills.
2. UI impact — before/after wireframes FIRST when the diff changes rendered UI. Read references/wireframe.md before authoring any wireframe. Delete the section for non-UI changes.
3. What changed and why — 1-3 paragraphs of narrative: the objective the diff served, key decisions visible in it, risks a reviewer should weigh. This is the only free prose. No boilerplate ("this recap is an aid…", "the reviewer should still…") — the header already carries provenance.
4. Contract changes — table.model cards for schema entities (per-field added/modified/removed/renamed badges; show the prior type with <span class="was">), endpoint cards for API changes (method, path, params as they exist AFTER the change; mark removed routes and breaking changes with the breaking badge plus a note-risk). Delete if no contracts moved.
5. File footprint — every changed file with its change badge and +/− stats, a short note only where the path doesn't explain itself.
6. Key changes — 3-8 tabs, one file per tab, each with a one-line tab-summary saying what the hunk changes and why, a split diff of the load-bearing hunks (≤~150 lines per tab; collapse boring stretches with a ln skip row), and a few annotation callouts anchored to line numbers. Brand-new files get an annotated walkthrough of the new code instead of a one-sided diff. Never leave a diff unlabeled.

Architecture or data-flow shifts get a diagram block (CSS panels from the template — diagram-panel / diagram-node / diagram-arrow, two panels for before/after) placed near the narrative. Use diagrams for structure and flow only; rendered UI always gets wireframes, never a diagram.

Write for the reviewer

Assume the reviewer has not memorized the issue, specification, or prior discussion. Keep the page compact, but give each fact enough context to stand on its own.

• Use plain language, one idea per sentence, active voice, and one stable term for each concept. Define an acronym or specialist term on first use.
• Name a specification before its identifier on first reference. Write “BRC-100 Wallet Interface,” not just “BRC-100.” Use the source's real title; if it has none, add a short description of its purpose. Link the title when a browsable source exists.
• Run Skill(core:humanize) on every heading, caption, annotation, and narrative paragraph before delivery. Preserve exact code names, evidence, uncertainty, and citations.

Turn every open decision into a questionnaire

If the review leaves a real choice for the human, give that choice an interactive question. Do not leave a decision buried in findings, risks, or open questions.

For each option, explain in 2–4 short sentences:

1. what changes if the reviewer chooses it;
2. what it enables;
3. its cost or risk; and
4. whether the choice is reversible and what follow-up it creates.

Give enough detail for the reviewer to predict the consequence without a follow-up. Stop before repeating the implementation. Use mutually exclusive controls for one-of-many choices and a notes field when caveats matter. Include a copy-response button that identifies the review and emits every answer. Adapt the component in ../visual-proposal/references/interactive-choices.md; omit its CEO-specific control when the review has no CEO call. Delete the questionnaire when the review contains no unresolved decisions.

Use the smallest useful visual

Add a diagram whenever it makes a relationship materially faster to understand: architecture, request or data flow, ownership, state transitions, dependency chains, or comparisons across three or more items. Use a flow for a sequence, a tree for hierarchy, a matrix for repeated comparisons, and paired panels for before/after state. Keep labels plain and trace every node and edge to the diff or a cited source. Use diagrams only for information they clarify. UI changes still use wireframes.

Budgets — substantial but lean

Lean is not thin. A recap that is one wireframe plus a sentence under-serves the reviewer as much as boilerplate over-serves them. Before authoring, make a surface inventory from the diff: changed routes, components, dialogs, role/permission variants, empty/error states, shared abstractions. Each meaningful item either gets represented or is intentionally omitted because it's tiny or not reviewer-visible.

• 3-8 key-change tabs. Fewer than 3 on a large change under-serves; more than 8 stops being a summary.
• ≤~150 diff lines per tab — summarize or skip-collapse the rest.
• Title ≤70 chars; narrative 1-3 paragraphs.
• A UI-heavy change needs more than one before/after pair: show the entry point, the changed interaction surface, and the resulting state. Permission changes need the role variants (what admins see vs. what viewers see).

Before/after is the headline

The recap's center of gravity is comparison:

• UI → paired wireframes in the ba-grid (labels live in the column headers, never inside the frame). The grid auto-stacks wide surfaces (browser, desktop) and puts narrow ones (mobile, popover, panel) side by side.
• Schema / API → a single card showing the AFTER shape with per-field change badges and was values usually beats two full side-by-side tables; use two cards only when the whole contract was replaced.
• Code → split diffs. Split is the default because before/after legibility is the point; use a unified single column only for a genuinely narrow hunk.
• Architecture → two diagram-panels, Before and After.

Deliverable and delivery

1. Copy the template to a working file — never edit the template in place: recaps/<slug>.html in the repo (gitignored or committed, follow the project's lead) or the session scratchpad for throwaway recaps.
2. Fill the sections per the skeleton above. All colors through the --wf-* tokens — never hard-code hex in content, or the dark theme breaks.
3. Deliver:
   • Claude Code Artifact tool → publish as an Artifact (it is default-private; strip the outer <!doctype>/<html>/<head>/<body> skeleton and keep the <style>, content, and <script> — the Artifact harness provides the document shell).
   • BitPlan → the normal durable or shareable path outside an Artifact. Load BitPlan's canonical skill: Skill(bitplan:bitplan) when installed as a plugin, or Skill(bitplan) for a standalone skill install. Prefer a BRC-100 wallet the user already has, explain the hosted-versus-on-chain choice, and get approval immediately before upload. Never request a mnemonic, private key, or wallet password.
   • No compatible wallet → explain that the planned 1Sat CLI fallback is not application-compatible yet; 1sat serve wallet is currently a wallet storage service, not BitPlan's BRC-100 endpoint. Do not pretend it works.
   • User explicitly declines a compatible wallet and the planned 1Sat CLI route → offer a local file first. Only if they explicitly want an unencrypted hosted capability link may you run bunx --bun postplan upload recaps/<slug>.html --description "<short label>". Explain that it is not wallet-encrypted BitPlan storage and ask immediately before upload.
   • Local → open recaps/<slug>.html (macOS) and report the absolute path. A path in the TUI is not a page.
4. Sanity-check the render before reporting it done: open it, look at it, in both themes if you changed any color usage. Overlapping labels or a crushed diff column means fixing the HTML, not shipping it.

The recap page is the deliverable — never paste the recap inline into chat as a wall of markdown; inline summaries are the thing a recap replaces. A 2-3 sentence handoff plus the link/path is the right chat footprint.

Security

• A recap is as sensitive as the source it summarizes. It can expose unreleased schema, internal endpoints, and architecture. Keep it local, default-private (Artifacts), or ask before any hosted upload of a private repo. Never publish a recap of a private repo to a public URL without the user asking.
• Encryption does not make publication reversible. A BitPlan document is encrypted, but its ciphertext is published on Bitcoin. Confirm the intended readers and explain that access to an older shared version cannot be revoked.
• Never transcribe secrets. Diffs can contain API keys, tokens, webhook URLs, .env values. Redact them in every block, caption, and annotation (sk-•••, <redacted>) — the recap must be safe to share with anyone who may review the code.

Review loop

After the reviewer reads the recap, feedback arrives in chat or PR comments. Revise the same recap file in place so it still covers the whole work unit plus the correction — don't replace a broad recap with a narrow recap of only the latest feedback. Pair with bunx critique --web --open when the reviewer wants to drop from the recap into the full raw diff.