update-docs

Update Docs

Post-change documentation sweep. Captures non-obvious knowledge into the right docs, trims bloat, and keeps the repo's documentation surfaces aligned after changes that likely introduced drift.

When to use

• After infrastructure, configuration, architecture, or operational changes
• After a merged PR, release cut, feature shipment, or version bump when those changes likely caused doc drift
• When asked to refresh docs, instruction files, runbooks, changelogs, API docs, roadmaps, or README content
• When a session uncovered new gotchas, changed setup steps, changed external behavior, or added services
• When an API contract, feature surface, migration path, or release/install path changed
• When the repo's docs surface is obviously underspecified and it is worth suggesting a minimal docs bootstrap to the user

When NOT to use

• Writing a full documentation set from scratch without user approval
• Code correctness or security review - use code-review or security-audit
• Code quality, slop, or maintainability cleanup - use code-simplification
• Prompt authoring or reusable skill-file maintenance - use prompt-generator or skill-creator
• Full codebase audit across multiple domains - use repo-audit (it invokes update-docs as one pass)
• Git commit messages, PR descriptions, release announcement copy, or tag operations - use git
• Roadmap prioritisation and backlog shaping belongs to the roadmap skill; moving shipped [planned] / [exploring] items is roadmap Mode 2; stated version numbers and highlight prose belong here

---

AI Self-Check

Before presenting documentation updates, verify:

• Audience needs covered: setup, public behavior, gotchas, decisions, and failure modes; no redundant implementation inventory
• No stale counts introduced (used "N" or kept count accurate)
• Internal links verified (no broken references after renames or moves)
• Companion instruction files still aligned (AGENTS.md synced if CLAUDE.md changed)
• Existing doc surface checked first before creating a new markdown file
• Release, API, roadmap, and feature docs updated only if the change actually affected them
• No orphaned gotchas for already-fixed issues
• Deprecated entries marked with [DEPRECATED] prefix and date, not silently removed
• .env.example updated if env vars or runtime config changed
• If repo docs are too thin, a minimal docs bootstrap was offered to the user as a suggestion, not forced
• Size check run (wc -c) - instruction files under 40,000 chars
• README / quality-evidence sections checked for stale dates, stale counts, and old run references
• All roadmap files (committed AND gitignored) checked - their stated version/date matches current HEAD or latest tag
• When private and public roadmaps both exist, both are updated, with the public one carrying user-visible highlights only and the private one carrying internal detail
• Docs match code: commands, flags, config names, screenshots, and API examples are checked against the changed implementation
• Audience path checked: README, changelog, API docs, runbooks, and migration notes are updated only where users need them
• Cross-cutting agent hygiene applied - see references/agent-hygiene.md

Core Principle

Document what the reader needs to act, in the file they will actually check. Explain setup, public behavior, and required defaults when that audience needs them; avoid duplicating implementation inventories. Document: gotchas, decisions, failure modes, workarounds, implicit dependencies, release-facing deltas, and "the thing that took 30 minutes to figure out."

---

Practices

• Prefer generated API/schema docs where the project already has generation tooling.
• Keep examples minimal but runnable so future verification is cheap.
• Document behavior changes, deprecations, migration steps, and rollback notes in the place users will look.
• Remove stale instructions instead of appending contradictory notes.
• Keep changelog entries user-facing and avoid internal implementation noise.

Workflow

Audit-only mode: When invoked by repo-audit or asked to report/check docs, inspect applicable Steps 1-7, including companion shape and drift, without editing. Skip commit Step 8. Scope all checks to documentation affected by the requested change; private configuration and unrelated roadmaps are not an automatic sweep target.

Copy this checklist and track progress:

• 1. Identify changes (1.5 roadmap freshness, 1.6 evidence freshness)
• 2. Categorize doc impact
• 3. Check whether the repo's docs surface is missing or too thin
• 4. Update affected docs (or report what needs updating in audit-only mode)
• 5. Verify internal links; if any link is broken, fix it and return to Step 5
• 6. Audit instruction-file bloat
• 7. Sync companion instruction files
• 8. Commit doc changes

