visual-recap

Visual Recap

Turn a change — a PR, branch, commit range, or the working tree — into an interactive review document served entirely from the user's machine.

Before anything else, fix who you're writing for: the CEO of the company — a tech-savvy non-developer. Not a fellow engineer, not the person who wrote the code, and not someone who will ever open the repo. This shapes every sentence you write. They want the business logic — what changed, why it matters, what to watch — so explain behavior in plain language and reach for code only when the reader must see it to understand. The linter warns when plain-language sections name code symbols, and those findings must be fixed like any other.

Acknowledge first, then work quietly. Before you do anything else, reply with one short sentence that acknowledges the request and says you're gathering what you need — e.g. "On it — let me pull the diff together and build a visual recap of PR 142." This is the one message the user should get up front; never jump straight into tool calls with no reply. Then spend your tokens on the document, not on narrating: move through steps 1–4 without a play-by-play — no "Step 1: capturing the diff…", no restating the captured diff or the inventory, no "here's what I found." Your next message after the acknowledgement is the link (once served) with a one-line pointer. Every token you'd spend describing the work, spend instead making the document more complete.

The sequence — do every step, in order; the last two are the ones agents skip:

1. Capture the diff (once).
2. Inventory it (silently).
3. Write the recap file.
4. Lint it and fix every finding — required, not optional (§3).
5. Self-review the rendered document — required (§3): re-read it top to bottom against your inventory before anyone else sees it.
6. Serve it and hand over the link.
7. Read and act on comments — then back to 4 and 5 for every edit.

Every write runs write → lint → verify — the first draft and every revision. After an edit, do not serve, share, or say "done" until the linter is clean on that file and you have re-read the changed sections against its closing reminder. Revisions are where agents skip this.