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")

Step 5: Create Missing Files

If docs/ai-context/ files don't exist yet, create them from the current codebase state. Analyze the code, tech stack, and project structure to populate each file with accurate current-state documentation.

Doc-Specific Rules

progress.md:

• Use absolute dates, never relative ("March 2026", not "last week")
• When marking items complete, DELETE the item (don't strike through) — the fix is in git history
• Keep completed phase summaries to a single table row (~10 words), not paragraphs
• Remove completed checklist items that have been done for 2+ weeks
• Security items: remove when fixed, keep only open issues

spec.md:

• Don't duplicate CLAUDE.md content (architecture principles, coding standards)
• Document request format + error codes + key behaviors — skip response examples
• Reference shared utility files by path, don't reproduce their content
• Load-bearing / cross-cutting invariants live in the spec's opening section(s). Light prime reads only the opening + TOC, so an invariant buried mid-doc is invisible at session start. When folding a shipped feature in, hoist any new cross-cutting invariant up as one terse line + a → § pointer to its detail section.

CLAUDE.md:

• Only rules that change Claude's behavior — if removing a line wouldn't cause Claude to do anything differently, delete it
• Not a reference doc: no test structure tables, no naming convention tables for standard patterns

Doc Lifecycle — Permanent vs Non-Permanent

• Fold-on-ship. When a feature ships, fold its feature-doc's current architecture into spec.md (present tense) and retire the feature doc. Never leave shipped architecture in a future/feature doc.
• Hoist cross-cutting invariants up. An invariant that spans the whole project belongs in spec.md's opening, not buried in a feature doc.
• Permanence. spec.md / project-structure.md / CLAUDE.md are permanent and must NOT cite non-permanent docs (e.g. open-issues/*, feature docs) by specific-file link. Only progress.md (the roadmap) may. Carve-out: project-structure.md may list a non-permanent doc as a file-tree entry (filename + one-line role), but no deep section-number citations into it.

Named-Reference Lifecycle (optional convention)

If you tag recurring traps, gotchas, or open issues with stable IDs, give each tag a stale-pass rule so dead references get pruned instead of accumulating. The exact scheme is yours — below is one example using an open-issue tag T-XX; adopt it, rename it, or skip it entirely.

• Traps / gotchas: for each tagged item, grep the cited files/symbols. If ALL referenced files/symbols are gone, the item is dead — delete it. If the item is keyed to a resolution that has shipped, verify and delete.
• Gates / checklists: any checked ([x]) row → delete immediately; done lives in git.
• Open follow-ups: if the cited file/symbol is gone OR a recent commit closes the item → delete.
• Library-version notes (e.g. "X needs Y ≥ 0.31"): if the current pin is already past the threshold, surface it to the user rather than silently deleting — you may not know whether upstream actually fixed the issue.

Run the stale pass every invocation, regardless of which tagging scheme (if any) you use.

Bloat Check

After updating, silently check progress.md:

• Each completed phase row: ~10 words max in "What" column — trim immediately if longer
• No duplication with spec.md — if progress.md restates architecture details, delete and cross-reference
• Dead items: remove completed checklist items done 2+ weeks with no ongoing relevance

Net-line audit guard: if a run adds ≥10 lines while deleting 0, pause and reconsider. Something is almost always prunable — a run that only grows is a smell.

Then check if CLAUDE.md would also benefit from an update based on the changes made.