Work brochure
After finishing a piece of work, the user wants two things:
- The normal recap in chat, exactly as you would write it anyway (what changed, where it stands, what is not done). This skill never replaces or shortens it.
- A brochure: one self-contained HTML page that walks through the same work visually, so they can open it beside the chat and understand the change through diagrams, screenshots and annotated code rather than paragraphs.
The brochure must be accurate to the code. Every claim, number, file path and screenshot comes from the actual diff, the commands you ran and the app you looked at. Never invent a test that wasn't run or a result you didn't see.
Steps
1. Write the chat recap first
Finish the work as usual, including your normal text summary and wrap_up (if the app has one). Then build the brochure. If the user only asked for the brochure of earlier work, skip straight to step 2.
After a PR is opened (the plugin's PostToolUse hook, or one in your settings, adds a reminder after gh pr create), build the brochure for that PR with gather.sh --pr <N> in the same turn, and put the brochure link in your closing message. Don't edit the PR body to add it unless the user asks. Skip it only if the PR is a trivial one-liner (typo, version bump).
2. Gather the facts
Run the helper from the repo root (it prints commits, a per-file diffstat grouped by folder, uncommitted changes and PR info):
bash <skill-dir>/scripts/gather.sh # this branch vs main + uncommitted
bash <skill-dir>/scripts/gather.sh A..B # any git range (e.g. already-merged work)
bash <skill-dir>/scripts/gather.sh --pr 51 # a GitHub PR
Then read the parts of the diff that matter (git diff <range> -- <path>), not the whole thing. Also collect from this conversation:
- Why: the problem or request in the user's own terms.
- Decisions: options you weighed and why you chose this one.
- Verification: commands run and their real output, screenshots taken, what you checked in the browser or simulator, and what you could not verify.
- Loose ends: follow-ups, risks, anything left undone.
- Needs the user: anything only they can decide, check by eye or approve.
3. Capture the real app (when the change is visible)
If the change shows up in a UI, the brochure should show the actual application, not a description of it.
- After: screenshot the running app at the changed screen(s) with the preview tools (
preview_startwith the project's launch.json server, navigate,computer {action: "screenshot"}), or the iOS simulatorscreenshot. Capture both desktop and phone widths when layout changed. - Before: if the difference is the point, check out the base revision into a temporary worktree in the scratchpad (
git worktree add <scratchpad>/before <base>), serve it on a different port, screenshot the same view, then remove the worktree (git worktree remove). Skip this when the change is purely additive or a "before" adds nothing. - Save screenshots as files in the scratchpad, shrink them (
sips -Z 1400 -s format jpeg -s formatOptions 78 in.png --out out.jpg) and embed them asdata:URIs. Keep the whole page under ~8 MB. - For video/animation changes, embed a few stills (
ffmpeg -ss <t> -i clip.mp4 -frames:v 1 -vf scale=900:-1 still.jpg) or a frame strip, plus the measured numbers. - Non-visual changes (scripts, data, backend) get diagrams and real output instead of screenshots.
4. Plan the story, then choose visuals
Order the page as the user would want it explained: the outcome first, then how it works, then the detail. Pick visuals by what changed. Prefer a picture wherever one explains faster than text; keep prose to short captions and one-to-three-sentence paragraphs.
| What changed | Visual to use |
|---|---|
| Logic, a pipeline, a decision rule | Mermaid flowchart of the new flow; highlight the new/changed nodes with classDef changed |
| Requests between parts (UI → API → storage) | Mermaid sequenceDiagram |
| Structure (modules, files, data shape) | File map with +/− bars; Mermaid graph of how parts connect; a table of fields before/after |
| UI | Before/after screenshot pair; annotate with numbered callouts placed over the image |
| Numbers (timings, sizes, counts, performance) | An inline SVG bar chart drawn to scale, before vs after |
| State or lifecycle | Mermaid stateDiagram-v2 |
| A sequence of work (migration, multi-step change) | Numbered walkthrough steps (only when order is real) |
| Key code | Short diff excerpts (5–25 lines) with the important lines marked, inside <details> so they don't dominate |
Aim for at least three distinct visuals for a feature-sized change, and at least one for anything smaller. Diagrams must describe the real mechanism (real function names, file names, values), not generic boxes.
5. Build the page from the template
Copy <skill-dir>/template.html and fill it in. It already contains the sketchpad look (one light theme on purpose: graph-paper background, handwritten headings, pencil-sketched cards, hand-drawn diagrams), the layout, and every component listed above. Don't add a dark mode or swap the look unless the user asks. Rules:
- Keep the
<style>block and the Mermaid loader script; replace the example content. Delete sections that don't apply rather than leaving them thin (e.g. no "Before → after" for a pure refactor). <title>: the feature's name, two to four words (e.g. "Checkout Retry Logic"), not "Work summary: …".- Hero: one sentence on the outcome, the meta line (branch, PR link, date), and the stat strip (files, lines +/−, commits, checks passed). Compute numbers from gather.sh, don't estimate.
- Needs your input (sticky note under the hero): only real asks that wait on the user, one line each, saying where to look. At most three. Delete the whole note when there are none; never pad it.
- Why this way (decisions table): two to four options that were really weighed in the session, one marked Chosen, a one-line trade-off each. Don't invent alternatives to fill it; if no real choice was made, delete the section.
- Keep the page lean: these two plus the sections that apply. Don't add sections beyond the template.
- File map: one row per meaningful file (group generated/binary files into one row), +/− bar widths as a percentage of the largest file's total, plus one plain-English line on why it changed.
- Diff excerpts: escape
<,>,&. Mark lines withclass="add",class="del", orclass="hl"(important unchanged line). - Mermaid goes in
<pre class="mermaid">, starting directly after the tag with the config block from the template (---/config:/look: handDrawn/theme: neutral/---) so it renders hand-drawn both as a local file and on claude.ai. Keep the template'sclassDef changed fill:#dfe7ff,stroke:#1f4fd1,stroke-width:2pxline. Escape</>inside labels as</>, and useclass <ids> changedfor what this work added or changed. Keep each diagram to about 5–9 nodes so it fits one screen: merge consecutive steps into one node with a<br/>detail line, and split a longer flow into two diagrams. Useflowchart LRfor short chains,TDfor branching ones. - Verification: list every check with a pass / fail / not-checked chip and its evidence (output excerpt or screenshot). "Not checked" items are required when they exist.
- Write plainly: short sentences, the user's terms, no filler.
Save it as <repo-root>/.claude/work-briefs/<YYYY-MM-DD>-<slug>.html. Keep that folder out of git in every repo without touching its .gitignore, by adding it to the local exclude file once:
mkdir -p .claude/work-briefs && x="$(git rev-parse --git-common-dir)/info/exclude" && (grep -qxF '.claude/work-briefs/' "$x" 2>/dev/null || echo '.claude/work-briefs/' >> "$x")
6. Check once, then deliver
- Open it once in the browser pane (
preview_startwithurl: file://<path>, or the project's static server) and take one screenshot to confirm the diagrams rendered and nothing overflows. Fix what that one look shows; don't loop. - Show it in the side panel:
SendUserFilewithdisplay: "render". - Publish it as a private Artifact (
Artifactpublish with the file path,icon: "document", and a one-sentence description) so it survives after a worktree is cleaned up. This is the persistent copy; artifacts start private. If no Artifact tool is available (e.g. a plain terminal session), skip this and give the local path. - In chat, after your normal recap, add one line with the brochure link and the local file path.
Updating: if the user asks for changes, edit the same file and republish to the same path so the link stays the same.
What a good brochure looks like
- Someone who wasn't in the session understands what changed and why in under two minutes of scrolling.
- The first screen answers "what's different now?" without scrolling.
- Every diagram, chart and screenshot is of this change.
- The honest status is visible: what was verified, what wasn't, what's left.