1. Identify What Changed

Check git diff and conversation context to understand what was modified:

# Uncommitted changes
git diff --name-only

# Compare against the roadmap's stated version, falling back to last tag, falling back to last 10
ROADMAP_VER=$(grep -hoE 'Current:?\s*v?[0-9]+\.[0-9]+\.[0-9]+' ROADMAP.md docs/ROADMAP.md 2>/dev/null | head -1 | grep -oE 'v?[0-9]+\.[0-9]+\.[0-9]+')
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
RANGE="${ROADMAP_VER:-${LAST_TAG}}..HEAD"
git log --oneline "$RANGE" 2>/dev/null || git log --oneline -10

Scan for changes in: configuration, infrastructure, service deployments, scripts, CI workflows, network/IP assignments, service versions, and anything operational.

1.5. Roadmap Freshness Check

Roadmaps drift the hardest because they restate facts the code, tags, and commit history already prove. Run this check whenever the repo has a roadmap - committed OR gitignored. If none is found, the step is silent; absence of ROADMAP.md is not an error.

Run the script in references/roadmap-freshness.md. It discovers every roadmap file (tracked and gitignored), parses each Current / Updated / Version header, and reports ROADMAP DRIFT when the stated version is older than the latest tag, a release was cut after the header date, or the header is more than 14 calendar days behind HEAD. On drift it widens RANGE for Step 2. The reference also has the side-channel check for stale Scanned / as of dates inside the roadmap body; report those as separate observations.

Do NOT fabricate refreshed content. The user wants staleness called out so they can decide whether to refresh manually, not invented data.

1.6. Evidence Freshness Check

README files often contain "quality evidence" paragraphs that rot quietly: old benchmark dates, old run IDs, stale skill counts, stale test counts, old release versions, or claims like "latest run" that no longer match repository state. Run this check whenever touching README, CHANGELOG, release docs, project status docs, or any doc with evidence/quality/status wording.

# Find brittle evidence claims in tracked docs.
DOCS=$(git ls-files '*.md' 'docs/**/*.md' 2>/dev/null)
if [[ -n "$DOCS" ]]; then
  printf '%s\n' "$DOCS" | while IFS= read -r doc; do
    git grep -n -E '([0-9]{4}-[0-9]{2}-[0-9]{2}|[0-9]+/[0-9]+|quality evidence|benchmark|latest (run|score|evidence|benchmark)|current (run|score|evidence|gates|version)|score[: ]|passed (for|in|on))' -- "$doc" 2>/dev/null || true
  done
fi
# Any claimed count ("N plugins", "N endpoints", "N tests") is only as good as the inventory
# that proves it. Recount from the repo's own source of truth before repeating the number:
#   git ls-files '<the tracked glob the claim describes>' | wc -l
# Do the same for scores, run IDs, and benchmark dates: re-read the artifact that stores them.

Every evidence claim needs its own artifact re-read in the same session - a count from the repo inventory, a score or run ID from the file that records it, a date from the report it came from. Never restate one from an earlier session or from the doc making the claim.

When a stale evidence claim is found, either update it from the source artifact or rewrite it to avoid brittle counts. Good: "Current repository gates pass for the public skill collection." Risky: "Current gates pass for all 42 skills" unless you verified the count in the same run.

2. Categorize Doc Impact

Map changes to documentation targets. Common instruction file names: CLAUDE.md, AGENTS.md, GEMINI.md, CODEX.md. Adapt to the project's doc structure:

