Update Docs

Update Docs — Documentation Maintenance

Keep project documentation synchronized with the current state of the code. Updates the core docs/ai-context/ files and CLAUDE.md as needed.

Core Documentation Principle

Compress aggressively — the default for every line is DELETE. A line earns its place only when it encodes something an AI agent cannot derive from the code, git log, or spec.md. Every run prunes as much as it adds.

Document current "is" state only — never reference legacy implementations or what changed.

• Write as if the documentation is being read for the first time
• No "previously", "was changed from", "used to be", or "improved" language
• No migration notes or upgrade paths within the docs themselves
• If something was removed, remove it from docs — don't leave a "removed X" note
• No build-state qualifiers ("recently added", "just landed", "new in this release") — dead the moment work ships; git log carries that

Audience: AI agents, not humans. These docs exist so a future session can prime fast. No marketing, no narrative arc, no "we did X then Y," no friendly hedging. Prefer tables, bold inline labels, and pseudocode over prose. Put code identifiers in backticks. Pair every non-obvious rule with a one-phrase reason (security, past incident, vendor quirk).

When to Skip

The bar is architecture, not activity. A run only earns doc changes when a change lands new architecture — a data flow, contract, invariant, or design decision a future session could not reconstruct from code alone. Fold that into spec.md in present tense. That is the ONLY thing that earns new lines — never a record that the work happened (git carries that), never a "we fixed/added X" note. If "document this change" reduces to "note that we did it," write nothing.

Do NOT run this skill for:

• Bug fixes that don't change architecture or capabilities
• Small refactors (rename, extract method) that don't change behavior
• UI tweaks or styling changes
• Single file additions within existing patterns
• Performance optimizations without architectural impact
• Comment or formatting changes

What NOT to Document

Claude Code can read files and grep code. Only document what cannot be inferred from the code itself:

Density test: Before adding content, ask: "Could Claude figure this out by reading the code?" If yes, don't document it.

Process

Step 0 (optional): Scope to a module

Default scope is the whole project — one project per repo. If your repo splits into modules/components under distinct top-level paths (each with its own docs/ai-context/), you may narrow to the one touched this session: git status --short shows which path has modified files; update only that module's docs. Skip this step entirely if the project has a single docs/ai-context/ — which is the common case.

Step 1: Analyze What Changed

Check recent changes:

git diff --stat HEAD
git log --oneline -5

Identify what categories of change occurred:

• New feature or capability → update spec.md, possibly progress.md
• New files or directories → update project-structure.md
• Deployment or infrastructure change → update deployment-infrastructure.md
• Milestone completed or status change → update progress.md
• New architecture decision or rule → update CLAUDE.md

Step 2: Update Relevant Files

Only update files where the change is meaningful. The 4 core files and their ownership:

Step 3: Apply the Single Source of Truth Rule

State each fact exactly once across the ai-context + CLAUDE.md bundle. If the same fact appears in multiple files, keep only the canonical owner and delete the rest — no breadcrumb pointer left behind. Resolve contradictions by trusting the canonical owner.

• Internal section refs are allowed — within one file, pointing §3.7 → §3.2 for navigation is fine.
• Cross-file breadcrumbs are forbidden. /update-docs and /prime load the bundle together, so writing See spec.md §X from another file is pure overhead. Move the fact to its owner; don't leave a pointer.

Examples:

• API endpoint details → spec.md (not CLAUDE.md)
• File naming conventions → CLAUDE.md (not project-structure.md)
• Deployment URLs → deployment-infrastructure.md (not spec.md)

Header-rename hazard: in single-source-of-truth docs, section-number pointers are load-bearing. If /prime is light (TOC + opening invariants only), deep facts are reached via CLAUDE.md → spec.md <section> pointers. Renaming a ## header means updating every pointer that cites it — or the pointer dangles.

Step 4: Keep Docs Lean

Only document non-obvious complexity that can't be inferred from reading the code:

• Architecture decisions and their rationale
• Non-obvious constraints (e.g., "audio must never be stored")
• Cross-cutting concerns that span multiple files
• External service configurations

Do NOT document:

• What a function does (the code shows this)
• Standard framework patterns (the framework docs cover this)
• Obvious file purposes (e.g., "utils.ts contains utility functions")