visual-plan

Visual Plan

Turn a plan into an interactive document the user reviews in their browser, served entirely from their machine. The plan is a plain markdown file — the bundled server renders it with diagrams, diffs, and styled blocks, live-reloads as you edit it, and collects the user's comments for you to read back.

A plan says what we will do. A recap explains what changed; a plan explains what is wrong and what we will do about it. A section that diagnoses a problem and stops is the plan's most common failure — the reader finishes it asking "so what?" — and the linter flags it (document-quality §2b).

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 decide based on business logic — what changes, why it's worth it, what could go wrong — so explain behavior in plain language and reach for code only when the reader must see it to decide. 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. "Got it — let me dig into the code and put together a visual plan for the rate-limiting change." 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: do the research and inventory silently — no step-by-step play-by-play, no restating what you found — and surface next with the link (once served) and a one-line pointer. Put the budget you'd spend narrating into the plan's coverage instead.

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

1. Research the change and write the plan file.
2. Inventory it (silently).
3. Lint it and fix every finding — required, not optional (§3).
4. Self-review the rendered document — required (§3): re-read it top to bottom against your inventory before anyone else sees it.
5. Serve it and hand over the link.
6. Read and act on comments — then back to 3 and 4 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.