Refresh Repo Docs

Refresh Repo Docs

Converge a repo's human-facing documentation onto the code it describes. Wrong docs are worse than no docs — a reader who follows a stale setup guide or copies a dead example loses both their time and their trust in every other doc in the repo.

Scope boundary: this skill owns README(s), docs/, CHANGELOG, CONTRIBUTING, guides, examples, ADRs. It does not touch agent-facing docs (AGENTS.md, CLAUDE.md, agent_docs/) — those have different consumers, quality bars, and their own skill: agent-docs. If you find agent-doc drift here, note it in the report and recommend an agent-docs refresh run.

Two rules the whole workflow hangs on:

• Scope by evidence, not by reading everything. The unit of work is a flagged doc, not the codebase. Deterministic signals (broken references, docs older than the code they describe) pick the worklist; reading every source file to "build a mental model" burns the context window before the first fix. Code gets read doc-first: for each claim, read exactly the code that can prove or refute it.
• Never write a claim you didn't verify. Every command, path, flag, default, and code example you write or keep must be checked against the current code — run it if read-only, read the source if not. The failure mode of doc syncing is replacing old guesses with new ones.

Phase 0 — Detect

Run the drift detector from the repo root (read-only):

// turbo

bash scripts/check-repo-docs-freshness.sh <scope>

It writes /tmp/repo-docs-freshness.json:

• the doc corpus discovered in scope (agent docs excluded)
• broken references per doc — links and file paths that no longer exist (critical, deterministic)
• stale suspects — docs whose referenced code files have commits newer than the doc's own last commit, with the recency gap (suspicion, not proof: code can change without invalidating prose)

Build the worklist:

• audit: incremental (default) → every doc with broken references or a stale-suspect flag; plus, if since was given, every doc that references files changed in git diff --name-only <since>..HEAD.
• audit: full → every doc in the corpus. (Expensive; use for a first run on a neglected repo or a periodic deep pass.)

If the worklist is empty: report "docs current", stop.

Record the worklist as a findings ledger — a working file at /tmp/repo-docs-findings.md with one section per doc. All findings from Phase 1 go in it before any edits happen (audit fully, then fix — editing while auditing loses the cross-doc picture, and the ledger survives context compaction).

Read the docs/README.md mode table when present (the map build-memory seeds, BM-DOCS-02). Each entry carries a mode that fixes how this skill may touch it:

• generated (e.g. docs/adr/README.md) → never hand-edit; fix the source or regenerate with the named generator, and note it (per the "never hand-edit generated docs" editing standard below).
• frozen / historical / append-only → report-only: a stale claim in a frozen spec, a historical docs/build/ record, or an append-only DEFERRALS.md is surfaced in the report, not rewritten — editing it would falsify the record. docs/tickets/ and docs/build/ default to historical even absent an explicit row.
• living → the normal stale/cruft/gap/mode-drift treatment.

Scope the worklist accordingly: a generated or report-only doc never receives an in-place prose fix.

Phase 1 — Audit the worklist

For each doc in the worklist:

1. Classify its Diátaxis mode — tutorial (learning), how-to (task), reference (facts), or explanation (understanding). The mode sets the quality bar for fixes (Phase 2) and is itself checkable: a reference page that has accreted tutorial prose, or a how-to bloated with theory, is a finding (mode-drift).
2. Extract its checkable claims: commands, file paths, API/CLI surfaces, config knobs and defaults, version numbers, code examples, architecture statements, feature descriptions.
3. Verify each claim against the code — read the specific source that proves or refutes it; run read-only commands (--help, ls, builds of examples) where cheap and safe. For claims the detector already flagged (broken refs), find where the target moved (git log --follow, git log --diff-filter=R) — a rename wants a path fix, a deletion wants the section removed.
4. File each finding in the ledger under one of:
   • stale — documented, but the code moved (wrong path, changed default, renamed flag, outdated example, superseded architecture)
   • cruft — documented, but the thing no longer exists (remove; for ADRs/design docs, mark superseded instead of deleting — they are records of decisions, not living docs)
   • gap — exists in code, matters to the doc's audience, undocumented. In incremental mode, check the changed surfaces (new commands, knobs, endpoints since the baseline) against the docs that should mention them.
   • mode-drift — content in the wrong document type (see 1)
