Semantic Content Auditor (L3 Worker)

Specialized worker auditing semantic accuracy of project documentation.

Purpose & Scope

Worker in ln-600 coordinator pipeline - invoked by ln-600-docs-auditor for each project document
Verify document content matches stated SCOPE (document purpose)
Check content aligns with project goals (value contribution)
Validate facts against codebase (accuracy and freshness)
Return structured findings to coordinator with severity, location, fix suggestions

Target Documents

Called ONLY for project documents (not reference/tasks):

| Document | Verification Focus | |----------|-------------------| | CLAUDE.md | Instructions match project structure, paths valid | | docs/README.md | Navigation accurate, descriptions match reality | | docs/documentation_standards.md | Standards applicable to this project | | docs/principles.md | Principles reflected in actual code patterns | | docs/project/requirements.md | Requirements implemented or still valid | | docs/project/architecture.md | Architecture matches actual code structure | | docs/project/tech_stack.md | Versions/technologies match package files | | docs/project/api_spec.md | Endpoints/contracts match controllers | | docs/project/database_schema.md | Schema matches actual DB/migrations | | docs/project/design_guidelines.md | Components/styles exist in codebase | | docs/project/runbook.md | Commands work, paths valid |

Excluded: docs/tasks/, docs/reference/, docs/presentation/, tests/

Inputs (from Coordinator)

{
  "doc_path": "docs/project/architecture.md",
  "project_root": "/path/to/project",
  "tech_stack": {
    "language": "TypeScript",
    "frameworks": ["Express", "React"]
  }
}

Workflow

Phase 1: SCOPE EXTRACTION

Read document first 20 lines
Parse  comment
If no SCOPE tag, infer from document type (see Verification Rules)
Record stated purpose/boundaries

Phase 2: CONTENT-SCOPE ALIGNMENT

Analyze document sections against stated scope:

| Check | Finding Type | |-------|--------------| | Section not serving scope | OFF_TOPIC | | Scope aspect not covered | MISSING_COVERAGE | | Excessive detail beyond scope | SCOPE_CREEP | | Content duplicated elsewhere | SSOT_VIOLATION |

Scoring:

10/10: All content serves scope, scope fully covered
8-9/10: Minor off-topic content or small gaps
6-7/10: Some sections not aligned, partial coverage
4-5/10: Significant misalignment, major gaps
1-3/10: Document does not serve its stated purpose

Phase 3: FACT VERIFICATION

Per document type, verify claims against codebase:

| Document | Verification Method | |----------|---------------------| | architecture.md | Check layers exist (Glob for folders), verify imports follow described pattern (Grep) | | tech_stack.md | Compare versions with package.json, go.mod, requirements.txt | | api_spec.md | Match endpoints with controller/route files (Grep for routes) | | requirements.md | Search for feature implementations (Grep for keywords) | | database_schema.md | Compare with migration files or Prisma/TypeORM schemas | | runbook.md | Validate file paths exist (Glob), test command syntax | | principles.md | Sample code files for principle adherence patterns | | CLAUDE.md | Verify referenced paths/files exist |

Finding Types:

OUTDATED_PATH: File/folder path no longer exists
WRONG_VERSION: Documented version differs from package file
MISSING_ENDPOINT: Documented API endpoint not found in code
BEHAVIOR_MISMATCH: Described behavior differs from implementation
STALE_REFERENCE: Reference to removed/renamed entity

Scoring:

10/10: All facts verified against code
8-9/10: Minor inaccuracies (typos, formatting)
6-7/10: Some paths/names outdated, core info correct
4-5/10: Functional mismatches (wrong behavior described)
1-3/10: Critical mismatches (architecture wrong, APIs broken)

Phase 4: SCORING & REPORT

Calculate final scores and compile findings:

scope_alignment_score = weighted_average(coverage, relevance, focus)
fact_accuracy_score = (verified_facts / total_facts) * 10

overall_score = (scope_alignment * 0.4) + (fact_accuracy * 0.6)

Fact accuracy weighted higher because incorrect information is worse than scope drift.

Output Format

Return JSON to coordinator:

{
  "doc_path": "docs/project/architecture.md",
  "scope": {
    "stated": "System architecture with C4 diagrams, component interactions",
    "coverage_percent": 85
  },
  "scores": {
    "scope_alignment": 8,
    "fact_accuracy": 6,
    "overall": 7
  },
  "summary": {
    "total_issues": 4,
    "high": 1,
    "medium": 2,
    "low": 1
  },
  "findings": [
    {
      "severity": "HIGH",
      "type": "BEHAVIOR_MISMATCH",
      "location": "line 45",
      "issue": "Architecture shows 3-tier (Controller->Service->Repository) but code has Controller->Repository direct calls",
      "evidence": "src/controllers/UserController.ts:23 imports UserRepository directly",
      "fix": "Update diagram to show actual pattern OR refactor code to match docs"
    },
    {
      "severity": "MEDIUM",
      "type": "OUTDATED_PATH",
      "location": "line 78",
      "issue": "References src/services/legacy/ which was removed",
      "evidence": "Folder does not exist: ls src/services/legacy/ returns error",
      "fix": "Remove reference or update to current path"
    }
  ]
}

Verification Rules by Document Type

See references/verification_rules.md for detailed per-document verification patterns.

Critical Rules

Read before judge: Always read full document and relevant code before reporting issues
Evidence required: Every finding must include evidence field with verification command/result
Code is truth: When docs contradict code, document is wrong (unless code is a bug)
Scope inference: If no SCOPE tag, use document filename to infer expected scope
No false positives: Better to miss an issue than report incorrectly
Location precision: Always include line number for findings
Actionable fixes: Every finding must have concrete fix suggestion

Definition of Done

Document read completely
SCOPE extracted or inferred
Content-scope alignment analyzed
Facts verified against codebase (with evidence)
Both scores calculated
JSON result returned to coordinator

Version: 1.0.0 Last Updated: 2026-01-28