Maintain documentation

Documentation Maintenance

Treat documentation as versioned, reviewable product code that evolves in lockstep with the system. Update existing canonical documents rather than leaving stale pages behind or spawning duplicate guides.

1. Find every document a change touches

• Search the repository and knowledge base for references to changed files, routes, CLI flags, environment variables, database tables, events, permissions and workflow steps.
• Check every layer of documentation:
  • Root and package README.md files
  • Setup and configuration templates (.env.example, docker/launch configs)
  • Architecture docs, specs and ADRs (docs/, knowledge base)
  • API references, webhook guides and runbooks
• Before creating a new file, verify that no existing document already owns the topic. If one does, update it in place.

2. Eliminate drift and duplication

• Single source of truth per topic: keep detailed reference material (such as all environment variables or all API error codes) in one canonical place and link to it from guides instead of copying tables across multiple files.
• Reconcile contradictions: when two documents disagree, check the code to determine what actually runs, update the outdated document, and quote both sides when reporting a contradiction in a knowledge review.
• Retire or mark superseded material: when a workflow, endpoint or option is replaced, update the active documentation to show the current path and move transition details to a deprecation or migration section rather than leaving old instructions unmarked.

3. Audit links, paths and identifiers

• Verify that every relative link, anchor (#section-heading), file path, package name, script name and configuration key in the touched document exists in the repository.
• When files, symbols or routes move, update all references across README.md and docs/ in the same change.
• Keep terminology consistent with the project's domain language and glossary (GLOSSARY.md or domain docs).

4. Record what changed and why

• In implementation notes and knowledge updates, state concisely:
  • Which documents were updated, confirmed accurate, or flagged for human decision.
  • What changed in behavior or interface and why.
  • Any remaining gaps that require manual input or external verification.
• Never modify unrelated sections or rewrite working prose outside the scope of the delivered change.

Before you finish

• All docs referencing changed routes, config keys, commands or files searched and updated.
• Existing canonical document updated in place rather than duplicated.
• File paths, relative links, anchors and symbol names verified against the repo.
• Historical or deprecated details labeled clearly instead of mixed with current behavior.
• Summary states what changed, what was verified and any open questions.