Documentation Maintenance

Principle

Optimize documentation for future agents recovering context. Human readability matters, but the primary goal is to preserve the facts, decisions, constraints, and routes that code alone does not reliably expose.

Code should explain current behavior through names, types, schemas, tests, and module boundaries. Documentation should explain why the behavior exists, what must not be broken, how to operate it safely, and where future agents should look first.

Workflow

1. Inspect local rules first. Read project documentation conventions before applying these defaults: agent entrypoints, context maps, docs indexes, and repository-specific doc guidance when present.
2. Classify the change. Identify durable facts, decisions, constraints, procedures, vocabulary, and source-of-truth changes; then classify them as implementation-only, business rules, operations, architecture, cross-module contracts, domain language, or historical context.
3. Decide if docs are needed. Write docs only when future agents would likely misunderstand, miss, or have to rediscover the context from code alone.
4. Choose one source of truth. Update the nearest existing source instead of creating duplicates. Link to source facts rather than copying them. For docs-as-code, update the upstream schema, generator, config, source comments, or specification before generated output.
5. Write for retrieval. Include trigger conditions, invariants, risks, verification paths, and relevant code entry points.
6. Guard semantic rewrites. When replacing a doc rather than editing it, compare the old and new meaning before pruning.
7. Prune stale material. Delete, merge, or redirect outdated docs. Incorrect docs are worse than missing docs.
8. Report the decision. In the final response, say which docs changed, or why no doc update was needed.