Change Type	Likely Docs to Update
New/changed infrastructure specs	Project instruction file (AGENTS.md or equivalent), inventory docs
New service or app deployed	Project instruction file, deployment docs
IP/port/endpoint changes	Project instruction file, network inventory
Version bumps (runtimes, deps, images)	Project instruction file
New gotcha discovered	Project instruction file
Operational procedure performed	Runbooks or deployment checklists (include when in the deploy cycle the procedure runs)
New secret or credential	Secrets inventory
CI/CD workflow changes	Project instruction file, pipeline docs
Docker/Compose changes	Project instruction file, deployment docs
Proxmox/LXC changes	Project instruction file, inventory docs
Rust crate/toolchain changes	Project instruction file, README.md (build prereqs)
Architecture decision	ADR if significant (see below), otherwise a short bullet in the instruction file
New or changed env vars, config keys, or runtime config	.env.example, README.md (setup section)
New dependencies or setup steps	README.md (getting started / prerequisites)
API endpoint or contract changes	API.md, README.md (API section), endpoint docs, OpenAPI spec if applicable
Feature added, removed, or materially changed	README.md, feature docs (FEATURES.md, FEATURESET.md, docs/features/*.md), changelog
Merged PR with user-visible impact	Changelog, roadmap/status docs, release notes, affected feature/API/setup docs
Version bumps / new release cut	CHANGELOG.md, release notes, README.md, install/upgrade docs, badges, package manager instructions
Release cut or version bump (roadmap-side)	ROADMAP.md header (Current / Updated), Shipped Highlights section, status docs
Multiple shipped features since last roadmap update	ROADMAP.md Shipped Highlights prose and Where-We-Are summary (item status moves belong to roadmap Mode 2)
Gitignored private roadmap AND committed public roadmap both present	Update both - private gets the deeper internal detail, public gets the user-visible summary
Strategy or sequencing changes	ROADMAP.md, status docs, milestone docs

When to write an ADR: If the decision affects multiple components, constrains future options, or reverses a previous decision, it's worth a dedicated Architecture Decision Record. If it's a one-liner ("switched from X to Y because Z"), a short bullet in the project's instruction file is enough.

Gotcha placement heuristic:

• One-liner gotcha (e.g., "VIP refuses k8s traffic - use direct IP") -> project instruction file bullet.
• Multi-step procedure (e.g., "rotating a cert requires drain, replace, reload in order") -> dedicated runbook section.
• Time-critical pre/post-deploy action (e.g., "Redis FLUSHALL must run after deploy but before traffic is routed back") -> checklist at the top of the runbook, not buried in a section.

3. Check Whether the Repo's Docs Surface Is Missing or Too Thin

If the repo has no meaningful documentation surface, or only a minimal README.md, treat that as a separate observation before editing anything.

Examples of "too thin":

• No docs/ directory and no durable markdown files beyond a stub README.md
• A README.md that only names the project and gives no setup, usage, API, or feature overview
• Repeated change-driven doc drift with nowhere sensible to record it

What to do:

• Suggest a minimal docs bootstrap to the user as a dismissable recommendation
• Keep the suggestion small and concrete, for example: README.md, CHANGELOG.md, API.md, ROADMAP.md, or docs/adr/
• Tailor the suggestion to the repo type; don't propose a generic docs tree mechanically
• If the user declines, continue with the best available existing doc surface and note the limitation

What NOT to do:

• Don't automatically create a full new docs set
• Don't block routine doc maintenance on the bootstrap suggestion

4. Update Affected Docs

For each affected doc, read it first, then make targeted edits.

What to ADD:

• Gotchas that aren't obvious from code (e.g., "VIP refuses k8s traffic - use direct IP")
• Implicit dependencies between components (e.g., "must restart pod after SealedSecret update")
• Failure modes and their symptoms (e.g., "PLEG unhealthy = container runtime frozen")
• Workarounds for known issues
• Operational constraints (e.g., "serial: 1 required - removing it updates all nodes simultaneously")
• Operational timing - when a procedure must run relative to a deployment step, say so explicitly (e.g., "Redis FLUSHALL must run after the new image is deployed but before traffic is routed back")
• Connection strings and service endpoints when IPs, ports, or hostnames change
• Decisions and their rationale
• User-visible feature additions, removals, and caveats in the doc where readers expect them
• Release-facing deltas: upgraded versions, upgrade notes, breaking changes, and migration pointers
• API behavior changes in API.md, endpoint docs, or the repo's canonical API surface

When no docs exist yet:

• Don't create a full documentation set from scratch unless the user explicitly asks
• DO offer a minimal docs bootstrap suggestion if the repo is under-documented
• DO add a minimal entry to the project instruction file (CLAUDE.md, AGENTS.md, or equivalent) with the gotcha or operational note that prompted this
• If the project has no instruction file at all, note this to the user and suggest creating one with the essential gotcha. Don't block on it.

What NOT to add:

• Implementation defaults that the intended reader does not need for setup or correct use
• Standard framework/platform detail unrelated to the reader's task
• Information already in upstream docs
• Temporary state (in-progress work, one-time migration steps already completed)
• Verbose explanations - one line per gotcha, expand only if the fix is non-obvious

5. Verify Internal Links

After editing docs, check that internal references still resolve:

Prefer the repository's Markdown/link checker for affected documents. If none exists, this limited inline-link check resolves paths relative to each source document; it does not validate heading anchors, reference-style links, or nested Markdown syntax. Pass the reviewed document paths explicitly.

python3 - README.md docs/guide.md <<'PYLINK'
from pathlib import Path
from urllib.parse import unquote, urlsplit
import re, sys
failed = False
for name in sys.argv[1:]:
    source = Path(name)
    for raw in re.findall(r'\[[^\]]*\]\(([^()]+)\)', source.read_text()):
        destination = raw.strip().split(' "', 1)[0].strip('<>')
        url = urlsplit(destination)
        if url.scheme or url.netloc or not url.path:
            continue
        if url.path.startswith('/'):
            print(f"SITE-ROOT LINK: {source}: {raw}; validate against site configuration")
            continue
        target = source.parent / unquote(url.path)
        if not target.exists():
            print(f"BROKEN LINK: {source}: {raw}")
            failed = True
sys.exit(1 if failed else 0)
PYLINK

Fix each BROKEN LINK and rerun until the check exits 0. If files moved, search incoming references as well. Report unsupported link forms as unchecked, not passed.

6. Audit Project Instruction Files for Bloat

After updates, review the project's shared instruction file critically:

Remove or condense if:

• A gotcha was fixed and no longer applies (mark as resolved, then delete next session)
• Information is now in a runbook (replace with pointer)
• A section restates what's in the source (e.g., listing every container image tag)
• Multiple bullet points say the same thing differently
• A migration or one-time procedure is fully complete and won't recur
• Version numbers that Renovate/CI keeps current automatically

Keep if:

• You'd waste 15+ minutes rediscovering it without the doc
• It's a cross-component interaction not visible in any single file
• It contradicts what you'd expect from reading the code
• It's a "don't do X" warning born from actual breakage

Size targets:

• Shared instruction files: aim for under 40,000 characters and under 500 lines even if the tool allows more. If over, move detailed sections to docs/ and link.
• Individual sections: if a section exceeds 30 lines, consider splitting into a dedicated doc.
• Check size after edits: wc -c CLAUDE.md AGENTS.md 2>/dev/null

7. Sync Companion Instruction Files

If the project keeps multiple instruction files (AGENTS.md plus tool-specific variants, for example), keep them aligned after updates.

Inspect whether companions are symlinks, import stubs, generated files, or independent documents before editing. For a symlink to the canonical file, edit that source once; copying onto the same file is unnecessary. Preserve import stubs. For generated companions, edit their source fragments and run the repository generator. For independent files, update only the corresponding shared guidance and retain target-specific sections. Review the resulting diff; never overwrite an entire distinct companion as a synchronization shortcut.

Default: instruction files are usually gitignored unless the project intentionally tracks them. Check .gitignore and existing history before committing them.

8. Commit Documentation Changes

Record the initial staged and dirty state before editing. Keep a list of task-owned paths and hunks, including intended new public docs. Leave ignored/private files local. Stage only reviewed task changes with explicit paths or patch staging.

Before committing, inspect the complete staged diff and compare it with the initial index. If unrelated work was already staged, preserve it and leave the task's edits uncommitted unless the user has authorized an isolation method. Do not reset another person's index, stage every dirty Markdown file, or commit the whole index merely because some documentation changed. Follow the repository's commit workflow only when committing is within the request's scope.

Quick Reference: File Locations

File	Purpose	Committed?
README.md	Repo overview, setup, install, usage	Yes
CHANGELOG.md	Release-facing history and breaking changes	Usually yes
API.md	Human-readable API surface and contract notes	Usually yes
ROADMAP.md	Public or private plan/status surface	Depends on project
FEATURES.md / FEATURESET.md	User-visible capability inventory	Depends on project
Other *.md docs	Release notes, status docs, migration notes, architecture docs	Depends on project
AGENTS.md	Cross-tool project instructions	Depends on project (check .gitignore)
Tool-specific instruction file	Companion instructions for a specific agent/tool when a project keeps one	Depends on project (check .gitignore)
docs/	Project documentation (inventory, runbooks, ADRs, migration notes, release docs)	Yes

Handling Deprecated Features

When a feature, service, or API is deprecated during a session:

• Keep the doc entry with a [DEPRECATED] prefix and the date - don't delete immediately
• Add the replacement in the same section so readers find both
• Follow repository and explicit user retirement policy first. Verify its release, publication-date, and elapsed-time conditions before removing entries; lack of incoming references cannot shorten a promised grace period.
• Only when no policy exists, keep entries for two completed release cycles after the deprecation is published, then remove them only after checking incoming references and preserving any still-needed migration guidance. If release or publication evidence is unavailable, retain the entry and report what remains unverified.
• Breaking changes deserve their own bullet: what broke, what replaces it, any migration steps

Output Contract

See references/output-contract.md for the full contract.

• Skill name: UPDATE-DOCS
• Deliverable bucket: audits
• Mode: always-on. Every invocation applies the reporting size and evidence rules in references/output-contract.md.
• Deliverable path: docs/local/audits/update-docs/<YYYY-MM-DD>-<slug>.md
• Severity scale: P0 | P1 | P2 | P3 | info (see shared contract).

Related Skills

• repo-audit - orchestrates code-review, code-simplification, security-audit, and update-docs in parallel. Update-docs is one of the four passes.
• git - for commit message conventions and PR descriptions. Update-docs covers project documentation files; git covers version control operations.

Reference Files

• references/roadmap-freshness.md - the roadmap drift script and side-channel date check; run it in Step 1.5
• references/agent-hygiene.md - cross-cutting checks applied before returning (generated)
• references/output-contract.md - report format for every invocation (generated)

---

Common Mistakes

• Documenting everything: Avoid repeating implementation inventories. Include a default when readers need it to configure or use the product correctly.
• Stale quality evidence: README claims like "latest run", "current score", or "39/39 skills" must be checked against the source artifact in the same session.
• Orphaned gotchas: A gotcha about a bug that was fixed 3 months ago is noise. Prune regularly.
• Assuming every merge needs docs: A merged PR is a strong hint, not an automatic docs task. Check for actual drift.
• Forgetting non-README surfaces: API changes belong in API.md; release deltas belong in CHANGELOG.md; feature drift belongs in feature docs.
• Over-documenting migrations: Once a migration is complete and verified, condense to a one-liner and remove the step-by-step procedure.
• Deleting deprecated docs too early: Follow repository and explicit user policy; no-reference evidence does not waive its grace period. Use the two-completed-release fallback above only when neither defines retirement conditions.
• Skipping the roadmap header check: A roadmap with Current: v0.27 while HEAD is on v0.43 is the loudest possible drift signal. Always parse and compare the header before deciding whether the roadmap needs updates.
• Treating a gitignored roadmap as out of scope: Private roadmaps drift hardest because nobody complains about them publicly. Run the freshness check against ALL roadmaps the find command surfaces, not just tracked ones.

---

Rules

• Document deltas, not defaults. Capture what changed, what broke, and what future sessions need to know.
• Treat merged PRs and releases as doc-drift signals, not guarantees. Verify likely impact before editing.
• Prefer the right existing doc over the nearest convenient one. Put API changes in API docs, release deltas in changelogs, and planning changes in roadmap/status docs.
• Do not rewrite healthy docs for style alone. Keep edits tied to real operational value.