Clean up and rewrite legacy markdown documentation to match the actual codebase. Use when the user mentions outdated docs, stale documentation, doc cleanup, syncing docs with code, updating READMEs, or when docs reference APIs/features/configs that no longer exist. Also trigger when the user says things like "docs are wrong", "README is outdated", "update the docs", "documentation doesn't match the code", or asks to audit documentation accuracy.
Rewrite markdown documentation so it accurately reflects the current codebase. The goal is documentation that a new developer could trust — no references to deleted functions, renamed configs, removed features, or outdated workflows.
Find every markdown file in the repo:
Glob: **/*.md
Also check for common doc locations:
README.md at repo rootdocs/ or documentation/ directoriesCONTRIBUTING.md, CHANGELOG.md, ARCHITECTURE.md.md files co-located with source codeRead each markdown file. For large repos with many docs, prioritize by likely staleness: READMEs first, then docs/ folder, then scattered files.
Before touching any docs, build a mental model of the current codebase:
Use Glob and Grep to explore. Read key source files. The point is to know what the code actually does before judging what the docs say it does.
For each documentation file, compare what the docs claim against what the code actually does. Look for these common issues:
For each discrepancy found, verify by searching the codebase — don't assume something is gone just because you haven't seen it yet.
Rewrite each outdated doc file to accurately reflect the codebase. Follow these principles:
After rewriting, provide a summary:
If some docs reference external systems or processes you can't verify from code alone (deployment procedures, third-party service configs), flag these for the user to review manually rather than guessing.