| name | visual-recap |
| description | Use when turning a PR/branch/commit diff into a self-contained interactive HTML recap (annotated diffs, file maps, API/schema summaries, wireframes) saved locally and opened in the browser. |
Visual Recap
/visual-recap builds a self-contained recap.html from a diff, not toward
one. It is the reverse of forward planning: instead of describing the change you
are about to make, you describe the change that was just made, at a higher
altitude than line-by-line review — same structured thinking, in reverse. Schema,
API, file, and architecture changes become the same data-model, API-endpoint,
file-tree, and diagram sections a forward plan would use, only now they summarize
work that exists. A reviewer scans the shape of the change before spending
attention on the literal lines. The deliverable is ONE self-contained HTML file
plans/<slug>/recap.html — everything inline, no external network references,
opened locally.
When To Use
Build a recap when a PR or commit is large, multi-file, or touches schema, API
contracts, or architecture, and a reviewer would benefit from seeing the change
mapped to structured sections before reading the raw diff. An agent can generate
one on request ("recap this PR", "show me what this branch changed"). Skip it for
small, single-file, or obvious diffs — a recap is review overhead, and a tiny
change reviews faster as plain diff.
Recap The Whole Work Unit
When /visual-recap is invoked in a chat thread after work has already happened,
the default scope is the whole current work unit/thread, not only the most recent
user message, tool action, or follow-up fix. Gather the thread-owned changes
across the conversation: original implementation work, later bug fixes, UI
follow-ups, tests, changesets, skill/instruction updates, and any generated
artifacts.
Use the current diff plus conversation context to separate thread-owned changes
from unrelated dirty work that existed before the thread. Exclude unrelated
pre-existing edits. If the scope is genuinely ambiguous and cannot be inferred,
state the assumption or ask a concise question before producing the recap.
When updating an existing recap after feedback, revise the recap so it still
covers the whole thread/work unit plus the new correction. Do not replace a broad
recap with a narrow recap of only the latest feedback unless the user explicitly
asks for that narrower scope.
Keep The Recap Body Lean
Do not add boilerplate intro, disclaimer, provenance, or summary prose to the
recap body. In particular, do not add a prose section just to say the recap is an
aid, that the reviewer should still review the diff, how many files changed, or
which ref/working tree generated the recap. The recap title, brief, and file-tree
(which carries the per-file change stats) already carry that context.
Only add prose when it tells the reviewer something specific about the change that
the structured sections do not: the objective, a real compatibility risk, an
important decision visible in the diff, or a grounded review note.
Recaps Must Be Substantial
Lean is not the same as thin. A recap is not a single wireframe plus one
sentence — that under-serves the reviewer as much as boilerplate prose over-serves
them. Alongside the visual/structural headline (wireframes, data-model,
API-endpoint, diagram), a substantial recap also carries the implementation
evidence:
- A short surface/state inventory before authoring: list the changed routes,
components, popovers/dialogs, role/access states, empty/error states, and
shared abstractions visible in the diff. The final recap must either represent
each meaningful item with a section or intentionally omit it because it is tiny,
redundant, or not user-visible.
- A file-tree of the changed files with each entry's change flag, so the reviewer
sees the footprint of the work at a glance.
- The split diff of the KEY changed files, grouped under a
## Key changes
heading in a single horizontal tabs control (one file per tab), with a one-line
summary and a few annotations on each — so the reviewer can drop from the
high-altitude shape straight into the load-bearing code. Use horizontal file
tabs, not a vertical side rail, so the selected file has enough width for the
side-by-side diff.
Skip the diff appendix only for a genuinely tiny change that reviews faster as
plain diff (see "When To Use"); for any change worth recapping, the file-tree and
key-change diffs belong in the recap.
Canonical Shape And Budgets
A strong recap follows one skeleton, top to bottom:
- UI-impact headline — wireframes first, when the diff changed rendered UI.
- Short outcome narrative: what changed and why, 1-3 paragraphs.
- data-model / API-endpoint sections for schema and contract changes.
- file-tree of the changed files with change flags.
## Key changes — one horizontal tabs control of split diffs / annotated code.
Budgets that keep the recap reviewable:
- 3-8 key-change tabs. Fewer than 3 on a large change under-serves the
reviewer; more than 8 stops being a summary.
- Keep each diff/annotated-code excerpt focused — prefer under ~150 lines per
tab; summarize or link the rest of a long file instead of dumping it.
- Title at most ~70 characters; brief 1-3 sentences.
GOOD. A 25-file auth change: Before/After wireframes of the login surface,
a two-paragraph narrative, a diff-aware data-model of the sessions table, an
API-endpoint for the new refresh route, a file-tree with change flags, and
## Key changes with five focused tabs, each with a one-line summary and a
few annotations on the load-bearing hunks.
BAD. One giant unsegmented diff dump with no summaries or annotations; or a
sparse three-section recap of a 40-file change (one wireframe, one sentence, one
file list) that forces the reviewer back into the raw diff anyway.
UI Impact Needs Wireframes
When the diff changes rendered UI, layout, density, visual state, interaction
affordances, navigation, controls, menus, dialogs, or design tokens, the recap
MUST include one or more wireframes. Prose and file diffs are not a substitute
for showing what changed visually.
Before choosing wireframes, make a UI coverage pass from the diff:
- Identify the entry surface where the change appears, such as a page header,
list row, toolbar, route shell, or menu trigger.
- Identify the interaction surface that opens or changes, such as a popover,
dialog, tab, sheet, dropdown, inline editor, or toast.
- Identify the resulting destination or persistent state, such as a public page,
read-only view, empty state, error state, loading state, permission-denied
state, or saved/shared state.
- Identify access or role variants when permissions change. Owner/admin/editor
versus viewer/non-manager differences are visual behavior and need a compact
matrix, paired wireframes, or clearly labeled state sequence.
For UI-heavy PRs, a single before/after of the entry surface is not enough.
Show the changed entry point, the main changed interaction surface, and the
resulting/destination state. Add more states when the diff adds tabs, role-based
controls, public/private visibility, invite/manage flows, destructive controls,
or empty/error branches.
Choose the smallest visual surface that makes the review clear:
- Use a
Before / After wireframe pair when the reviewer benefits from direct
comparison, such as a removed or added control, a changed state, layout
density, ordering, navigation, or a visible component replacement.
../visual-plan/references/wireframe.md owns how to lay that pair out (columns
vs. vertical stack by geometry).
- Use an after-only wireframe when the change is purely additive or the "before"
state would only show absence without adding review value.
- Use more than two wireframes when the UI change is flow-dependent, responsive,
or stateful; show the meaningful states in order instead of forcing a single
before/after pair. For a storyboard or flow sequence of multiple states, read
../visual-plan/references/canvas.md for the horizontal canvas layout.
- For tiny surfaces like menus, popovers, dialogs, toasts, or panels, show the
focused sub-surface. Do not redraw a full page unless placement in the page is
itself part of the change.
Ground each wireframe in the changed UI behavior, component names, file paths,
and diff-visible labels/states. If exact pixels are inferred rather than
captured, say so in the wireframe caption or a concise annotation.
Wireframe Quality — read ../visual-plan/references/wireframe.md
Shared references: The wireframe and artifact reference docs live in the
sibling visual-plan skill at ../visual-plan/references/. Both skills share the
same plugin's skills/ directory, so those relative paths are valid from here.
UI recap wireframes must meet a strict quality bar — full-width chrome, pinned
bottom bars, real product content, before/after comparability, the right surface
density, theme tokens instead of hex. Before authoring ANY wireframe, READ
../visual-plan/references/wireframe.md and ../visual-plan/references/artifact.md
— together they are the source of truth for HTML wireframe quality and for the
self-contained-file correctness contract. Do not author wireframes from memory.
When a browser tool is available, open the rendered recap and visually inspect it
at the current theme before reporting. If any label, annotation, toolbar, or
wireframe content overlaps another element, fix the HTML and reopen. A text-match
screenshot is not enough; visually inspect the captured image. When no browser is
available (for example a headless CI agent), state that in the recap handoff
instead.
Deliverable: a self-contained local HTML file
The deliverable is ALWAYS one self-contained HTML file
plans/<slug>/recap.html (<slug> = YYYY-MM-DD-<short-topic>), never inline
chat prose. Read ../visual-plan/references/artifact.md first — it is the
correctness contract.
- Collect the diff with git (
git diff, git diff --stat, git log) for the
whole work unit. Build every structured section mechanically from the real
diff (see Grounding Rule).
- Author
recap.html as a single self-contained document, all CSS/JS inline,
designed for this change. Use the reframed ../visual-plan/references/
docs for wireframe and document quality.
- Validate:
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/validate_artifact.py" plans/<slug>/recap.html.
Fix any violation before handoff.
- Open it (browser tool, else
open/xdg-open, else report the path).
- Feedback is file/chat based: edit
recap.html, re-validate, reopen. Keep it
covering the whole work unit unless asked to narrow scope.
Diff → HTML Section Mapping — read references/diff-mapping.md
READ references/diff-mapping.md before authoring sections. It maps every kind
of diff change — schema, API, code hunks, new files, UI, architecture — to its
corresponding recap HTML section, with grounding, formatting, and annotation rules
for each. Do not build sections from memory.
Before / After Is The Headline
The recap's center of gravity is the before/after comparison. references/diff-mapping.md
defines the two document-body primitives (side-by-side columns for structured
comparisons; split diff for code) and how wireframes serve as the visual
comparison primitive for UI diffs, including layout ownership from
../visual-plan/references/wireframe.md.
Grounding Rule
Structured sections are true by construction only if they are derived from the
actual changed lines. The diff, data-model, API-endpoint, and file-tree sections
MUST be built mechanically from the real diff — real paths, real fields, real
method/path, real before/after text — never inferred, rounded, or invented. The
model writes only the prose: the "why", the narrative, the risk read. A
confidently wrong recap is dangerous in a review context, because a reviewer who
trusts the summary may skip the very line the summary got wrong. When the diff
does not contain a fact, leave it out rather than guess; mark anything the model
inferred (not extracted) as inferred in prose.
Security
See references/diff-mapping.md for the full security guidelines: keep recaps
local and private (treat them like the source they summarize), and never
transcribe secrets — redact any keys, tokens, or credential-looking literals.
Related Skills
- visual-plan — the canonical command and the source of the shared wireframe,
artifact, and document-quality references; a recap follows the same section
discipline in reverse.
