| name | update-doc |
| description | Update project documentation after implementing new features, API endpoints, CLI commands, architectural changes, or workflow changes that affect how the project is understood, used, or maintained. Covers docs/ and README.md. Maintains Tables of Contents (up to h4). Handles new doc files by linking them from README.md. NEVER modifies CLAUDE.md, MEMORY.md, specs/, or docs/manual/. Do NOT use for internal refactors, small bug fixes, dependency bumps, test-only changes, or any change that does not affect usage, behavior, APIs, or conceptual understanding. |
| allowed-tools | Read, Edit, Write, Grep, Glob, Bash |
| argument-hint | [optional notes on what to document and how] |
Update Documentation
Update the relevant documentation files based on the recent changes only if those changes meaningfully impact how the project should be understood, used, or maintained.
User notes: $ARGUMENTS
If the user provided notes above, treat them as the primary guide for this entire workflow. The notes take precedence over your own analysis — they define what to prioritize, what to emphasize, and how to frame the changes. When no notes are provided, rely on the diff analysis and your own judgment.
When to Use This Skill
DO update documentation for
- New features or capabilities
- Changes to existing behavior, flags, options, or configuration
- Architectural changes that affect how the system works or is deployed
- Workflow changes (new deployment steps, new environment variables, new scripts)
- New or removed integrations, dependencies, or services
- Changes to data models, schemas, or API contracts
Do NOT update documentation for
- Internal refactors that do not change external behavior
- Small bug fixes with no user-facing impact
- Dependency bumps or lock-file updates
- Test-only changes (new tests, test refactors)
- Code style or formatting changes
- Changes confined entirely to
specs/, docs/manual/, or .claude/
If in doubt, err on the side of not updating — unnecessary doc churn is worse than a brief delay.
Phase 1 — Diagnostic (sub-agent)
Goal: Audit the current state of all documentation files without consuming the master agent's context window. This phase produces a structured report that drives all subsequent decisions.
Step 0 — Determine the project root
Run git rev-parse --show-toplevel to get the repository root. All file operations use this path as the base. Never use the current working directory.
Step 1 — Launch diagnostic sub-agent
Spawn an Explore sub-agent with this task:
Read references/diagnostic-checklist.md and execute every check against the project's documentation files. Scan <project_root>/README.md, <project_root>/docs/*.md (excluding docs/manual/), and <project_root>/docs/gotchas/*.md (if the directory exists). Return the full diagnostic report as specified in the checklist.
The sub-agent reads all doc files, checks compliance, and returns a structured report. The master agent does not read the doc files during this phase — it only receives the report.
Step 2 — Parse the diagnostic report
From the report, classify every issue into two buckets:
Deterministic fixes (no judgment needed — apply unconditionally):
| Issue | Action |
|---|
| TOC missing | Add linked TOC immediately after h1, covering headings up to h4 |
| TOC present but plain text (no anchors) | Convert to linked markdown list format with anchor links |
| TOC present but stale (entries don't match headings) | Regenerate TOC from current headings |
| File not linked from README doc index | Add link with one-line summary to README's Documentation section |
docs/gotchas.md hub missing | Create it — if hub+domain format, generate from existing domain files; if no domain files exist, create with a placeholder note |
docs/gotchas/ directory missing (but hub references domain files) | Create the directory — the hub expects domain files to link to |
| Gotchas hub out of sync with domain files | Regenerate the hub TOC and link list deterministically — add entries for unlisted domain files, remove entries for deleted domain files |
Judgment calls (requires LLM intelligence — decide in Phase 3):
| Issue | Decision criteria |
|---|
| File over 750 lines | Split only if multiple concerns can be identified. A single-concern file at 780 lines is acceptable. |
| Numeric claims that may be stale | Verify against current code before changing |
| File references to renamed/deleted files | Confirm the reference is broken before fixing |
| Potential stale content sections | Only update if the diff from Phase 2 confirms the behavior changed |
Phase 2 — Change Analysis
Step 3 — Analyze the code diff
Run:
git diff HEAD~1 --name-only
If HEAD~1 doesn't capture all session changes (e.g., multiple commits), widen the range or use git diff --cached --name-only for staged changes. The goal is a complete list of modified source files.
Classify changes:
- New files — new modules, commands, API endpoints, utilities
- Modified files — changed behavior, new flags, renamed interfaces
- Deleted files — removed features or deprecated code
If the user provided notes, use them to focus: the notes define which changes matter most.
Step 4 — Filter to relevant documentation files
For each documentation file from the diagnostic report, ask: could this file be affected by the code changes?
- Does the file describe a system, component, or workflow that the changes touch?
- Does the file contain counts, lists, or summaries that are now stale?
- Does the file reference files, functions, or concepts that were added, renamed, or removed?
Only include files that pass this impact test. Files with only deterministic compliance fixes (TOC, cross-links) are always included regardless of code impact.
Phase 3 — Plan
Step 5 — Build the action plan
Merge the diagnostic findings (Phase 1) with the content changes (Phase 2) into a single action plan. For each file, list:
- Deterministic fixes to apply (from Phase 1 Step 2)
- Content updates needed based on the code diff
- Structural changes if the file is over or approaching 750 lines
Decision rules for structural changes:
- File is currently over 750 lines → must split. Identify sub-concerns that can be extracted into new focused docs/ files.
- File is under 750 lines but the planned content update would push it over → split before writing. Extract existing sub-concerns first, then add new content.
- File is under 750 lines and the update keeps it under → no structural change needed.
Decision rules for new file creation:
- The change introduces an entirely new subsystem, command family, or architectural component not covered by any existing doc → create a new
docs/<topic>.md
- The change adds a section to an existing area (new flag on existing command) → update the existing doc
- When unsure → update the existing file
When creating new documentation files, follow these standards:
- Include a linked TOC immediately after the h1, covering headings up to h4
- Cross-link to related docs/ files
- Use concrete examples from the actual codebase, not generic placeholders
- Write for a developer who knows nothing about this project
- Ensure the file stays under 750 lines
Gotchas routing rules:
When code changes reveal new gotchas, determine the target file using this procedure:
-
Detect gotchas format — Check whether docs/gotchas/ directory exists with at least one .md file.
- If YES → hub+domain format. Route new gotchas to domain files.
- If NO → monolithic format. Add gotchas directly to
docs/gotchas.md. If the file exceeds 750 lines after adding, append a note in the summary: "Your gotchas.md is [N] lines. Consider running /init-doc refactor to split it into domain files."
-
Route to domain file (hub+domain format only):
- List existing domain files in
docs/gotchas/
- Match the new gotcha to an existing domain by topic (e.g., a NeonDB gotcha goes to
docs/gotchas/database.md)
- If no existing domain file matches, create a new
docs/gotchas/<domain>.md with h1, linked TOC, and the new gotcha entry
-
Sync the hub (hub+domain format only, deterministic):
- After any domain file is created or modified, regenerate
docs/gotchas.md:
- Read all files in
docs/gotchas/
- For each domain file: extract the h1 heading and build a one-line summary
- Rebuild the hub TOC: one link per domain file with its summary
- Write the hub — this is a full regeneration, not a partial patch
- Verify every hub link points to an existing file
Phase 4 — Execute
Step 6 — Apply all changes
Process files in this order:
- Structural splits first — If any file needs splitting, do it before modifying content. Create the new focused files, move the extracted content, and update cross-links.
- Content updates — Apply content changes to each affected file. Follow these writing standards:
- Use the project's actual terminology, variable names, and conventions
- Include concrete examples from the actual codebase when adding new content
- Remove outdated descriptions when behavior has changed — do not leave stale information alongside new information
- TOC fixes — After all content changes are applied to a file, regenerate or fix its TOC. The TOC must use linked markdown list format with anchor links, covering headings up to h4.
- Cross-link fixes — Add any missing links (README doc index, inter-file cross-references).
- Gotchas files — Apply the gotchas routing rules from Phase 3:
- Monolithic format: Add new gotchas directly to
docs/gotchas.md. If the file was flagged as missing, create it.
- Hub+domain format: Write new gotchas to the appropriate
docs/gotchas/<domain>.md file (create the domain file if needed). Then regenerate docs/gotchas.md hub deterministically: read all domain files, rebuild the TOC and link list from their headings. This is a full regeneration — not a selective patch.
- If no new gotchas were discovered and the hub is already in sync, no gotchas changes are needed.
Step 7 — Handle README doc index
After all file operations are complete, verify the README's Documentation section:
- Every
docs/*.md file must have a corresponding entry with a one-line summary
- Entries for deleted files must be removed
- For monorepo projects, verify the Project Structure section includes per-sub-project orientation if applicable
Phase 5 — Validate
Step 8 — Final compliance pass
Run through each modified file and verify:
- Size guardrails — README.md ≤ 750 lines, each docs/ file ≤ 750 lines, gotchas hub ≤ 50 lines. If any file exceeds the guardrail after updates, split it now.
- TOC correctness — Every file has a linked TOC after h1, all entries match current headings, no broken anchors.
- Cross-links — Every docs/ file is linked from README. New files are cross-referenced from at least one other doc.
- Counts and summaries — Numeric claims in updated files match the current state.
- No stale content — Updated files do not contain descriptions of old behavior alongside new behavior.
- Gotchas integrity:
docs/gotchas.md exists (hub or monolithic)- If hub+domain format: every domain file in
docs/gotchas/ has a corresponding entry in the hub, and every hub entry links to an existing domain file
- No domain file exceeds 750 lines
Step 9 — Summarize
List what was done:
- Files updated (with brief description of changes)
- Files created (with reason)
- Files split (with what was extracted where)
- Deterministic fixes applied (TOC, cross-links, README index, hub sync)
Protected Files (NEVER modify)
CLAUDE.md — Any CLAUDE.md at any level. Project instructions managed exclusively by the user.MEMORY.md — Claude auto-memory file. Do not read, edit, or write any .md files in auto-memory directories.specs/ — Entire specifications directory at project root.docs/manual/ — Entire manual documentation directory..claude/ — Entire .claude/ directory (skills, commands, memory, settings).
Documentation Standards Reference
These standards apply to all documentation files created or modified by this skill. They align with the init-doc skill that creates the initial documentation.
| Standard | Rule |
|---|
| TOC | Every file must have a linked markdown TOC (with anchor links) immediately after h1, covering up to h4 |
| Size | README.md ≤ 750 lines, docs/*.md ≤ 750 lines, gotchas hub ≤ 50 lines (soft guardrails — single-concern coherence is the primary driver) |
| Cross-links | All docs must be cross-linked. Every docs/ file linked from README |
| Gotchas | docs/gotchas.md must always exist. If hub+domain format, hub must be in sync with all docs/gotchas/*.md domain files |
| Examples | Use concrete examples from the actual codebase, not generic placeholders |
| Audience | Write for a developer who knows nothing about this project |
| Terminology | Use the project's actual terminology, variable names, and conventions |
| Single concern | Each docs/ file focused on one topic. Split rather than let files grow unbounded |
