/check-docs

Audit project documentation. Output findings as structured report.

What This Does

Check for required documentation files
Assess documentation completeness
Detect stale/outdated content
Verify links and examples
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

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"

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"

.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

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

Check docs for references to OTHER auth systems

if [ "$current_auth" = "Clerk" ]; then

Look for outdated auth references

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

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

/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

check-docs

Safety Notice

Copy this and send it to your AI assistant to learn