Add a skill for keeping the documentation in step with a change

[revtex]

Five files carry this project's documentation and each answers a different question, but only one of them — CHANGELOG.md — has anything enforcing it. So a change reliably lands with a changelog entry and nothing else, and the plan, the README and CLAUDE.md fall behind exactly the way the changelog once did.

.claude/skills/document-change/SKILL.md routes a change to the files it actually owes an entry, rather than treating a touched changelog as done:

File	Answers	When
CHANGELOG.md	What changed and why it mattered	Every PR, or the no-changelog label
README.md	How the app works today	Observable behaviour changed
docs/MODERNIZATION-PLAN.md	Why it is built this way, what is left	A finding, a phase move, a falsified claim
CLAUDE.md	What must not be broken	A decision that binds future work
docs/decisions/	A phase decision and its verification	Rare

It starts from the diff rather than from the conversation, because a summary of the work reliably drops the part that turned out to matter.

Three rules that came from real mistakes

Which is most of why it is worth having. All three were made while writing #40 and #41:

• Anchor an edit on unique surrounding text. ### Removed matches twice in CHANGELOG.md.
• Never let two entries in the same unreleased block contradict each other. When a branch reworks something an unreleased entry already describes, amend that entry — neither has shipped, so the block should read as one description of the release rather than as a diary of what was tried.
• Do not leave a measurement reading as current after a change invalidated it. The Advanced page's height needed re-qualifying twice.

Two smaller decisions

The changelog section carries a worked contrast on a real entry rather than a description of the house style. The distinction between the patch and the defect is easier to copy than to explain.

Its verification step greps only the lines the change added. The first draft grepped whole files for inherited names and answered "yes, 28" on a clean tree, because the plan and the README name the predecessor legitimately — a check that always fails is a check nobody reads twice.

On .claude/

settings.local.json and worktrees/ are added to .gitignore rather than committed alongside the skill. The skill is shared and belongs to the repository; a permission allow-list full of one machine's paths does not, and an untracked .claude/ was going to end up inside someone's git add -A.

Testing

No code changes — no test, build or behaviour is affected. Labelled no-changelog: nothing here is visible to a user of the app.

🤖 Generated with Claude Code