maintaining-documentation

Maintaining Documentation

Overview

A doc is a set of claims about reality; this skill keeps a project's docs matching reality over time. The same law binds every flow: decide whether a doc is even supposed to track current reality (classify first), auto-fix only what is determinate, route everything ambiguous to the human, and never rewrite a historical record. Violating the letter of these rules is violating the spirit of them. "I was bringing the docs up to date" is exactly how design docs get their history erased.

Dispatch — read the flow file before doing anything

These are hard gates: do not start a flow from memory of this table. Flows add process; the law below binds all of them and is never restated in flow files.

STOP: classify before you edit (evergreen vs. point-in-time)

The single biggest failure is rewriting a dated design/plan/spec to "match the code." A spec from three months ago describing how something should work is not wrong when the code later diverged — editing it to match destroys the record.

• Evergreen — README, ABOUT, CLAUDE.md, tutorials, living API/schema reference. Contract: reflects current reality. Drift is a defect → fix.
• Point-in-time — design specs, plans, brainstorm notes (often dated, or under docs/specs|plans|…). Contract: true as of its date. Drift vs. current code is expected. Never rewrite to match code; at most add a supersede banner or as-of date.
• Mixed / unclear — conflicting signals (a dated-folder README) → treat the whole doc as interview-only.

Classify the doc set first, at the group level (folder globs + named exceptions), and confirm with the human before editing anything. Precedence: a point-in-time signal (dated filename, point-in-time directory) beats an evergreen name like README. Do not decide this per-doc by gut as you go — surface it as one decision.

The classification confirmation is the one gate you never skip — not under time pressure, not under authority, not under "just be decisive, don't kick it back to me." A one-line confirm costs seconds; skipping it is what turns an audit into an erased design record. And when classification is genuinely ambiguous (e.g. a reference-looking file inside a specs/ folder that also holds design docs), resolve to the safe side — treat it as point-in-time and confirm — because a body rewrite is irreversible to the record. Disclosing your assumption in a footnote after you've rewritten the body is too late.

The confirmed classification persists in the doc index (Class column — see Artifacts). Editing flows gate on it: no index → run audit Phase 0 first. Never classify by gut mid-flow.

Scope & exclusions

