ln-612-semantic-content-auditor

What this skill does

> **Paths:** File paths (`references/`, `../ln-*`) are relative to this skill directory.

# Semantic Content Auditor (L3 Worker)

**Type:** L3 Worker

Specialized worker auditing semantic fitness of project documentation.

## Purpose & Scope

- Verify document content matches stated SCOPE and declared document kind
- 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 |
|----------|-------------------|
| `AGENTS.md` / `CLAUDE.md` | Entry instructions stay scoped, navigable, and free of 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

**MANDATORY READ:** Load `references/audit_worker_core_contract.md`, `references/docs_quality_contract.md`, and `references/markdown_read_protocol.md`.
Tool policy: follow host AGENTS.md MCP preferences; load `references/mcp_tool_preferences.md` and `references/mcp_integration_patterns.md` only when host policy is absent or MCP behavior is unclear.

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 |

`hex-line` is optional for this doc-only worker. Use it to outline large markdown files when available; otherwise continue with built-in `Read/Grep/Glob/Bash` and do not block on MCP availability.

## Workflow

### Phase 1: Header and Contract Extraction

1. Read document header and top sections first
2. Parse:
   - `SCOPE`
   - `DOC_KIND`
   - `DOC_ROLE`
   - `READ_WHEN`
   - `SKIP_WHEN`
   - `PRIMARY_SOURCES`
3. If no SCOPE tag, infer from document type
4. Infer expected `DOC_KIND` from the shared contract when missing
5. Record stated purpose and routing boundaries

### Phase 2: Doc-Kind-Aware Semantic Audit

Judge the document according to its kind:

| DOC_KIND | Main semantic question |
|----------|------------------------|
| `index` | Does it route efficiently and avoid deep factual overload? |
| `reference` | Is it precise, complete enough, and easy to lookup? |
| `how-to` | Is the procedure actionable and sequenced correctly? |
| `explanation` | Does it build the right mental model and rationale? |
| `record` | Does it preserve the decision trace and consequences? |

Analyze the document against stated scope and kind:

| 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 |

**Agent instruction file checks** (applies when the audited file is `AGENTS.md` or `CLAUDE.md`):

| Check | Finding Type | Severity | Recommendation |
|-------|--------------|----------|----------------|
| Style / formatting rules (indentation, quote style, trailing whitespace, naming conventions) | NOT_A_LINTER | WARN | Move to Biome, Prettier, Ruff, EditorConfig, or a Claude Code Stop hook. Instruction files are loaded into every session and cost tokens against the ~100-imperative budget; deterministic tools do this for free. |
| Conditional / non-universal rules at the root (`when working on src/api/...`, `if modifying the billing service`, `for the Z service`) | NON_UNIVERSAL_RULE | WARN | Move to `.claude/rules/*.md` with a `paths:` frontmatter filter (Anthropic built-in path scoping). Non-universal rules bias Claude Code toward ignoring the entire file via the `<system-reminder>` wrapper. |
| Self-Improvement Loop rule pointing at a manual `tasks/lessons.md` | OBSOLETE_PATTERN | WARN | Delete. Claude Code's built-in auto memory at `~/.claude/projects/<project>/memory/` already does this; a parallel hand-maintained convention wastes context. |

All three WARN only — they require human judgment (intentional style rule? conditional scope that's actually project-wide?). Cite `references/agent_instructions_writing_guide.md` in every finding.

Read strategy:
- header + top sections first
- read only the body sections needed for judgment
- read the full file only when the semantic judgment is unsafe without it

**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 `references/audit_scoring.md`.

## Output Format

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

Write JSON summary per `references/audit_summary_contract.md`. In managed mode the caller passes both `runId` and `summaryArtifactPath`; in standalone mode the worker generates its own run-scoped artifact path per shared contract.

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

With `category: "Semantic Content"` and checks: scope_alignment, not_a_linter, non_universal_rule, obsolete_pattern (the last three fire only on AGENTS.md / CLAUDE.md targets).

Return summary per `references/audit_summary_contract.md`.

When `summaryArtifactPath` is absent, write the standalone runtime summary under `.hex-skills/runtime-artifacts/runs/{run_id}/evaluation-worker/{worker}--{identifier}.json` and optionally echo the same summary in structured output.
```
Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/ln-612--architecture.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)
```

## Critical Rules

Apply the already-loaded `references/audit_worker_core_contract.md`.

- **Read progressively:** Use section-first reading; full reads only when needed for safe judgment
- **Scope inference:** If no SCOPE tag, use document filename to infer expected scope
- **Doc-kind aware:** Judge by document purpose, not one generic rubric
- **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
- **Shared class registry:** Document boundaries come from `docs_quality_contract.md`; do not invent alternate scope rules per file

## Definition of Done

Apply the already-loaded `references/audit_worker_core_contract.md`.

- [ ] Header contract extracted or inferred
- [ ] Content-scope alignment analyzed (OFF_TOPIC, MISSING_COVERAG