/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

4a. Auth System Consistency Check

When auth system changes (Clerk, Auth0, Convex Auth, etc.), docs often reference the old system.

# Detect auth inconsistencies
# Check README for current auth
current_auth=$(grep -oE "Clerk|Auth0|Convex Auth|NextAuth|Magic Link|Supabase Auth" README.md 2>/dev/null | head -1)

# Check docs for references to OTHER auth systems
if [ "$current_auth" = "Clerk" ]; then
  # Look for outdated auth references
  grep -rlE "Magic Link|Resend|RESEND_API_KEY|Convex Auth|EMAIL_FROM" docs/ 2>/dev/null | while read f; do
    echo "⚠ INCONSISTENT ($f): References old auth system, but README uses Clerk"
  done
fi

Common auth migration leftovers:

• RESEND_API_KEY when moved to Clerk (Clerk handles email)
• Magic Link references when using Clerk social login
• Convex Auth when using Clerk with Convex
• EMAIL_FROM env var when no longer sending auth emails

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

Next.js Specific Checks

For Next.js projects, also verify:

• App Router conventions documented (reference /next-best-practices)
• RSC vs client component boundaries explained
• Route handlers and middleware documented

Related

• /log-doc-issues - Create GitHub issues from findings
• /fix-docs - Fix documentation gaps
• /documentation - Full documentation workflow
• /cartographer - Generate architecture docs
• /next-best-practices - Next.js conventions to document