check-docs

Instructions

Run a quick audit of documentation health.

Step 0: Read Context Memory

First, read .devdoc/context.json if it exists:

{
  "product": { "name": "..." },
  "terminology": { 
    "glossary": { "term": "definition" },
    "avoidTerms": [{ "wrong": "...", "correct": "..." }],
    "brandNames": { "ProductName": "ProductName" }
  },
  "api": { "style": "REST", "authentication": { "type": "api_key" } }
}

Use context for additional checks:

• Verify terminology usage matches glossary
• Flag usage of terms in avoidTerms
• Check brand name capitalization
• Validate API patterns match api.conventions

Step 0b: Source Verification (CRITICAL)

For each doc page, search for corresponding source files:

# For auth docs, find auth source
git ls-files | grep -iE "auth"
rg -l "export.*login" --type ts

# For API docs, find route handlers
git ls-files | grep -iE "(route|api|controller)"

Flag docs without verifiable sources:

⚠️ UNVERIFIED DOCS (no matching source files)
- docs/legacy/old-api.mdx - No source found
- docs/guides/advanced.mdx - No source found

Options:
1. 🔄 Remove these docs
2. ❓ Ask for source locations
3. 📝 Mark as needs-review

Step 1: Get Documentation Type

Read docs.json for docType field:

{ "docType": "api" }  // "internal" | "api" | "product"

If not set, detect from structure:

• Has architecture/, development/ → "internal"
• Has api-reference/, sdks/ → "api"
• Has features/, tutorials/ → "product"

This helps tailor the checks:

• internal: Should have setup guides, architecture docs
• api: Should have authentication, error handling, API reference
• product: Should have screenshots, tutorials, FAQs

Step 2: Run Checks

Standard Checks:

1. Broken Links - Check all internal href links resolve
2. Missing Pages - Pages in docs.json but file doesn't exist
3. Orphan Pages - MDX files not in docs.json navigation
4. Code Validity - Syntax check code blocks
5. Outdated Examples - Compare imports against package exports
6. Stale Versions - Check version numbers against package.json

Source Verification Checks (CRITICAL):

1. Source File Exists - For each doc, search for matching source file
2. Signature Match - Compare documented signatures vs source
3. Type Accuracy - Verify documented types match source types
4. Example Validity - Check examples work with current source

Context-Based Checks (if context.json exists):

1. Terminology - Flag incorrect terms from avoidTerms
2. Brand Names - Check capitalization matches brandNames
3. Product Name - Ensure consistent use of product.name
4. API Patterns - Verify examples follow api.conventions

Output Format

Documentation Health Check
==========================

Context: Using .devdoc/context.json ✓
DocType: api

Summary: X issues found

## Critical Issues

### Broken Links (count)
   file.mdx:line → /path (page not found)

### Missing Pages (count)
   docs.json references 'page' but file not found

### Source Verification Failed (count)
   docs/api/auth.mdx → No source file found
     Searched: src/**/*auth*.ts, lib/**/*auth*.ts
     Options:
       1. 🔄 Remove doc
       2. ❓ Ask for path
       3. 📝 Mark as TODO

### Signature Mismatch (count)
   docs/api/users.mdx → createUser signature wrong
     Documented: createUser(name, email)
     Source: createUser(options: CreateUserInput)
     File: src/lib/users.ts:45

## Warnings

### Terminology Issues (count)
   file.mdx:line → Uses "charge" instead of "payment"

### Brand Name Issues (count)
   file.mdx:line → "productname" should be "ProductName"

### Outdated Code (count)
   file.mdx:line → import { oldFunc } from 'pkg'

### Orphan Pages (count)
   path/to/file.mdx (not in navigation)

## Passed

✓ All version numbers current
✓ All internal links resolve
✓ No syntax errors in code blocks
✓ Product name used consistently
✓ All docs have verified source files

Checks By DocType

For docType: "internal"

• Setup guide exists and references correct tools
• Architecture docs present
• Development workflow documented
• Prerequisites clearly listed

For docType: "api"

• Authentication page exists
• Error codes documented
• API reference present (OpenAPI or manual)
• Quickstart under 5 minutes
• Code examples in primary language

For docType: "product"

• Screenshots present and described
• Tutorials have clear steps
• FAQ section exists
• Non-technical language used

Detailed Checks

Source Verification (CRITICAL)

For each documentation page:

# 1. Extract topic from doc path
# docs/api/auth.mdx → topic: "auth"

# 2. Search for source files
git ls-files | grep -iE "auth"
rg -l "export.*(login|authenticate)" --type ts

# 3. Read source and doc, compare:
#    - Function signatures
#    - Parameter types
#    - Return types
#    - Error codes

If source not found:

⚠️ UNVERIFIED: docs/api/auth.mdx
No source file found for authentication documentation.

Options:
1. 🔄 Auto-correct IA - Remove this doc
2. ✏️ Rename doc - Match what exists
3. 📝 Mark as TODO - Keep with warning
4. ❓ Ask for path - Where is it implemented?

Link Validation

• Internal links (href="/path")
• Anchor links (href="#section")
• Cross-references between pages

Code Block Validation

• Language tag present
• Valid syntax (basic check)
• Import statements resolve
• Uses correct primary language from context
• Examples match source code

Navigation Validation

• All pages in docs.json exist
• No duplicate entries
• Valid group structure

Content Validation

• Frontmatter present (title, description)
• No H1 headings (title from frontmatter)
• Images have alt text
• Sources cited in frontmatter

Terminology Validation (from context)

• No terms from avoidTerms used
• Brand names capitalized correctly
• Glossary terms used consistently

Quick Fixes

After running check, common fixes:

1. Broken link → Update href or create missing page
2. Orphan page → Add to docs.json or delete if unused
3. Missing frontmatter → Add title and description
4. Outdated import → Update to current export name
5. Wrong terminology → Replace with correct term from context
6. Brand name → Fix capitalization per context.json