explain-pr

The shape of this skill follows Blake Smith's code review hierarchy of needs: the most important job of a review is to keep the team's mental model of the system aligned as it changes. Catching bugs and debating design sit below that. Style is last. A walk is for that first job — what changed, how it works now, and what is in the blast.

A visual language for explaining pull requests. One CSS file, one small JS file. No npm, no build.

A coding agent emits a short walk of the PR (a few scenes, one claim each). Click a component to open its note and follow-up prompt in an overlay anchored beside the clicked object without moving the scene. The page header links to the pull request's original Files Changed view when a GitHub PR is available. The popup title matches the clicked label. Type a question and copy the prompt back into the agent. Close with Escape, the Close button, or a click outside; your question is kept when you reopen that component.

figure.css inlines Fraunces, IBM Plex, and the glyph icons. figure.js fills the question box and copy button, and lazy-loads mermaid.js for before/after sequence diagrams (from mermaid.min.js next to figure.js, otherwise jsDelivr).

A walk

Four scenes from grafana/tempo #7876. Typical shape: what changed, why it matters, how it works, and the blast radius.

01 · What changed

02 · Why it matters

03 · How it works

04 · Blast radius

Open it

Double-click index.html, or File → Open in a browser. Nothing to install. Do not start a server.

Skill

Load skills/explain-pr/SKILL.md. Copy figure.css and figure.js next to the HTML the model emits. The component palette is catalog.html.

Walkthroughs

Rebuild the stylesheet

python3 scripts/build-css.py