documenting-changes

Documenting Changes

Overview

Code without matching documentation rots into "what does this do?" within weeks. Catch drift the moment implementation finishes, while the change is still in your head.

Core principle: When code changes, the docs that describe it must change too — or you must say why not.

This is a soft gate. It surfaces affected docs and prompts the user. It does not block completion. The user decides: update now, defer, or skip.

Announce at start: "I'm using the documenting-changes skill to keep docs in sync."

When to Use

Always run before:

• Claiming a feature/fix is "done"
• Step 1.5 of finishing-a-development-branch
• Creating a PR for a feature, refactor, or bugfix

Skip only when:

• Pure cosmetic changes (formatting, whitespace, comment typos)
• The user has explicitly said "no docs needed for this"

The Process

Step 1: Inventory the Change

git diff <base>...HEAD --stat
git diff <base>...HEAD -- '*.md'   # what's already covered

Answer:

• Public surface changed? — API, CLI flags, config keys, env vars, schemas, slash commands, hooks, plugin manifest
• Workflow/behavior changed? — install steps, defaults, error messages, ordering
• New things appeared? — new feature, module, command, skill, script

Step 2: Map Each Change to Doc Locations

For each change identified, walk all five layers:

Layer	What to check
docs/	Architecture, guides, references, ADRs, plans
README.md	Overview, install, quick-start, feature list (root + subdirectory READMEs)
CHANGELOG.md / release notes	Entry under current/next version
Inline (JSDoc, TSDoc, docstrings, Go doc comments)	Signatures, parameter docs, examples at definition sites
Plugin/skill metadata	.claude-plugin/*, skills/*/SKILL.md description fields, version fields

Step 3: Decide per Change

Each change resolves to exactly one of:

1. UPDATE — touches user-visible surface or modifies existing documented behavior → write the update
2. CREATE — entirely new feature with no existing doc home → create new file (and link from index/README)
3. SKIP — internal-only change → must give a one-line justification naming the specific module and confirming no public surface changed

"Internal" alone is not a justification. "Refactored cache eviction in src/internal/cache.ts; no exported API, config, or behavior changed" is.

Step 4: Present to User (Soft Gate)

Documentation review for this work:

UPDATES NEEDED:
- docs/architecture.md — describe new event flow
- README.md — add "MyFeature" to feature list
- CHANGELOG.md — entry for v1.6.0

NEW DOCS:
- docs/guides/myfeature.md — usage guide for new MyFeature

INLINE:
- src/api/handler.ts — JSDoc on handleRequest() reflects new param

SKIPPED (internal-only):
- src/internal/cache.ts refactor — no public surface or behavior change

Update docs now (recommended), defer, or skip?

Wait for the user's choice.

• Now → apply updates, then re-run verification (lint/build/test) since docs changes can include code samples.
• Defer → record the gap explicitly: file an issue, add a TODO(docs) comment at the change site, or note "docs pending" in the CHANGELOG/PR body. Don't let it disappear.
• Skip → fine for internal-only work; the justification you produced in Step 3 stays in your reply for the record.

Quick Reference

Change type	Likely doc actions
New public API/CLI flag	UPDATE README + CHANGELOG + inline docstring; consider docs/ guide
New feature (user-facing)	CREATE docs/guides/.md + UPDATE README feature list + CHANGELOG
Behavior change of existing feature	UPDATE relevant docs/ page + CHANGELOG; check README quick-start
Renamed/removed export	UPDATE inline docs at new site + CHANGELOG (breaking?) + grep docs/ for old name
Bugfix (no behavior change beyond fix)	CHANGELOG entry; SKIP rest with justification
Internal refactor	SKIP all with one-line justification per affected module
New skill / plugin command	CREATE SKILL.md or command doc + UPDATE plugin manifest + CHANGELOG

Common Mistakes

Skipping inline docs

• Problem: Function signature changed but docstring still describes old params
• Fix: grep for the symbol you changed and check the doc comment at its definition

"I'll update docs in a follow-up PR"

• Problem: Follow-up PRs for docs rarely happen; drift compounds
• Fix: Update in same change. If truly impossible, file an issue with a deadline before merging.

Updating only docs/

• Problem: README.md and inline docs still show old usage; users hit them first
• Fix: Walk all five layers every time, even if most resolve to SKIP

Vague justification for skip

• Problem: "internal change" is a label, not a reason
• Fix: Name the file/module and the surface that did NOT change

New feature with no doc home

• Problem: Adding a feature but updating only CHANGELOG — no place a user can learn how to use it
• Fix: CREATE a docs/guides/<name>.md and link from README, even if short

Red Flags

• About to claim "done" without having looked at docs/
• Edited a function but didn't open its docstring
• Added a new feature with no entry in README or docs/
• "The code is self-documenting" (often true at unit level, almost never true for user-facing features or workflows)
• Skipping with no justification, or justification that just repeats "internal"

Integration

Called by:

• finishing-a-development-branch (Step 1.5) — between test verification and presenting merge/PR options
• verification-before-completion — completion claims include "docs reviewed"

Independent invocation: Any time after a non-trivial change, even mid-work, to keep drift from accumulating.