# Refresh Repo Docs > Audit and sync a repo's human-facing documentation (README, docs/, CHANGELOG, CONTRIBUTING, examples) against the actual code — detect drift deterministically, fix stale claims, remove cruft, fill gaps, and verify every claim written. Use when docs are outdated, after major feature work, or on a periodic docs-hygiene pass. - Skill: `stevevitali/refresh-repo-docs` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add stevevitali/refresh-repo-docs` - Raw SKILL.md: https://api.skillmd.com/api/skills/stevevitali/refresh-repo-docs/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - License: MIT - Author: SteveVitali (https://skillmd.com/u/stevevitali) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/stevevitali/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 bash scripts/check-repo-docs-freshness.sh ``` 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 ..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 bash scripts/check-repo-docs-freshness.sh ``` 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: ```bash git add git commit -m "docs: refresh repo docs — Scope: () 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.