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 anti-slop
• Prompt authoring or reusable skill-file maintenance - use prompt-generator or skill-creator
• Full codebase audit across multiple domains - use full-review (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; factual drift (stated version, shipped highlights, items mistakenly listed as planned) belongs here

AI Self-Check

Before presenting documentation updates, verify:

• Only documenting gotchas, decisions, and failure modes - not defaults readable from config
• 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
• [planned] / [exploring] items that actually shipped have moved to Shipped Highlights, not left in the in-progress list
• 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
• Current source checked: dated versions, CLI flags, API names, and support windows are verified against primary docs before repeating them
• Hidden state identified: local config, credentials, caches, contexts, branches, cluster targets, or previous runs are made explicit before acting
• Verification is real: final checks exercise the actual runtime, parser, service, or integration point instead of only linting prose or happy paths
• Routing overlap checked: overlapping skills, trigger terms, and "When NOT to use" boundaries are checked before returning guidance
• Spec claims verified: claims about tool behavior, output contracts, or repo conventions are checked against current docs, scripts, or skill files
• 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

Core Principle

Document what you can't grep, in the file readers will actually check. If it's in the source code, config files, or manifests, it usually doesn't belong in docs. Document: gotchas, decisions, failure modes, workarounds, implicit dependencies, release-facing deltas, and "the thing that took 30 minutes to figure out."

Performance

• Diff the code first, then update affected docs; avoid broad rewrites unrelated to the change.
• Prefer generated API/schema docs where the project already has generation tooling.
• Keep examples minimal but runnable so future verification is cheap.

Best Practices

• 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 full-review or when the user asks to "just report" or "check docs," run Steps 1-6 and report findings without making changes or committing. Skip Steps 7-8.

1. Identify changes 1.5. Roadmap freshness check 1.6. Evidence freshness check
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
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 no roadmap is found, the step is silent and you move on; absence of ROADMAP.md is not an error.

# Discover all roadmap files (tracked AND gitignored). Normalize the leading ./ from find
# so it doesn't duplicate paths returned by git ls-files.
ROADMAPS=$(
  { git ls-files '*ROADMAP*' '*roadmap*' 2>/dev/null
    find . -maxdepth 4 -iname 'ROADMAP*' -not -path '*/node_modules/*' -not -path '*/.git/*' 2>/dev/null \
      | sed 's|^\./||'
  } | sort -u
)

if [[ -n "$ROADMAPS" ]]; then
  # Resolve the source-of-truth version (try common manifests in order)
  REPO_VER=""
  [[ -f package.json   ]] && REPO_VER=$(node -p "require('./package.json').version" 2>/dev/null)
  [[ -z "$REPO_VER" && -f Cargo.toml     ]] && REPO_VER=$(grep -m1 '^version' Cargo.toml     | sed -E 's/.*"([^"]+)".*/\1/')
  [[ -z "$REPO_VER" && -f pyproject.toml ]] && REPO_VER=$(grep -m1 '^version' pyproject.toml | sed -E 's/.*"([^"]+)".*/\1/')
  [[ -z "$REPO_VER" && -f setup.py       ]] && REPO_VER=$(grep -oE "version=['\"][^'\"]+" setup.py | sed -E "s/.*['\"]//")
  LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
  HEAD_DATE=$(git log -1 --format=%cs HEAD 2>/dev/null)

  # For each roadmap, parse the stated Current/Updated/Version header and compare
  echo "$ROADMAPS" | while read -r rm; do
    [[ -f "$rm" ]] || continue
    STATED=$(grep -hE '^>.*(Current|Updated|Version)' "$rm" 2>/dev/null | head -3)
    RM_VER=$(printf '%s' "$STATED"  | grep -oE 'v?[0-9]+\.[0-9]+\.[0-9]+' | head -1)
    RM_DATE=$