Score = (Completeness × 0.25) + (Accuracy × 0.25) + (Clarity × 0.20)
      + (Consistency × 0.15) + (Navigation × 0.10) + (Freshness × 0.05)

Rating:
90-100: Excellent
75-89:  Good
60-74:  Adequate
40-59:  Poor
0-39:   Critical

# Find undocumented public classes
Grep: "^class |^final class |^abstract class " --glob "src/**/*.php"
# Compare with: Grep: "## " --glob "docs/api/**/*.md"

# Find undocumented public methods
Grep: "public function " --glob "src/**/*.php" | wc -l
# Compare with documented count

# Check README sections
Grep: "## Installation|## Usage|## Features" --glob "README.md"

# Find version mismatches
Grep: "version.*[0-9]+\.[0-9]+" --glob "README.md"
# Compare with: Grep: '"version"' --glob "composer.json"

# Find non-existent paths in docs
Grep: "src/[A-Za-z/]+" --glob "docs/**/*.md"
# Verify each path exists

# Find outdated code examples
# Extract code blocks and verify they match current API

# Find undefined acronyms
Grep: "\b[A-Z]{2,}\b" --glob "docs/**/*.md"
# Check for glossary/definition nearby

# Find jargon without explanation
# Manual review of: DDD, CQRS, VO, DTO first usage

# Find walls of text (paragraphs > 5 lines)
# Manual review recommended

# Find broken internal links
Grep: "\]\((?!http)[^\)]+\)" --glob "**/*.md"
# Verify each relative path exists

# Find missing TOC in long docs (> 100 lines)
wc -l docs/**/*.md | awk '$1 > 100 {print $2}'
# Check for: Grep: "## Table of Contents|## Contents" in each

# Find orphan pages (not linked from anywhere)
# Cross-reference all .md files

# Find diagrams with too many elements
Grep: "^\s*[A-Za-z].*\[|^\s*[A-Za-z].*\(" --glob "**/*.md" -A 50
# Count nodes in each mermaid block

# Find diagrams without labels
Grep: "A-->B|1-->2" --glob "**/*.md"
# Should have descriptive IDs

# Find non-rendering mermaid
# Test each ```mermaid block

❌ Missing installation instructions
❌ Broken copy-paste examples
❌ Wrong/outdated code syntax
❌ Missing license
❌ Dead links to key resources
❌ Security-sensitive info in examples

⚠️ Missing API documentation
⚠️ No usage examples
⚠️ Outdated screenshots
⚠️ Inconsistent terminology
⚠️ Missing error handling docs
⚠️ Diagrams don't match code

ℹ️ No badges
ℹ️ Missing contributing guide
ℹ️ No FAQ section
ℹ️ Basic diagrams could be improved
ℹ️ Could add more examples

# Documentation Audit Report

**Project:** {name}
**Date:** {date}
**Auditor:** Claude Code

## Summary

| Metric | Score | Status |
|--------|-------|--------|
| Overall | X/100 | ⚠️ |
| Completeness | X/100 | ✅ |
| Accuracy | X/100 | ❌ |
| Clarity | X/100 | ✅ |
| Consistency | X/100 | ⚠️ |
| Navigation | X/100 | ✅ |

## Critical Issues

### 1. {Issue Title}
- **Location:** {file:line}
- **Problem:** {description}
- **Impact:** {who is affected}
- **Fix:** {recommendation}

## Warnings

### 1. {Issue Title}
- **Location:** {file}
- **Problem:** {description}
- **Recommendation:** {fix}

## Recommendations

1. {Priority action 1}
2. {Priority action 2}
3. {Priority action 3}

## Detailed Findings

### README.md
- [ ] {item}: {status}

### API Documentation
- [ ] {item}: {status}

### Architecture Documentation
- [ ] {item}: {status}

## Next Steps

1. Fix critical issues immediately
2. Address warnings in next sprint
3. Consider recommendations for roadmap

# Example doc validation workflow
documentation:
  checks:
    - markdown-lint
    - link-check
    - spelling
    - code-example-test
    - mermaid-validate