Ln 612 Semantic Content Auditor

---
name: ln-612-semantic-content-auditor
description: "Audits document semantic content against stated SCOPE and project goals. Checks coverage, off-topic content, SSOT. File-based report with scope_alignment score."
allowed-tools: Read, Grep, Glob, Bash
license: MIT
---

> **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-610 coordinator pipeline** - invoked by ln-610-docs-auditor for each project document
- Verify document content **matches stated SCOPE** (document purpose)
- Check content **aligns with project goals** (value contribution)
- Return structured findings to coordinator with severity, location, fix suggestions
- Does NOT verify facts against codebase

## Target Documents

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

| Document | Verification Focus |
|----------|-------------------|
| `CLAUDE.md` | Instructions serve stated purpose, no off-topic content |
| `docs/README.md` | Navigation scope correct, descriptions relevant |
| `docs/documentation_standards.md` | Standards applicable to this project type |
| `docs/principles.md` | Principles relevant to project architecture |
| `docs/project/requirements.md` | Requirements scope complete, no stale items |
| `docs/project/architecture.md` | Architecture scope covers all layers |
| `docs/project/tech_stack.md` | Stack scope matches project reality |
| `docs/project/api_spec.md` | API scope covers all endpoint groups |
| `docs/project/database_schema.md` | Schema scope covers all entities |
| `docs/project/design_guidelines.md` | Design scope covers active components |
| `docs/project/infrastructure.md` | Infrastructure scope covers all deployment targets |
| `docs/project/runbook.md` | Runbook scope covers setup + operations |

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

## Inputs (from Coordinator)

**MANDATORY READ:** Load `shared/references/audit_worker_core_contract.md`.

Receives from coordinator per invocation:

| Field | Description |
|-------|-------------|
| `doc_path` | Path to document to audit (e.g., `docs/project/architecture.md`) |
| `output_dir` | Directory for report output (from contextStore) |
| `project_root` | Project root path |
| `tech_stack` | Detected technology stack |

## 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: SCORING & REPORT

Calculate final score based on scope alignment:

```
overall_score = weighted_average(coverage, relevance, focus)
```

Coverage: how completely the scope is addressed. Relevance: how much content serves the scope. Focus: absence of off-topic content.

## Scoring Algorithm

**MANDATORY READ:** Load `shared/references/audit_worker_core_contract.md` and `shared/references/audit_scoring.md`.

## Output Format

**MANDATORY READ:** Load `shared/references/audit_worker_core_contract.md` and `shared/templates/audit_worker_report_template.md`.

Write report to `{output_dir}/612-semantic-{doc-slug}.md` where `doc-slug` is derived from document filename (e.g., `architecture`, `tech_stack`, `claude_md`).

With `category: "Semantic Content"` and checks: scope_alignment.

Return summary to coordinator:
```
Report written: docs/project/.audit/ln-610/{YYYY-MM-DD}/612-semantic-architecture.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)
```

## Critical Rules

**MANDATORY READ:** Load `shared/references/audit_worker_core_contract.md`.

- **Read before judge:** Always read full document before reporting issues
- **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
- **No fact-checking:** Do NOT verify paths, versions, endpoints against code

## Definition of Done

**MANDATORY READ:** Load `shared/references/audit_worker_core_contract.md`.

- Document read completely
- SCOPE extracted or inferred
- Content-scope alignment analyzed (OFF_TOPIC, MISSING_COVERAGE, SCOPE_CREEP, SSOT_VIOLATION)
- Score calculated using penalty algorithm
- Report written to `{output_dir}/612-semantic-{doc-slug}.md` (atomic single Write call)
- Summary returned to coordinator

## Reference Files

- **Audit output schema:** `shared/references/audit_output_schema.md`

---
**Version:** 2.0.0
**Last Updated:** 2026-03-01