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.

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 <!-- SCOPE: ... --> 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

MANDATORY READ: Load references/verification_rules.md for 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