Documentation Updates
Keep documentation in sync with code changes.
When you change behavior, update the docs that describe it.
When you add new functionality, create documentation for it.
Source Documents Are Read-Only
Primary source documents — specifications, requirements, design docs, RFCs,
and other authoritative references — must not be modified by AI agents.
These documents represent human decisions and intent.
If a source document conflicts with the code, the code is wrong, not the document.
Make source documents read-only (chmod a-w) to enforce this mechanically.
If you encounter a read-only document that seems outdated,
flag it to the user rather than changing it.
Checklist
For each file changed in this session, check for related documentation:
- Same-directory or parent README — does it describe the changed behavior?
- Docstrings and comments in the file — do they describe changed functions, methods, or classes?
- AGENTS.md / CLAUDE.md — does it reference changed commands, workflows, or skills?
- docs/ folder — do any docs describe the changed behavior or API?
- Other references — search for mentions of changed functions, classes, or file names in documentation files
Actions
| Finding |
Action |
| Documentation describes old behavior |
Update it to match the new behavior |
| New feature, API, or behavior has no docs |
Create documentation, following the project's existing conventions |
| Documentation references removed code |
Remove or update the reference |
| Comment describes what the code does, not why |
Rewrite to explain intent, or remove if the code is self-explanatory |
Creating New Documentation
When creating documentation for new functionality:
- Follow the project's existing documentation conventions (format, location, level of detail)
- If no conventions exist, place a README in the relevant directory
- Document interfaces, APIs, behaviors, and configuration — not internal implementation details
- Write for the audience: other developers, users, or future AI agents
What Not to Document
- Internal implementation details that are clear from reading the code
- Trivial getters, setters, or boilerplate
- Anything that would just restate what the code already says
Source: boochtek/ai-skills — distributed by TomeVault.
1---2name: documentation-383description: Keeping documentation up to date. Use when making any code changes. Covers READMEs, code comments, AGENTS.md, docs/, etc. Use when this capability is needed.4---56# Documentation Updates78Keep documentation in sync with code changes.9When you change behavior, update the docs that describe it.10When you add new functionality, create documentation for it.1112## Source Documents Are Read-Only1314Primary source documents — specifications, requirements, design docs, RFCs,15and other authoritative references — must not be modified by AI agents.16These documents represent human decisions and intent.17If a source document conflicts with the code, the code is wrong, not the document.1819Make source documents read-only (`chmod a-w`) to enforce this mechanically.20If you encounter a read-only document that seems outdated,21flag it to the user rather than changing it.2223## Checklist2425For each file changed in this session, check for related documentation:26271. **Same-directory or parent README** — does it describe the changed behavior?282. **Docstrings and comments in the file** — do they describe changed functions, methods, or classes?293. **AGENTS.md / CLAUDE.md** — does it reference changed commands, workflows, or skills?304. **docs/ folder** — do any docs describe the changed behavior or API?315. **Other references** — search for mentions of changed functions, classes, or file names in documentation files3233## Actions3435| Finding | Action |36|---------|--------|37| Documentation describes old behavior | Update it to match the new behavior |38| New feature, API, or behavior has no docs | Create documentation, following the project's existing conventions |39| Documentation references removed code | Remove or update the reference |40| Comment describes what the code does, not why | Rewrite to explain intent, or remove if the code is self-explanatory |4142## Creating New Documentation4344When creating documentation for new functionality:4546- Follow the project's existing documentation conventions (format, location, level of detail)47- If no conventions exist, place a README in the relevant directory48- Document interfaces, APIs, behaviors, and configuration — not internal implementation details49- Write for the audience: other developers, users, or future AI agents5051## What Not to Document5253- Internal implementation details that are clear from reading the code54- Trivial getters, setters, or boilerplate55- Anything that would just restate what the code already says5657---58> Source: [boochtek/ai-skills](https://github.com/boochtek/ai-skills) — distributed by [TomeVault](https://tomevault.io).59<!-- tomevault:4.0:skill_md:2026-06-15 -->
tomevault-io