5. Severity: critical (a reader following this doc gets a wrong result: broken command, dead example, false setup step) > moderate (misleading but survivable: outdated description, stale diagram) > minor (cosmetic: dead badge, old version string in prose).

Calibration: a finding must be demonstrable — name the code that contradicts the doc. "This section could be expanded" is not drift; padding docs with speculative content is how cruft gets created. When code and doc disagree, the code is what's true now — but check git log intent before "fixing" docs to match a bug (the doc may describe intended behavior; if so, flag the code instead of rewriting truth to match an accident).

If apply is false: format the ledger (findings by doc, by severity, with evidence), report, and stop.

Phase 2 — Fix

Work through the ledger one doc at a time, foundational docs first (architecture/reference before the READMEs and guides that cite them), so downstream fixes can rely on upstream ones.

• stale → correct in place, re-verifying the replacement claim against code (not from memory of Phase 1). Update examples by running or type-checking them where feasible.
• cruft → delete the content (ADRs: annotate "Superseded by …" and leave). Removing a stale promise is a fix, not a loss.
• gap → write the missing content in the host doc's mode and voice, at proportional depth — a new config knob wants a row in the reference table, not an essay.
• mode-drift → relocate content to the right doc (or right section) and cross-link; don't delete substance to enforce purity.

Editing standards (kept intact from hard experience):

• Minimal diffs — don't reflow, reformat, or re-voice text whose content isn't changing; review noise buries the real fixes.
• Match each doc's existing voice and conventions — a refresh should be invisible except where it's a correction.
• No placeholders — never commit "TODO"/"TBD"; document fully or record it as a remaining gap in the report.
• Never hand-edit generated docs — fix the source/generator config and regenerate; note the generator in the report.
• No fabricated changelog entries — a changelog records what happened; backfill only from git log evidence, in the file's existing format.

Phase 3 — Validate and sweep

1. Re-run the detector — broken references introduced or left = fix and re-run (max 2 iterations, then report what remains):

// turbo

bash scripts/check-repo-docs-freshness.sh <scope>

2. Cross-doc consistency sweep — re-read every doc this run touched, checking the set: the same feature named the same way everywhere; example config files agree with the config reference; README feature claims agree with the deeper docs behind them; no doc still cites content this run moved or removed.

Phase 4 — Report and commit

Summarize from the ledger: per doc — stale fixed / cruft removed / gaps filled / mode fixes, each one line; then remaining gaps (found but not fixable without human input) and code suspects (places where the doc described intent and the code looks wrong).

Stage only the doc files this run touched:

git add <docs touched>
git commit -m "docs: refresh repo docs — <summary>

Scope: <scope> (<audit mode>)
Stale: X fixed | Cruft: Y removed | Gaps: Z filled | Remaining: N (see PR/report)
"

Optional CI integration

The detector is deterministic, fast, and exit-code-gated: run check-repo-docs-freshness.sh on PRs that touch docs or heavily-referenced source and fail (or warn) on broken references. Catching drift at change time beats periodic sweeps; this skill remains the periodic repair tool.

What this skill does NOT do

• Agent docs (AGENTS.md / CLAUDE.md / agent_docs/) — that's the agent-docs skill; same convergence philosophy, different consumers and quality bars.
• Generate API reference sites — it fixes prose and examples; generated references are the generator's job.
• Restructure the doc tree wholesale — file moves and information re-architecture need human buy-in; propose in the report instead.
• Write marketing copy — feature descriptions state what code does, not how exciting it is.
• Decide what the code should do — where docs and code disagree and the code looks wrong, it flags; it doesn't silently rewrite the docs to canonize a bug.