Skill: Update Documentation

What This Skill Does

Updates existing project documentation to reflect code changes. Handles:

Detecting which documentation is affected by recent changes
Updating module documentation (symbols, structure, data flow)
Updating feature documentation (new behavior, changed flows)
Updating the project overview (new modules, changed architecture)
Ensuring cross-references remain valid

When to Use

After implementing a feature or fixing a bug that changes behavior
After refactoring that affects module structure or symbols
When the user says documentation is "outdated" or asks to "update docs"
After a plan phase is completed and code has changed

Do NOT use this skill to create documentation from scratch - use generate-docs instead. Do NOT use this skill to update root-level AGENTS.md - use generate-agents-md (full regeneration) or edit AGENTS.md manually.

Execution Model

The primary agent spawns doc-explorer. doc-explorer maps code changes to docs and updates files under docs/.
Rationale: doc updates are grounded in repo state; exploration + edits belong together to avoid losing "why this section changed".
For large change sets affecting multiple modules, doc-explorer self-delegates per module (see Self-Delegation below).
The primary agent should keep chat output minimal (what docs changed + any gaps).

Self-Delegation

When changes span multiple modules, doc-explorer SHOULD delegate per-module updates to separate doc-explorer instances via the Task tool:

Orchestrator instance: Identifies affected modules from git diff, spawns per-module instances
Per-module instance: Receives scoped task ("update docs for module X, changes: ..."), reads existing doc, updates it
Orchestrator: Updates cross-cutting artifacts (overview, feature docs), validates cross-references

This prevents unnecessary context growth from accumulating analysis of all changed modules in a single context.

Workflow

Step 1: Identify What Changed

Determine the scope of changes using one or more methods:

If changes are recent (current session):

Review the files modified in the current session
Check git diff for uncommitted changes

If changes are from git history:

Use git log --oneline -N to see recent commits
Use git diff <commit>..HEAD --stat to see affected files
For large diffs, self-delegate per-module analysis

If the user specifies what changed:

Focus on the modules/features the user mentions

Step 2: Map Changes to Documentation

For each changed file, determine:

Which module does it belong to? → Update docs/modules/<module>.md
Which features does it affect? → Update docs/features/<feature>.md
Does it change the project structure? → Update docs/overview.md

For changes spanning multiple modules, self-delegate per-module updates.

Step 3: Read Existing Documentation

Read the affected documentation files. Compare against the current code state:

Are symbols still accurately described?
Has the module structure changed (new files, moved files)?
Have dependencies changed?
Are data flows still correct?
Are feature behaviors still accurately described?

Step 4: Apply Updates

Update each affected document:

Module Documentation:

Update Key Symbols if exports changed
Update Structure if files were added/removed/moved
Update Dependencies if new dependencies were introduced
Update Data Flow if processing logic changed
Keep inventories in sync (files/dirs + symbols)

Feature Documentation:

Update User Flow if user-facing behavior changed
Update Technical Flow if implementation approach changed
Update Implementation table with new/changed symbols
Update Edge Cases if new limitations discovered

Project Overview:

Update Modules table if modules were added/removed
Update Features table if features were added/removed
Update Architecture if high-level structure changed
Update Tech Stack if new technologies introduced

Step 5: Validate Cross-References

Check that all module links in the overview point to existing files
Check that feature docs reference the correct module docs
If implementation plans exist, verify they still reference current module documentation
Remove references to deleted modules/features

Step 6: Report Changes

Present a summary:

Which documents were updated
What sections changed
Any gaps found (new code that has no documentation)

Rules

Never overwrite without reading first: Always read existing documentation before modifying.
Preserve manual additions: If a section was manually enriched beyond what auto-generation would produce, preserve those additions.
Incremental updates: Only update what changed. Don't regenerate entire documents.
Track the update: Update the frontmatter version or add a note if the template supports it.
No built-in explore agent: Do NOT use the built-in explore subagent type. Self-delegate to doc-explorer instead.
Self-delegate for scale: For large change sets spanning multiple modules, spawn additional doc-explorer instances per module via the Task tool.
Flag gaps: If new code lacks documentation, notify the user rather than silently ignoring it.
File-based interface: All updates are written to files in the docs/ directory. Do not return updated content as chat messages.

Templates

This skill includes normative templates as bundled files. Only read the templates when processing them. Output MUST preserve template headings/frontmatter keys when updating docs:

tpl-project-overview.md - Expected structure for project overview
tpl-module-documentation.md - Expected structure for module documentation
tpl-feature-documentation.md - Expected structure for feature documentation

update-docs