docs

/o docs — Audit and update documentation

Scans all documentation in the repo (and linked repos) against recent changes. Finds what's stale and offers to fix it.

IMPORTANT: Delegate to a subagent. Doc audits read every doc file + git log + cross-reference — extremely context-heavy. Spawn an Agent with the task, let it do the reads/writes, get back a summary of what's stale and what it fixed. Only bring results back to the main context if the user needs to approve changes.

Flow:

1. Discover docs — find all documentation files in the repo:

   • README.md, CONTRIBUTING.md, ARCHITECTURE.md, CLAUDE.md at repo root
   • docs/ directory if it exists
   • Any .md files in key directories that serve as documentation

2. Gather recent changes — read the git log since the last /o docs run (or last 7 days if first run):

   git log --since="7 days ago" --name-only --pretty=format:"%s"
   

3. Cross-reference — for each doc file, check if recent changes affect what it describes:

   • Does README.md reference files, APIs, commands, or patterns that changed?
   • Does ARCHITECTURE.md describe a structure that was reorganized?
   • Does CLAUDE.md list commands or patterns that were added/removed?
   • Are there new features with zero documentation?

4. Report and fix — render a summary:

   ## Doc audit
   
   README.md        ⚠ stale — mentions old API endpoint /v1/auth, now /v2/auth
   ARCHITECTURE.md  ✓ current
   CLAUDE.md        ⚠ stale — missing new BullMQ task "process-videos"
   docs/api.md      ⚠ stale — 3 new endpoints not documented
   
   Fix these now? (y/n)
   

   If the user says yes (or doesn't object), update the docs inline. Show the diff for each change.

Key rules:

• Don't rewrite docs from scratch — make targeted updates to stale sections
• Preserve the doc's existing style and voice
• If a doc references code, verify the references are still valid (file paths, function names, CLI commands)
• Track the last audit date in state/sessions/{session-id}.md so subsequent runs only check new changes