Imported from nicolasdao/puffy-core (.agents/skills/update-doc/SKILL.md). Install upstream with npx skills add nicolasdao/puffy-core --skill update-doc. Copyright stays with the author.

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

Judgment calls (requires LLM intelligence — decide in Phase 3):

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:

1. Deterministic fixes to apply (from Phase 1 Step 2)
2. Content updates needed based on the code diff
3. 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:

1. 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."

2. 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

3. 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:

1. 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.
2. 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
3. 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.
4. Cross-link fixes — Add any missing links (README doc index, inter-file cross-references).
5. 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:

1. 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.
2. TOC correctness — Every file has a linked TOC after h1, all entries match current headings, no broken anchors.
3. Cross-links — Every docs/ file is linked from README. New files are cross-referenced from at least one other doc.
4. Counts and summaries — Numeric claims in updated files match the current state.
5. No stale content — Updated files do not contain descriptions of old behavior alongside new behavior.
6. 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.