/visual-recap

name: visual-recap
description: >-
  Turn a PR, branch, commit, or git diff into an interactive visual recap with
  diagrams, file maps, API/schema summaries, annotated diffs, and focused review
  notes.
metadata:
  visibility: exported

Visual Recap

`/visual-recap` creates a visual plan built **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. The same plan data model serves both directions — schema, API, file, and architecture changes become the same `data-model`, `api-endpoint`, `file-tree`, and `diagram` blocks 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.

Publish As An Agent-Native Plan — Never Inline

The deliverable is ALWAYS a published Agent-Native Plan, created with `create-visual-recap` on the Plan MCP connector — NEVER inline chat content (not Markdown prose, an ASCII sketch, a table, a fenced "wireframe", or a "here's the recap" summary). A recap's entire value is the hosted, interactive, annotatable plan; an inline summary is not a degraded recap, it is the thing a recap replaces. If the `plan` (or legacy `agent-native-plans`) tools are not visible, discover them through the host's `tool_search` first; if they are still missing, STOP and give the user the client-specific reconnect step rather than improvising an inline recap. Before publishing, or whenever a connector or auth error appears, READ `references/connection.md` in this skill directory — it is the single source of truth for the never-inline rule, connector discovery, and the per-client reconnect steps. Local-files privacy mode (below) is the one exception.

Local-Files Privacy Mode — read `references/local-files.md`

When the user wants no hosted Plan database writes — no DB writes, no Plan MCP publish, fully local/offline/private recaps, or `AGENT_NATIVE_PLANS_MODE=local-files` — do not call any hosted Plan tool except the schema-only `get-plan-blocks` catalog lookup. Read the diff with the local `recap collect-diff` / `scan` / `build-prompt --local-files` helpers, author a local MDX folder (set `kind: "recap"` and `localOnly: true`), and preview it with `plan local check`, `plan local serve --kind recap`, and `plan local verify --kind recap`. Before using local-files mode, READ `references/local-files.md` in this skill directory — it is the single source of truth for the full contract.

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 blocks before reading the raw diff. A GitHub Action can generate one automatically from a PR 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, generated plan/source artifacts, and any local import/linking fixes needed to make the recap open.

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 publishing.

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 blocks to the generated plan body. In particular, do not create a `rich-text` block 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 plan title, brief, and `file-tree` (which carries the per-file change stats) already carry that context.

Only add prose blocks when they tell the reviewer something specific about the change that the structured blocks 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 block 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`

`rich-text` heading in a single horizontal `tabs` block (the default orientation, one file per tab), with a one-line `summary` and a few `annotations` on each — so the reviewer can drop from the high-altitude sh