ln-612-semantic-content-auditor（ln 612 语义内容审核员）

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. If shared/ is missing, fetch files via WebFetch from https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}.

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 shared/references/audit_worker_core_contract.md, shared/references/docs_quality_contract.md, and shared/references/markdown_read_protocol.md. MANDATORY READ: Load shared/references/mcp_tool_preferences.md and shared/references/mcp_integration_patterns.md

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

1. If no SCOPE tag, infer from document type
2. Infer expected DOC_KIND from the shared contract when missing
3. 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 shared/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 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 JSON summary per shared/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 shared/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

MANDATORY READ: Load shared/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

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

Version: 2.0.0 Last Updated: 2026-03-01