A pull request, before you read the diff

Pull request 9: the 1.8.1 polish

Reading time about 4 minutesWritten 2026-10-16For: a reviewerPull request 9 on GitHub

Pull request 9 polishes the look in 12 files, but 7 of them carry the same 24 lines, so one file, template.html, is the real change.

Keep in your head (only these)
  1. One commit, 12 files, 192 lines added and 99 removed.
  2. Seven files hold the same 24 added lines. Read template.html.
  3. The commands passed. Only a person can check the layout.

How big is it, and was it checked?

Merged 2026-10-15
12files changed
+192lines added
−99lines removed
  • Repository checksnode tools/check-repo.mjs exits 0, with 18 checks ok.
  • Plugin manifestclaude plugin validate --strict . exits 0.
  • CI, check jobThe same node tools/check-repo.mjs on Node 18 passed in 10 seconds.
  • Layout in a browserNo command to re-run. The pull request says 390 and 1280 px were looked at, in both themes.

Take: every command exits 0. The browser check is the author's word, so repeat it for any page you care about.

  1. What changed and whyFive look changes, before and after.
  2. Where the 192 lines goMost of the diff is one change, copied.
  3. What the checks proveWhat a command vouches for, and what it cannot see.
  4. Where to look firstWhat to read, what to skim and what to skip.

Chapter 1 of 4, about 1 minute

What changed, and why?

Before this: 12 files changed, and seven of them carry the same lines.

The pull request follows a close look at the gallery, the examples and real upgraded pages at 390 and 1280 px, in both themes. It polishes release 1.8.0.

Before, in 1.8.0
  • The keep label and the chapter kicker were capitals with letter spacing.
  • A callout had a 5 px left bar and a full tint.
  • A flow step's number sat over its text.
  • The mini-map shrank to fit a phone, down to 7 px labels.
  • The rail line showed the summary first, with no limit.
After, in 1.8.1
  • Both are sentence case and a little larger.
  • A callout is a white card with a hairline and a glyph before its title.
  • The number sits beside a bold title, and the line below runs full width.
  • Under 560 px the mini-map keeps its size and scrolls.
  • The rail line shows minutes first and stops at two lines.

Take from this: every change is in the template's style, plus one line of its script. No page content changes.

Remember: five look changes in the template's style block, plus one script line.

Chapter 2 of 4, about 1 minute

Where do the 192 added lines go?

Before this: 12 files changed, with 192 lines added and 99 removed.

Seven files hold the same 24 added lines and the same 13 removed lines. One is template.html. The other six carry a copy of its style and script: the gallery, three examples and two site pages.

Added lines by file group: template.html 24, six pages that carry a copy 144, five other files 24. template.htmlthe source of the change 24 Six pages with a copy24 added lines in each 144 Five other filesCHANGELOG, atlas.css and three more 24 Added lines by file group: template.html 24, six pages that carry a copy 144, five other files 24. template.htmlthe source of the change 24 Six pages with a copy24 added lines in each 144 Five other filesCHANGELOG, atlas.css and three more 24
Take from this: 168 of the 192 added lines are the same 24 lines, so reading one file covers almost all of it.
Show the diff stat for every file 
.claude-plugin/plugin.json                        |  2 +-
CHANGELOG.md                                      | 15 +++++++++
docs/index.html                                   | 37 +++++++++++++++--------
docs/roadmap.html                                 | 37 +++++++++++++++--------
skills/explainer-atlas/assets/atlas.css           | 10 +++---
skills/explainer-gather/examples/ballot.html      | 37 +++++++++++++++--------
skills/html-explainer/assets/gallery.html         | 37 +++++++++++++++--------
skills/html-explainer/assets/template.html        | 37 +++++++++++++++--------
skills/html-explainer/examples/field-guide.html   | 37 +++++++++++++++--------
skills/html-explainer/examples/playbook.html      | 37 +++++++++++++++--------
skills/html-explainer/references/design-system.md |  4 +--
skills/html-explainer/scripts/upgrade.mjs         |  1 +
12 files changed, 192 insertions(+), 99 deletions(-)

This is the output of git show --stat 04cb440. Each of the seven pages shows 24 added and 13 removed lines.

Remember: 7 of 12 files hold the same 24 added lines, so the real change is one file.

Chapter 3 of 4, about 2 minutes

What do the checks prove, and what can they not see?

Before this: the commands exit 0, and the browser check has no command to re-run.

The repository check runs six kinds of test. None of them looks at a screen, and CI's site job is skipped on pull requests.

  • PagesAll 7 shipped pages pass the page checker.
  • CopiesThe gallery and both site pages hold the template's style and script, byte for byte.
  • Paths and manifests35 paths named in skill files exist. The manifests agree, and the template's mark reads 1.8.1.
  • Hooks and merge toolhooks.json runs 3 commands that exist. merge.html ranks a fixed sample correctly.
  • LayoutSideways scroll and split words need a person at 390 and 1280 px, in both themes.

Take from this: a command vouches for the files and their copies. Only a person vouches for how a page looks.

Claimed, not re-run here

The pull request says it opened the gallery, three upgraded pages and an old atlas page at both widths and in both themes. It reports no console errors and no sideways scroll.

Show how to re-run the commands at this commit 
git worktree add --detach ../pr9-check 04cb440
cd ../pr9-check
node tools/check-repo.mjs
claude plugin validate --strict .

Both commands exit 0 at commit 04cb440. When you are done, run git worktree remove ../pr9-check from the main checkout.

Remember: commands vouch for the files and their copies, and a person must look at the layout.

Chapter 4 of 4, about 1 minute

Where should I look first, and what can I skip?

Before this: seven of the 12 files hold the same 24 lines, and no command sees the layout.

  1. Read the template's diff. It is 24 lines added and 13 removed in template.html. This is the whole idea.
  2. Skim three small files. plugin.json moves 1.8.0 to 1.8.1 on line 4. upgrade.mjs adds one hash line. CHANGELOG.md adds 15 lines.
  3. Glance at atlas.css and design-system.md. The atlas's quiet snapshot line also applies after the chapter map. The design doc's two rows match the new look.
  4. Skip the six copies. They repeat the first step. The fold below shows how to prove it.

Take from this: six files are worth a look, and the template's 37 changed lines are the ones to read.

Show how to confirm the seven files changed alike 
for f in skills/html-explainer/assets/template.html skills/html-explainer/assets/gallery.html skills/html-explainer/examples/playbook.html skills/html-explainer/examples/field-guide.html skills/explainer-gather/examples/ballot.html docs/index.html docs/roadmap.html; do
  git diff -U0 04cb440~1 04cb440 -- "$f" | grep '^[+-]' | grep -v '^+++\|^---' | sort | md5sum
done

Seven identical hashes mean the seven files changed in the same way. The repository check already proves this for the gallery and the two site pages.

Remember: read template.html first, skim three small files, and skip the six copies.

Recap

  1. Five look changes in the template's style block, plus one script line.
  2. 7 of 12 files hold the same 24 added lines, so the real change is one file.
  3. Commands vouch for the files and their copies, and a person must look at the layout.
  4. Read template.html first, skim three small files, and skip the six copies.