Documentation Maintenance
Announce at start: "Following the doc-maintenance skill to keep docs in sync."
Core Rule
Every code change has a documentation blast radius. Map it before committing.
Process
1. Map — Identify Affected Docs
After any code change, check:
- • README mentions this feature?
- • API docs cover this endpoint/function?
- • Inline comments reference this behavior?
- • Configuration docs list this setting?
- • Architecture docs describe this component?
- • CHANGELOG needs an entry?
2. Update — Same PR, Same Commit
| Change Type | Docs to Update |
|---|---|
| New API endpoint | API docs, README (if public), CHANGELOG |
| Changed behavior | Inline comments, user-facing docs, CHANGELOG |
| New configuration | README, environment docs, config reference |
| Removed feature | All references, migration guide, CHANGELOG |
| Renamed entity | All references (grep for old name) |
3. Scaffold — New Features Need New Docs
If a feature doesn't have documentation yet:
- •Create a minimal doc (title + one-paragraph overview + basic usage)
- •Add to navigation (README, AGENTS.md, or equivalent index)
- •Mark TODOs for sections to expand later
4. Verify — Docs Match Code
- • Code examples in docs actually work
- • Links to source files are correct
- • Version numbers are current
- • Screenshots/diagrams reflect current UI
Red Flags — STOP
| Signal | Action |
|---|---|
| PR has code changes but no doc updates | Check the blast radius map |
| "I'll update docs later" | Update now — later never comes |
| Docs describe behavior that no longer exists | Delete or update immediately |
| New feature merged without any documentation | Create minimum viable doc before next task |
Related Skills
| When | Invoke |
|---|---|
| Writing the code that needs docs | planning |
| Ready to submit docs with code | pr-writing |
| Reviewing existing doc quality | code-review |
Deep Reference
For principles, rationale, anti-patterns, and examples:
- •
guides/doc-maintenance/doc-maintenance.md - •
guides/documentation-guidelines/documentation-guidelines.md