/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

Gap	Priority
Missing README.md	P0
Missing .env.example (with env vars used)	P0
Incomplete README sections	P1
Missing architecture docs	P1
Undocumented env vars	P1
Stale documentation	P2
Missing CONTRIBUTING.md	P2
Missing ADRs	P2
Polish and extras	P3

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