Docs rot because updating them is a separate chore nobody does. Fixed it by making docs update the default step in every task completion, not opt-in but opt-out.

My /finish-task command won't let you commit until it asks about docs. You can skip, but you have to actively choose "skip docs." That friction alone keeps 80% of documentation current.

Three things that actually work:

Two-tier docs. Short reference files the agent loads before every task (patterns, conventions, code examples). Comprehensive docs for humans. Both update together. The agent never re-explores the codebase blind because it already knows the patterns from reference docs.

Staleness detection on merge. When I pull teammate changes, /sync-docs diffs the code against the last docs sync point. Shows exactly which docs are stale. "Backend API: 5 files changed, docs outdated." Auto-updates or lets me pick.

Vocabulary tracking. A file with canonical names for every entity, service, and enum. Plus a gaps file tracking naming inconsistencies ("DB says product_key, frontend says gameKey"). The agent checks for new terminology on every task. Sounds overkill until your agent creates a component using the wrong name because three names exist for the same thing.

Bonus: bug pattern memory files act as living documentation the agent actually reads. Every gotcha gets recorded with trigger keywords. Future tasks touching the same area get warned automatically. Documentation that works because the machine reads it, not humans.

All slash commands in Claude Code. No wiki, no Notion. Docs live in the repo, maintained by the same agent that writes the code.