majiayu000 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
- Read document header and top sections first
- Parse:
SCOPEDOC_KINDDOC_ROLEREAD_WHENSKIP_WHENPRIMARY_SOURCES
- If no SCOPE tag, infer from document type
- Infer expected
DOC_KINDfrom the shared contract when missing - 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_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