Documentation Auditor
Audit project documentation quality. Universal for any tech stack.
Purpose
- Proactively compress - find all opportunities to reduce size while preserving value
- Eliminate meaningless, redundant, and verbose content
- Convert prose to structured formats (tables, lists)
- Verify documentation hierarchy with CLAUDE.md as root
- Detect duplication and enforce Single Source of Truth
- Ensure docs match current code state
- Semantic verification - delegate to ln-601 to verify content matches SCOPE and codebase reality
Invocation
- Direct: User invokes for documentation quality review
- Pipeline: Called by ln-100-documents-pipeline (Phase 5, if auditDocs=true)
Workflow
- Scan: Find all .md files in project (CLAUDE.md, README.md, docs/**)
- Build Tree: Construct hierarchy from CLAUDE.md outward links
- Audit Categories 1-7: Run structural checks (see Audit Categories below)
- Semantic Audit (Category 8): For each project document, delegate to ln-601-semantic-content-auditor
- Score: Calculate X/10 per category (including semantic scores from ln-601)
- Report: Output findings and recommended actions
Phase 4: Semantic Audit Delegation
For each project document (excluding tasks/, reference/, presentation/):
FOR doc IN [CLAUDE.md, docs/README.md, docs/project/*.md]:
result = DELEGATE ln-601-semantic-content-auditor {
doc_path: doc,
project_root: project_root,
tech_stack: detected_stack
}
semantic_findings.append(result.findings)
semantic_scores[doc] = result.scores
Target documents: CLAUDE.md, docs/README.md, docs/documentation_standards.md, docs/principles.md, docs/project/*.md
Excluded: docs/tasks/, docs/reference/, docs/presentation/, tests/
Audit Categories
| # |
Category |
What to Check |
| 1 |
Hierarchy & Links |
CLAUDE.md is root; all docs reachable via links; no orphaned files; no broken links |
| 2 |
Single Source of Truth |
No content duplication; duplicates replaced with links to source; clear ownership |
| 3 |
Proactive Compression |
Eliminate verbose/redundant content; prose→tables; remove meaningless info; compress even under-limit files; see size_limits.md |
| 4 |
Requirements Compliance |
Correct sections; within size limits; no code blocks (tables/ASCII diagrams/text only); stack-appropriate doc links |
| 5 |
Actuality (CRITICAL) |
Verify facts against code: paths exist, functions match, APIs work, configs valid; outdated docs are worse than none |
| 6 |
Legacy Cleanup |
No history sections; no "was changed" notes; no deprecated info; current state only |
| 7 |
Stack Adaptation |
Links/refs match project stack; no Python examples in .NET project; official docs for correct platform |
| 8 |
Semantic Content |
Delegated to ln-601: Content matches SCOPE; serves project goals; descriptions match actual code behavior; architecture/API docs reflect reality |
Output Format
## Documentation Audit Report - [DATE]
### Compliance Score
| Category | Score | Issues |
|----------|-------|--------|
| Hierarchy & Links | X/10 | N issues found |
| Single Source of Truth | X/10 | N duplications |
| Proactive Compression | X/10 | N compression opportunities |
| Requirements Compliance | X/10 | N violations |
| Actuality | X/10 | N mismatches with code |
| Legacy Cleanup | X/10 | N legacy items |
| Stack Adaptation | X/10 | N stack mismatches |
| Semantic Content | X/10 | N semantic issues (via ln-601) |
| **Overall** | **X/10** | |
### Critical Findings
- [ ] **[Category]** `path/file.md:line` - Issue description. **Action:** Fix suggestion.
### Recommended Actions
| Priority | Action | Location | Category |
|----------|--------|----------|----------|
| High | Remove duplicate section | docs/X.md | SSOT |
| Medium | Add link to CLAUDE.md | docs/Y.md | Hierarchy |
Scoring Algorithm
MANDATORY READ: Load shared/references/audit_scoring.md for unified scoring formula.
Severity mapping:
| Issue Type |
Severity |
| Outdated content (code mismatch) |
CRITICAL |
| Broken links, orphaned docs |
HIGH |
| Semantic mismatch (via ln-601) |
HIGH |
| Content duplication |
MEDIUM |
| Missing compression opportunity |
LOW |
Reference Files
- Size limits and targets: references/size_limits.md
- Detailed checklist: references/audit_checklist.md
Critical Notes
- Fix content, not rules: NEVER modify standards/rules files (*_standards.md, *_rules.md, *_limits.md) to make violations pass. Always fix the violating files instead.
- Verify facts against code: Actively check every path, function name, API, config mentioned in docs. Run commands. Outdated docs mislead - they're worse than no docs.
- Compress always: Size limits are upper bounds, not targets. A 100-line file instead of 300 is a win. Always look for compression opportunities.
- Meaningless content: Remove filler words, obvious statements, over-explanations. If it doesn't add value, delete it.
- No code in docs: Documents describe algorithms in tables or ASCII diagrams. Code belongs in codebase.
- Forbidden: Code blocks, implementation snippets
- Allowed: Tables, ASCII diagrams, Mermaid, method signatures (1 line)
- Instead of code: "See Official docs" or "See src/file.cs:42"
- Format Priority: Tables/ASCII > Lists (enumerations only) > Text (last resort)
- Stack adaptation: Verify all documentation references match project stack. .NET project must not have Python examples. Check official doc links point to correct platform (Microsoft docs for C#, MDN for JS, etc.)
- Code is truth: When docs contradict code, always update docs. Never "fix" code to match documentation.
- SSOT re-verification after fixes: After making ANY documentation change, re-check that the fix maintains Single Source of Truth. If content exists in multiple files, keep it in the canonical source only and replace other occurrences with a link to that source (e.g.,
See [section](path#anchor)). Never duplicate content inline — always link. Canonical source hierarchy: CLAUDE.md → docs/README.md → docs/project/.md → docs/reference/.md.
- Delete, don't archive: Legacy content should be removed, not moved to "archive"
- No history: Documents describe current state only; git tracks history
Version: 4.0.0
Last Updated: 2026-01-28
1---2name: ln-600-docs-auditor-33description: Audit project documentation quality across 8 categories (Hierarchy, SSOT, Compactness, Requirements, Actuality, Legacy, Stack Adaptation, Semantic Content). Delegates to ln-601 for deep semantic verification of project documents. Use when documentation needs quality review, after major doc updates, or as part of ln-100-documents-pipeline. Outputs Compliance Score X/10 per category + Findings + Recommended Actions.4metadata:5 source: https://skillmd.com/skills/majiayu000/ln-600-docs-auditor-36---78# Documentation Auditor910Audit project documentation quality. Universal for any tech stack.1112## Purpose1314- **Proactively compress** - find all opportunities to reduce size while preserving value15- Eliminate meaningless, redundant, and verbose content16- Convert prose to structured formats (tables, lists)17- Verify documentation hierarchy with CLAUDE.md as root18- Detect duplication and enforce Single Source of Truth19- Ensure docs match current code state20- **Semantic verification** - delegate to ln-601 to verify content matches SCOPE and codebase reality2122## Invocation2324- **Direct:** User invokes for documentation quality review25- **Pipeline:** Called by ln-100-documents-pipeline (Phase 5, if auditDocs=true)2627## Workflow28291. **Scan:** Find all .md files in project (CLAUDE.md, README.md, docs/**)302. **Build Tree:** Construct hierarchy from CLAUDE.md outward links313. **Audit Categories 1-7:** Run structural checks (see Audit Categories below)324. **Semantic Audit (Category 8):** For each project document, delegate to ln-601-semantic-content-auditor335. **Score:** Calculate X/10 per category (including semantic scores from ln-601)346. **Report:** Output findings and recommended actions3536### Phase 4: Semantic Audit Delegation3738For each project document (excluding tasks/, reference/, presentation/):3940```41FOR doc IN [CLAUDE.md, docs/README.md, docs/project/*.md]:42 result = DELEGATE ln-601-semantic-content-auditor {43 doc_path: doc,44 project_root: project_root,45 tech_stack: detected_stack46 }47 semantic_findings.append(result.findings)48 semantic_scores[doc] = result.scores49```5051**Target documents:** CLAUDE.md, docs/README.md, docs/documentation_standards.md, docs/principles.md, docs/project/*.md5253**Excluded:** docs/tasks/, docs/reference/, docs/presentation/, tests/5455## Audit Categories5657| # | Category | What to Check |58|---|----------|---------------|59| 1 | **Hierarchy & Links** | CLAUDE.md is root; all docs reachable via links; no orphaned files; no broken links |60| 2 | **Single Source of Truth** | No content duplication; duplicates replaced with links to source; clear ownership |61| 3 | **Proactive Compression** | Eliminate verbose/redundant content; prose→tables; remove meaningless info; compress even under-limit files; see [size_limits.md](references/size_limits.md) |62| 4 | **Requirements Compliance** | Correct sections; within size limits; **no code blocks** (tables/ASCII diagrams/text only); stack-appropriate doc links |63| 5 | **Actuality (CRITICAL)** | **Verify facts against code:** paths exist, functions match, APIs work, configs valid; outdated docs are worse than none |64| 6 | **Legacy Cleanup** | No history sections; no "was changed" notes; no deprecated info; current state only |65| 7 | **Stack Adaptation** | Links/refs match project stack; no Python examples in .NET project; official docs for correct platform |66| 8 | **Semantic Content** | **Delegated to ln-601:** Content matches SCOPE; serves project goals; descriptions match actual code behavior; architecture/API docs reflect reality |6768## Output Format6970```markdown71## Documentation Audit Report - [DATE]7273### Compliance Score7475| Category | Score | Issues |76|----------|-------|--------|77| Hierarchy & Links | X/10 | N issues found |78| Single Source of Truth | X/10 | N duplications |79| Proactive Compression | X/10 | N compression opportunities |80| Requirements Compliance | X/10 | N violations |81| Actuality | X/10 | N mismatches with code |82| Legacy Cleanup | X/10 | N legacy items |83| Stack Adaptation | X/10 | N stack mismatches |84| Semantic Content | X/10 | N semantic issues (via ln-601) |85| **Overall** | **X/10** | |8687### Critical Findings8889- [ ] **[Category]** `path/file.md:line` - Issue description. **Action:** Fix suggestion.9091### Recommended Actions9293| Priority | Action | Location | Category |94|----------|--------|----------|----------|95| High | Remove duplicate section | docs/X.md | SSOT |96| Medium | Add link to CLAUDE.md | docs/Y.md | Hierarchy |97```9899## Scoring Algorithm100101**MANDATORY READ:** Load `shared/references/audit_scoring.md` for unified scoring formula.102103**Severity mapping:**104105| Issue Type | Severity |106|------------|----------|107| Outdated content (code mismatch) | CRITICAL |108| Broken links, orphaned docs | HIGH |109| Semantic mismatch (via ln-601) | HIGH |110| Content duplication | MEDIUM |111| Missing compression opportunity | LOW |112113## Reference Files114115- Size limits and targets: [references/size_limits.md](references/size_limits.md)116- Detailed checklist: [references/audit_checklist.md](references/audit_checklist.md)117118## Critical Notes119120- **Fix content, not rules:** NEVER modify standards/rules files (*_standards.md, *_rules.md, *_limits.md) to make violations pass. Always fix the violating files instead.121- **Verify facts against code:** Actively check every path, function name, API, config mentioned in docs. Run commands. Outdated docs mislead - they're worse than no docs.122- **Compress always:** Size limits are upper bounds, not targets. A 100-line file instead of 300 is a win. Always look for compression opportunities.123- **Meaningless content:** Remove filler words, obvious statements, over-explanations. If it doesn't add value, delete it.124- **No code in docs:** Documents describe algorithms in tables or ASCII diagrams. Code belongs in codebase.125 - **Forbidden:** Code blocks, implementation snippets126 - **Allowed:** Tables, ASCII diagrams, Mermaid, method signatures (1 line)127 - **Instead of code:** "See [Official docs](url)" or "See [src/file.cs:42](path#L42)"128- **Format Priority:** Tables/ASCII > Lists (enumerations only) > Text (last resort)129- **Stack adaptation:** Verify all documentation references match project stack. .NET project must not have Python examples. Check official doc links point to correct platform (Microsoft docs for C#, MDN for JS, etc.)130- **Code is truth:** When docs contradict code, always update docs. Never "fix" code to match documentation.131- **SSOT re-verification after fixes:** After making ANY documentation change, re-check that the fix maintains Single Source of Truth. If content exists in multiple files, keep it in the canonical source only and replace other occurrences with a link to that source (e.g., `See [section](path#anchor)`). Never duplicate content inline — always link. Canonical source hierarchy: CLAUDE.md → docs/README.md → docs/project/*.md → docs/reference/*.md.132- **Delete, don't archive:** Legacy content should be removed, not moved to "archive"133- **No history:** Documents describe current state only; git tracks history134135---136**Version:** 4.0.0137**Last Updated:** 2026-01-28