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

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:

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:

Analyze the document against stated scope and kind:

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

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_COVERAGE, SCOPE_CREEP, SSOT_VIOLATION)
• Semantic judgment applied according to DOC_KIND
• Score calculated using penalty algorithm
• Report written to {output_dir}/ln-612--{doc-slug}.md (atomic single Write call)
• Summary written per contract

Reference Files

• Audit output schema: references/audit_output_schema.md

Version: 2.0.0 Last Updated: 2026-03-01