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

1. Read document first 20 lines
2. Parse <!-- SCOPE: ... --> comment
3. If no SCOPE tag, infer from document type (see Verification Rules)
4. 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