| name | docs-review |
| description | Review documentation for accuracy, completeness, and consistency against the actual codebase. |
Review documentation for accuracy, completeness, and consistency. Focus on things that require judgment—automated checks handle the rest.
What's Already Automated
Don't waste time on these—CI and pre-commit hooks handle them:
- README CLI output:
markdown-code-runner regenerates CLI help blocks via docs/run_markdown_code_runner.py
- Linting/formatting: Handled by pre-commit
What This Review Is For
Focus on things that require judgment:
- Accuracy: Does the documentation match what the code actually does?
- Completeness: Are there undocumented features, options, or behaviors?
- Clarity: Would a new user understand this? Are examples realistic?
- Consistency: Do different docs contradict each other?
- Freshness: Has the code changed in ways the docs don't reflect?
Review Process
1. Check Recent Changes
git log --oneline -20 | grep -iE "feat|fix|add|remove|change|option"
git diff --name-only HEAD~20 | grep "\.py$"
Look for new features, changed defaults, renamed options, or removed functionality.
2. Verify Configuration Docs Against Code
Compare docs under docs/configuration/ against the Pydantic models in the src/mindroom/config/ package, whose root model is in src/mindroom/config/main.py.
Do not rely on a fixed list of files; discover what exists in both locations and check they match.
rg -n "^class " src/mindroom/config
ls docs/configuration/
Trace inheritance for every discovered class instead of assuming each Pydantic model directly subclasses BaseModel.
Check:
- All config keys documented, types and defaults match code
- No models exist without corresponding docs (or vice versa)
- Example YAML would actually work
3. Verify Architecture Docs Against Source
git ls-files "src/mindroom/**/*.py"
Check docs/architecture/ and the Architecture section of CLAUDE.md:
- Listed modules exist and descriptions match what the code does
- No source modules are missing from the listings
- Both locations can drift independently — check both
4. Verify Feature Docs Against Implementation
For every doc file under docs/, find the corresponding source module(s) and check they agree. Don't assume a fixed mapping — discover it:
ls docs/*.md docs/*/
ls src/mindroom/*.py src/mindroom/*/
Look for docs that describe features the code no longer has, or code with features the docs don't cover.
5. Check Examples
For examples in any doc:
- Would the
config.yaml snippets actually work?
- Are names and references realistic and current?
- Do examples use current syntax (not deprecated options)?
- Do setup snippets reference real files/flags/commands that exist in this repo/CLI?
- Do NOT flag AI model names as invalid based on your training cutoff — look them up online first
6. Cross-Reference Consistency
The same info appears in multiple places. Check for conflicts between README.md, docs/, and CLAUDE.md.
Also verify that script paths and file references in CLAUDE.md and docs/deployment/ match the actual filesystem layout.
6b. Verify Deployment Docs
Check docs/deployment/ files against actual Dockerfiles, Helm charts, scripts, and environment variable defaults in src/mindroom/constants.py.
7. Self-Check This Prompt
This prompt can become outdated too. If you notice:
- New automated checks that should be listed above
- New doc files that need review guidelines
- Patterns that caused issues
Include prompt updates in your fixes.
Output Format
Categorize findings:
- Critical: Wrong info that would break user workflows
- Inaccuracy: Technical errors (wrong defaults, paths, types)
- Missing: Undocumented features or options
- Outdated: Was true, no longer is
- Inconsistency: Docs contradict each other
- Minor: Typos, unclear wording
For each issue, provide a ready-to-apply fix:
### Issue: [Brief description]
- **File**: path/to/file.md:42
- **Problem**: What's wrong
- **Fix**: What to change
- **Verify**: How to confirm
