docs-review

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:

1. Accuracy: Does the documentation match what the code actually does?
2. Completeness: Are there undocumented features, options, or behaviors?
3. Clarity: Would a new user understand this? Are examples realistic?
4. Consistency: Do different docs contradict each other?
5. Freshness: Has the code changed in ways the docs don't reflect?

Review Process

1. Check Recent Changes

# What changed recently that might need doc updates?
git log --oneline -20 | grep -iE "feat|fix|add|remove|change|option"

# What code files changed?
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.

# Find every config class declaration, including indirect Pydantic subclasses
rg -n "^class " src/mindroom/config

# Find all config doc files
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

# What source files actually exist?
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:

1. Critical: Wrong info that would break user workflows
2. Inaccuracy: Technical errors (wrong defaults, paths, types)
3. Missing: Undocumented features or options
4. Outdated: Was true, no longer is
5. Inconsistency: Docs contradict each other
6. 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