Default target: README, top-level *.md, docs/**, CLAUDE.md. Always exclude: git-ignored paths, .claude/, .private-journal/, worktrees; generated / foreign-owned docs (any "do not edit" / "generated by" sentinel — editing them is futile, the next regeneration wipes it); non-markdown. The dictionary (docs/DICTIONARY.md) is excluded from its own terminology sweep.

The rubric: what may be auto-fixed

Auto-fix a claim only when ALL hold:

1. the doc is evergreen;
2. the claim is mechanical — an identifier/path, CLI flag, config/env name+default, API route/field, or a token-level example fix;
3. a single live (non-test) counterpart exists in the code, so the right value is determined, not guessed (multiple hits / test-only / no hit → interview);
4. it's a local token replacement that leaves the surrounding sentence true;
5. a missing counterpart is confirmed removed vs. renamed via git history (git log -S, --follow, blame) before you conclude anything.

Dictionary clause. In evergreen prose only, a deprecated synonym may be auto-fixed when ALL hold: the synonym maps to exactly one dictionary entry (whose heading is the replacement); the match is whole-word; no exception covers it; and the replacement leaves the surrounding sentence true. The determinant is the dictionary instead of a code counterpart — conditions 1, 4 and 5 still apply. Code identifiers, UI strings: never auto-fixed — findings only (rename / add entry / add exception). Commit messages: dictionary terms in new ones; history is never flagged.

Always interview — never auto-fix — regardless of category:

• Counts & inventories ("14 workflows", "~40 files") — no canonical counting convention.
• Bare line-number citations (file.go:120-130) — they drift on every edit. Recommend rewriting to file:symbol; never silently renumber.
• Absence / negative claims ("there is no env-var fallback") — you can't grep-prove a negative.
• Cross-reference repair — detecting a broken link is fine; choosing its new target rarely is.
• Structural changes to embedded examples — rewriting an example's shape to a new schema.
• Behavioral / semantic claims ("does X when Y", sequencing, rationale).
• Claims whose ground truth lives in another repo or an external binary.

Verify the claim, not just the symbol

Confirming that the thing a doc names exists is not confirming the claim about it. A claim of the form "X is validated / X happens when Y / X is done by Z / X is configured as W" is verified only by the code path that enacts it — the validator that rejects, the handler that closes the stream, the function that computes the value, the line that loads the asset — not by X's mere existence. Check the verb, not just the noun.

• "the loader rejects an emit node that declares runner" → find the rejection in the validator, or the claim is false.
• "the stream closes when the run is terminal" → find the close on every terminal state, or name the one it misses.
• "diffs are computed in internal/document" → find the call there, not just the function's definition.
• "Tailwind is loaded from a CDN" → check the actual <script src>, not that Tailwind is used.

This is the most common false-matches: the noun checks out, so the verifier waves the verb through. State the mechanism, and point the citation at the code that does the thing claimed.

Artifacts: dictionary and index

The skill maintains exactly two artifacts per project, plus inline stamps. Never a third metadata file.

• docs/DICTIONARY.md — normative terminology for docs, code identifiers, commit messages, and UI strings; divergences live in its Exceptions section, scoped by path globs only. Template: templates/DICTIONARY-template.md; grammar and lifecycle: references/dictionary.md. Evergreen, stamped, and the canonical owner of terminology.
• The doc index — a sentinel-fenced table (<!-- doc-index:begin/end -->) in docs/README.md, or standalone docs/INDEX.md where no README exists. Columns: Doc | What | Class | Owns. Class is the persisted classify-and-confirm output; Owns is machine-readable path globs (what docmaint stale diffs). Template: templates/INDEX-template.md.
• docmaint (scan | stamp | stale, --help for usage) does the mechanical work. It never edits docs; agents do, under the rubric. It lives in this skill's scripts/ directory — not in the target repo — so invoke it by absolute path (e.g. ~/.claude/skills/maintaining-documentation/scripts/docmaint), and pass --root <target-repo> unless your cwd is already the target repo root (--root defaults to cwd). Flow files write bare docmaint <subcommand>; this resolution rule applies everywhere.

Stamp contract

Evergreen docs carry one idempotent block at EOF (docmaint stamp maintains it; sentinel <!-- doc-audit:last-reviewed -->):

---
<!-- doc-audit:last-reviewed -->
_Last reviewed: 2026-06-09 · commit `abc1234` · verified against code (2 claims deferred to review)._

The SHA is provenance and the incremental cursor — a deliberate change from the predecessor skill. Incremental re-audits are triage, not soundness: deferred claims keep a doc on the worklist regardless of SHA; claims with ground truth outside the repo are cleared only by full audits; terminology never depends on stamps (docmaint scan full-sweeps every run). Stamping precondition (all flows): no stamp without independent verification of the applied edits — full audits use two or more competing verifiers (Phase 3); diff- or worklist-bounded flows use at least one independent verifier. Don't stamp point-in-time docs. Stamp only what you verified — and any evergreen claim you could not verify this pass, including claims whose ground truth lives outside the repo, counts toward --deferred N. Never let an unverified claim ride under a clean stamp.

Pragmatism law

• Docs exist for readers. Before creating any doc, entry, or artifact, name the reader. No reader → don't write it.
• Adopt existing structures before imposing new ones.
• Two artifacts per project (dictionary, index) plus stamps. Never a third.
• A coverage gap is a finding to file, not a mandate to generate a doc.
• The dictionary stays readable in one sitting: load-bearing terms only.
• Write-path stays bounded by the diff. If maintenance isn't cheap, it won't happen.

Red flags — STOP

• "I'll bring the docs up to date" across a whole spec/plan set without classifying first. → Classify and confirm first.
• About to renumber a file:line citation. → Convert to file:symbol via interview.
• About to rewrite an example's structure to the new schema. → Interview, not auto-fix.
• Pressured to "be decisive / don't confirm", about to classify docs yourself and rewrite their bodies. → The classification confirm is the one gate you never skip. Surface it; a one-line yes costs seconds.
• Concluding a feature was "removed" / deleting its docs from a grep miss. → Check git history first.
• "Close enough, I'll just fix the count." → Counts go to the human.
• Editing a file that says "generated" / "do not edit". → Skip it.
• Marking a claim "matches" without a citation. → Cite it or don't claim it.
• About to finish without a second adversarial pass over your own edits. → In a full audit, run the competing verify pass (audit Phase 3) first; in bounded flows, the one-verifier stamping precondition applies. Fix what it finds.
• Marking a claim "matches" because the symbol exists, without checking the code does what's claimed about it. → Verify the verb, not the noun.
• Audited each doc, never looked at the set (duplication, gaps, contradictions, index). → Per-doc passes are blind to set-level defects; run the corpus review (audit Phase 4 — applies to the full-audit flow).
• About to remove a [permanent] exception, or a [temporary] one on scan evidence alone. → Permanent: never. Temporary: confirm via git history first (a grep miss is not resolution).
• About to stamp a doc whose edits nobody independently verified. → The stamping precondition applies in every flow, not just full audits.
• About to write a doc, or a dictionary entry, no one asked to read. → Name the reader (pragmatism law).
• About to add a third per-project metadata file. → Two artifacts. Never a third.
• About to write an exception scope in prose ("code touching X"). → Path globs only.
• Editing docs in a project with no confirmed index Class column. → Run audit Phase 0 first.

Rationalizations

Common mistakes

• Editing before classifying.
• Spawning one subagent per point-in-time doc — batch them; they aren't claim-verified.
• An unbounded first-run interview backlog — prioritize, defer the tail to a report.
• Auto-committing the audit — leave it uncommitted for human review.
• Declaring done without adversarially verifying your own edits — your fixes are a prime hiding spot for confident-but-wrong claims (audit Phase 3).
• Treating per-doc verification as the whole job — duplication, gaps, cross-doc contradictions, and a missing index are set-level defects invisible to a per-doc pass (audit Phase 4).
• Verifying the noun, not the verb — confirming a symbol exists instead of confirming the code does what the doc claims about it.
• Treating stale output as proof of cleanliness — it is triage; soundness comes from full audits.