documentation-reviewer

Review and update MkDocs documentation when code changes. This skill should be used when completing feature implementation, after making code changes that affect user-facing functionality, when reviewing PRs for documentation completeness, or when auditing documentation coverage. Analyzes git diffs to identify documentation gaps and provides MkDocs Material formatting patterns.

Documentation Reviewer

Overview

Ensure documentation stays synchronized with code changes. Analyze git diffs, identify impacted documentation, and update MkDocs Material docs with proper formatting.

Workflow

1. Analyze Changes → 2. Map to Docs → 3. Identify Gaps → 4. Update Docs → 5. Verify

Step 1: Analyze Changes

Run the change analysis script or manually check:

# Using script (from project root)
python3 ~/.claude/skills/documentation-reviewer/scripts/analyze_changes.py

# Manual check
git diff --name-only HEAD~1  # or specify commit range
git diff --stat HEAD~1

Step 2: Map Changes to Documentation

| Change Type | Documentation Impact | |-------------|---------------------| | New API endpoint | docs/api/endpoints.md | | New feature/component | docs/features/ or docs/architecture/ | | Config changes | docs/getting-started/ or docs/development/ | | New invoke task | docs/development/invoke-tasks.md | | Docker changes | docs/architecture/docker.md | | Model changes | docs/api/endpoints.md, docs/architecture/backend.md | | Frontend component | docs/architecture/frontend.md |

See references/change-mapping.md for complete mapping rules.

Step 3: Identify Documentation Gaps

Check for missing documentation:

New exports - Public functions/classes need documentation
Changed behavior - Updated logic needs updated docs
New config options - Environment variables, settings
Breaking changes - Migration guides required
New dependencies - Installation instructions

Step 4: Update Documentation

Use MkDocs Material syntax from references/mkdocs-material-syntax.md:

Admonitions for warnings/tips
Code blocks with titles and line numbers
Tabbed content for multi-platform instructions
Tables for structured data
Mermaid diagrams for architecture

Step 5: Verify

# Serve docs locally
mkdocs serve

# Check for broken links and build
mkdocs build --strict

Quick Reference

Must-Document Changes

[ ] New API endpoints
[ ] New CLI commands/invoke tasks
[ ] Configuration changes
[ ] Breaking changes
[ ] New features
[ ] Security-related changes

Documentation Checklist

[ ] Updated relevant docs page(s)
[ ] Added to mkdocs.yml nav if new page
[ ] Code examples are accurate and tested
[ ] Links are valid
[ ] Consistent with existing style

Resources

references/mkdocs-material-syntax.md - Formatting patterns and examples
references/change-mapping.md - Code-to-docs mapping rules
references/documentation-standards.md - Writing style and structure
scripts/analyze_changes.py - Git diff analysis tool