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 | Situation | You MUST read | | --- | --- | | Full audit: "docs are out of date", pre-release, untrusted doc set | `references/audit.md` | | Routine re-check of previously audited docs | `references/incremental.md` | | Just finished code work; update the docs that ride along | `references/write-path.md` | | Create/extend the dictionary; term disputes; exceptions | `references/dictionary.md` | | Writing a brand-new doc; "where does this doc go?" | `references/new-docs.md` | | Writing or substantially rewriting a doc's content (any doc type) | `references/writing.md` | 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 through Python by the absolute path of the directory this SKILL.md was loaded from (`python3 <skill-dir>/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. - Drafting a doc without a written reader brief, or with sections that map one-to-one onto modules, packages, or algorithm steps. → Write the brief; organize by the reader's questions (`references/writing.md`). - Putting `file:symbol` or source-path citations into a doc for users. → Citations back your verification notes; the doc speaks the reader's vocabulary. - Opening a README with how it works inside. → Open with what the reader gets. - About to hand back a new or rewritten doc no one tried to *use*. → Run the reader test (`references/writing.md`). - 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 | Excuse | Reality | |--------|---------| | "The spec says X but the code says Y, so the spec is wrong." | Only if the spec is **evergreen**. A point-in-time design doc is allowed to differ — classify first. | | "It's obviously a reference doc, I'll just fix it." | Per-doc gut calls are how design docs get their history rewritten. Confirm the classification with the human. | | "They said be decisive and not to kick decisions back — so I'll classify and rewrite myself." | The classification confirm is the one gate you never skip; it's the difference between fixing a doc and erasing a design record. A one-line confirm costs seconds. | | "Nothing in it reads as a dated design narrative, so it's evergreen." | Absence of obvious design language isn't proof of evergreen, especially in a mixed folder like `specs/`. Ambiguous + destructive edit → treat as point-in-time and confirm. | | "I disclosed my assumption at the end." | A footnote after you've rewritten the body is too late — the record is already changed. Confirm *before* editing, not after. | | "The line number moved, I'll update it." | Line numbers drift on every edit; re-pinning re-breaks it. Convert to `file:symbol`. | | "I'll bring the example up to the new schema." | Structural example rewrites change meaning → interview, don't auto-fix. | | "The grep found nothing, the feature's gone." | A grep miss is not proof of removal. Check git history; it may be renamed. | | "37 vs. ~40 is close, I'll just write the real number." | Counts have no canonical convention — hand it to the human. | | "The symbol/route/field exists, so the claim checks out." | Existence ≠ the claim. Verify the code path that *enacts* it (the validator/handler/call site), not just that the noun exists. | | "Every doc verified clean, so the docs are good." | Per-doc accuracy ≠ a healthy set. Duplication, missing docs, and cross-doc contradictions only surface at the corpus level (audit Phase 4). | | "Scan found zero hits, the exception is resolved." | A grep miss is not resolution — confirm via `git log -S` first; `[permanent]` exceptions are never removed on scan evidence. | | "It's a tiny doc edit, stamping without a verifier is fine." | The stamp *means* independently verified. No verifier, no stamp. | | "The docs feel incomplete, I'll add a doc for each gap." | Gaps are findings. A doc with no reader is debt, not coverage. | | "The code is the source of truth, so the doc should follow its structure." | The code is how you *check* the doc. The doc follows the reader's questions; only reference docs mirror anything, and they mirror the interface, not the implementation. | | "Citing the source file makes the doc verifiable." | Verifiable to you, noise to the reader. Keep citations in the verification notes. | | "Explaining the internals helps advanced users." | Then write them an architecture doc. A user doc that explains internals makes every reader wade through them. | | "Every claim checks out against the code, so the doc is good." | True and usable are separate tests. Run the reader test. | ## 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. - Writing from the code outward — narrating modules, functions, and algorithm steps — instead of from the reader's situation inward.