Paths: File paths (

shared/

,

references/

,

../ln-*

) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

Documentation Auditor (L2 Coordinator)

Purpose & Scope

• Coordinates 4 audit workers running in parallel:
  • ln-611 (documentation structure) — 1 invocation
  • ln-612 (semantic content) — N invocations (per target document)
  • ln-613 (code comments) — 1 invocation
  • ln-614 (fact verification) — 1 invocation
• Detect project type + tech stack ONCE
• Pass shared context to all workers (token-efficient)
• Aggregate worker results into single consolidated report
• Write report to

  docs/project/docs_audit.md

  (file-based, no task creation)
• Manual invocation by user or called by ln-100-documents-pipeline

Workflow

1. Discovery: Detect project type, tech stack, scan .md files
2. Context Build: Build contextStore with output_dir, project_root, tech_stack
3. Prepare Output: Create output directory
4. Delegate: Invoke 4 workers in parallel
5. Aggregate: Collect worker results, calculate overall score
6. Context Validation: Post-filter findings
7. Write Report: Save to

   docs/project/docs_audit.md

Phase 1: Discovery

• CLAUDE.md

  — root of documentation hierarchy

• docs/README.md

  — documentation index
• Package manifests:

  package.json

  ,

  requirements.txt

  ,

  go.mod

  ,

  Cargo.toml

• Existing docs in

  docs/project/

• Programming language(s)
• Major frameworks/libraries
• List of

  .md

  files in project (for ln-611 hierarchy check)
• Target documents for semantic audit (for ln-612)

FOR doc IN [CLAUDE.md, docs/README.md, docs/documentation_standards.md,
            docs/principles.md, docs/project/*.md]:
  IF doc exists AND doc NOT IN [docs/tasks/*, docs/reference/*, docs/presentation/*]:
    semantic_targets.append(doc)

Phase 2: Build contextStore

{
  "tech_stack": {"language": "...", "frameworks": [...]},
  "project_root": "...",
  "output_dir": "docs/project/.audit/ln-610/{YYYY-MM-DD}"
}

{YYYY-MM-DD}

2026-03-01

Phase 3: Prepare Output

mkdir -p {output_dir}

Phase 4: Delegate to Workers

{output_dir}/611-structure.md

{output_dir}/612-semantic-{doc-slug}.md

{output_dir}/613-code-comments.md

{output_dir}/614-fact-checker.md

doc_path

Report written: ... | Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

Phase 5: Aggregate Results

1. Parse scores from worker return values
2. Read worker reports from

   {output_dir}/

   for detailed findings
3. Calculate category scores:

1. Calculate overall score: weighted average of 4 categories

Phase 6: Context Validation (Post-Filter)

shared/references/context_validation.md

FOR EACH finding WHERE severity IN (HIGH, MEDIUM):
  # Rule 1: ADR/Planned Override
  IF finding matches ADR → advisory "[Planned: ADR-XXX]"

  # Doc-specific: Compression context (from ln-611)
  IF Structure finding Cat 3 (Compression):
    - Skip if path in references/ or templates/ (reference docs = naturally large)
    - Skip if filename contains architecture/design/api_spec
    - Skip if tables+lists > 50% of content (already structured)

  # Fact-checker: Example/template path exclusion (from ln-614)
  IF Fact finding (PATH_NOT_FOUND):
    - Path in examples/ or templates/ directory reference → advisory
    - Path has placeholder pattern (YOUR_*, <project>, {name}) → remove

  # Fact-checker: Planned feature claims (from ln-614)
  IF Fact finding (ENTITY_NOT_FOUND, ENDPOINT_NOT_FOUND):
    - Entity mentioned in ADR/roadmap as planned → advisory "[Planned: ADR-XXX]"

  # Fact-checker: Cross-doc contradiction authority (from ln-614)
  IF Fact finding (CROSS_DOC_*_CONFLICT):
    - docs/project/ is authority over docs/reference/ → report reference doc

  # Comment-specific: Per-category density targets (from ln-613)
  IF Comment finding Cat 2 (Density):
    - test/ or tests/ → target density 2-10%
    - infra/ or config/ or ci/ → target density 5-15%
    - business/domain/services → target density 15-25%
    Recalculate with per-category target.

  # Comment-specific: Complexity context for WHY-not-WHAT (from ln-613)
  IF Comment finding Cat 1 (WHY not WHAT):
    - If file McCabe complexity > 15 → WHAT comments acceptable
    - If file in domain/ or business/ → explanatory comments OK

Downgraded findings → "Advisory Findings" section in report.

Phase 7: Write Report

docs/project/docs_audit.md

## Documentation Audit Report - {DATE}

### Overall Score: X.X/10

| Category | Score | Worker | Issues |
|----------|-------|--------|--------|
| Documentation Structure | X/10 | ln-611 | N issues |
| Semantic Content | X/10 | ln-612 | N issues (across M docs) |
| Code Comments | X/10 | ln-613 | N issues |
| Fact Accuracy | X/10 | ln-614 | N issues |

### Critical Findings

- [ ] **[Category]** `path/file:line` - Issue. **Action:** Fix suggestion.

### Advisory Findings

(Context-validated findings downgraded from MEDIUM/HIGH)

### Recommended Actions

| Priority | Action | Location | Category |
|----------|--------|----------|----------|
| High | ... | ... | ... |

Scoring Algorithm

shared/references/audit_scoring.md

Critical Notes

• Pure coordinator: Does NOT perform any audit checks directly. ALL auditing delegated to workers.
• Fix content, not rules: NEVER modify standards/rules files to make violations pass
• Fact verification via ln-614: Dedicated worker extracts and verifies all claims across ALL docs
• Compress always: Size limits are upper bounds, not targets
• No code in docs: Documents describe algorithms in tables or ASCII diagrams
• Code is truth: When docs contradict code, always update docs
• Delete, don't archive: Legacy content removed, not archived

Definition of Done

• Project metadata discovered (tech stack, doc list)
• contextStore built with output_dir =

  docs/project/.audit/ln-610/{YYYY-MM-DD}

• Output directory created (no deletion of previous runs)
• All 4 workers invoked and completed
• Worker reports aggregated: 4 category scores + overall
• Context Validation applied to all findings
• Consolidated report written to

  docs/project/docs_audit.md

Reference Files

• Context validation rules:

  shared/references/context_validation.md

• Audit scoring formula:

  shared/references/audit_scoring.md

• Worker report template:

  shared/templates/audit_worker_report_template.md

• Task delegation pattern:

  shared/references/task_delegation_pattern.md