name: check-docs
description: |
Audit documentation: README, architecture, API docs, .env.example.
Outputs structured findings. Use log-doc-issues to create issues.
Invoke for: documentation audit, gap analysis, staleness check.

/check-docs

Audit project documentation. Output findings as structured report.

What This Does

1. Check for required documentation files
2. Assess documentation completeness
3. Detect stale/outdated content
4. Verify links and examples
5. Output prioritized findings (P0-P3)

This is a primitive. It only investigates and reports. Use /log-doc-issues to create GitHub issues or /fix-docs to fix.

Process

1. Core Documentation Check

# Required docs
[ -f "README.md" ] && echo "✓ README" || echo "✗ README"
[ -f ".env.example" ] && echo "✓ .env.example" || echo "✗ .env.example"
[ -f "ARCHITECTURE.md" ] || [ -f "docs/ARCHITECTURE.md" ] || [ -f "docs/CODEBASE_MAP.md" ] && echo "✓ Architecture" || echo "✗ Architecture"
[ -f "CONTRIBUTING.md" ] && echo "✓ CONTRIBUTING" || echo "✗ CONTRIBUTING"
[ -d "docs/adr" ] || [ -d "docs/adrs" ] && echo "✓ ADR directory" || echo "✗ ADR directory"

2. README Quality Check

# Check README sections
grep -q "## Installation" README.md 2>/dev/null && echo "✓ Installation section" || echo "✗ Installation section"
grep -q "## Quick Start" README.md 2>/dev/null || grep -q "## Getting Started" README.md 2>/dev/null && echo "✓ Quick start" || echo "✗ Quick start"
grep -q "## Configuration" README.md 2>/dev/null || grep -q "## Setup" README.md 2>/dev/null && echo "✓ Configuration" || echo "✗ Configuration"

3. .env.example Coverage

# Find env vars used but not documented
grep -rhoE "process\.env\.[A-Z_]+" --include="*.ts" --include="*.tsx" src/ app/ 2>/dev/null | \
  sort -u | sed 's/process.env.//' > /tmp/env-used.txt
[ -f ".env.example" ] && cut -d= -f1 .env.example > /tmp/env-documented.txt || touch /tmp/env-documented.txt
comm -23 <(sort /tmp/env-used.txt) <(sort /tmp/env-documented.txt) 2>/dev/null

4. Staleness Check

# Find docs not updated in 90+ days
find . -name "*.md" \( -path "./docs/*" -o -name "README.md" -o -name "CONTRIBUTING.md" \) 2>/dev/null | while read f; do
  if [ -f "$f" ]; then
    age=$(( ($(date +%s) - $(stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null)) / 86400 ))
    [ $age -gt 90 ] && echo "STALE ($age days): $f"
  fi
done

5. Link Validation

# Check for broken links (if lychee installed)
command -v lychee >/dev/null && lychee --offline *.md docs/**/*.md 2>/dev/null || echo "Install lychee for link checking"

Output Format

## Documentation Audit

### P0: Critical (Blocking)
- Missing README.md - Users cannot understand project
- Missing .env.example - Developers cannot set up environment

### P1: Essential (Required)
- README missing Installation section
- README missing Quick Start section
- 5 env vars used but not in .env.example: STRIPE_SECRET_KEY, ...
- No architecture documentation

### P2: Important (Should Have)
- README.md stale (120 days since update)
- No CONTRIBUTING.md for open source project
- No ADR directory for significant decisions

### P3: Nice to Have
- Consider adding API documentation
- Consider subdirectory READMEs for packages/

## Summary
- P0: 2 | P1: 4 | P2: 3 | P3: 2
- Missing files: README.md, .env.example
- Stale docs: 1
- Recommendation: Create README and .env.example immediately

Priority Mapping

Related

• /log-doc-issues - Create GitHub issues from findings
• /fix-docs - Fix documentation gaps
• /documentation - Full documentation workflow
• /cartographer - Generate architecture docs