Paths: File paths (references/, ../ln-*) are relative to this skill directory.
Documentation Structure Auditor (L3 Worker)
Type: L3 Worker
Specialized worker auditing structural quality of project documentation.
Purpose & Scope
- Audit documentation for structural quality across 8 categories
- Scan all
.md files in project, build hierarchy from AGENTS.md when present
- Return structured findings to coordinator with severity, location, recommendations
- Calculate compliance score (X/10) for Documentation Structure
Inputs
MANDATORY READ: Load references/audit_worker_core_contract.md, references/docs_quality_contract.md, references/markdown_read_protocol.md, and references/mcp_tool_preferences.md.
Optional rule catalog: load references/docs_quality_rules.json only when exact rule IDs, path matrices, or allowlisted placeholder exceptions are needed.
Tool policy: You may run as an isolated subagent where host AGENTS.md is not in scope, so default to hex-line MCP first for file reads, search, and edits. Load references/mcp_integration_patterns.md only when MCP behavior is unclear.
Receives contextStore with: tech_stack, project_root, output_dir.
hex-line is optional for this doc-only worker. Use it as an accelerator for large markdown outlines and targeted reads when available; otherwise continue with built-in Read/Grep/Glob/Bash.
Workflow
- Parse Context: Extract tech stack, project root, output_dir from contextStore
- Load Registry if Present: Use
docs/project/.context/doc_registry.json as the first routing source when available
- Scan Docs: Find all
.md files in project (AGENTS.md, CLAUDE.md, README.md, docs/**)
- Read Section-First: For larger docs, outline first, then read header markers +
Quick Navigation + Agent Entry + Maintenance
- Build Tree: Construct hierarchy from
AGENTS.md outward links when present, otherwise from CLAUDE.md
- Audit Categories 1-7: Run structural checks (see Audit Categories below)
- Collect Findings: Record each violation with severity, location (file:line), effort estimate (S/M/L), recommendation
- Calculate Score: Count violations by severity, calculate compliance score (X/10)
- Write Report: Build full markdown report per
references/templates/audit_worker_report_template.md, write to {output_dir}/611-structure.md in single Write call
- Return Summary: Return minimal summary to coordinator (see Output Format)
Audit Categories
| # |
Category |
What to Check |
| 1 |
Hierarchy & Links |
AGENTS.md is canonical root when present; all docs reachable via links; no orphaned files; no broken links |
| 2 |
Single Source of Truth |
No content duplication; duplicates replaced with links to source; clear ownership |
| 3 |
Proactive Compression |
Eliminate verbose/redundant content; prose to tables; remove meaningless info; compress even under-limit files; see size_limits.md |
| 4 |
Requirements Compliance |
Correct header markers, correct top sections, within size limits, no illegal code blocks, stack-appropriate doc links |
| 5 |
Freshness Indicators |
Detect staleness signals: dates >6 months in content, unsupported API/tool references, TODO/FIXME markers, placeholder text left in place; deep fact-checking handled by dedicated worker |
| 6 |
Legacy Cleanup |
No history sections; no "was changed" notes; no unsupported info; current state only |
| 7 |
Stack Adaptation |
Links/refs match project stack; no Python examples in .NET project; official docs for correct platform |
| 8 |
Import Pattern Compliance |
When AGENTS.md exists at repo root, CLAUDE.md must contain exactly one @AGENTS.md line and a bounded harness-specific delta (≤50 lines total). Any content in CLAUDE.md that duplicates AGENTS.md is drift. See references/agent_instructions_writing_guide.md for rationale |
Severity Mapping
| Issue Type |
Severity |
| Staleness indicators (old dates, unsupported refs, TODO markers) |
MEDIUM |
| Broken links, orphaned docs |
HIGH |
| Content duplication |
MEDIUM |
| Missing compression opportunity |
LOW |
| Legacy/history content |
MEDIUM |
| Wrong stack references |
HIGH |
Import pattern drift (duplicated AGENTS.md content in CLAUDE.md, oversized stub, missing @AGENTS.md line) |
HIGH |
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}/611-structure.md with category: "Documentation Structure" and checks: hierarchy_links, ssot, compression, requirements_compliance, freshness_indicators, legacy_cleanup, stack_adaptation, import_pattern_compliance.
Return summary per references/audit_summary_contract.md.
Standalone mode still writes the same JSON summary to a worker-owned run-scoped artifact path per shared contract.
Critical Rules
Apply the already-loaded references/audit_worker_core_contract.md.
- Do not auto-fix: Report violations only; coordinator aggregates for user
- Tech stack aware: Use contextStore
tech_stack to apply stack-specific checks (e.g., .NET vs Node.js doc standards)
- No deep fact-checking: Detect staleness signals only (dates, unsupported refs, TODO markers)
- Compress always: Size limits are upper bounds, not targets. A 100-line file instead of 300 is a win
- No code in docs: Documents describe algorithms in tables or ASCII diagrams. Code belongs in codebase
- Code is truth: When docs contradict code, report docs as needing update (not code)
- Delete, don't archive: Legacy content should be removed, not moved to "archive"
- Location precision: Always include
file:line for programmatic navigation
- Shared contract precedence: Placeholder policy, template-metadata policy, and no-code exceptions come from
docs_quality_contract.md / docs_quality_rules.json
Definition of Done
Apply the already-loaded references/audit_worker_core_contract.md.
Reference Files
- Size limits and targets: references/size_limits.md
- Detailed checklist: references/audit_checklist.md
Version: 1.0.0
Last Updated: 2026-03-01
1---2name: ln-611-docs-structure-auditor3description: Checks hierarchy, links, SSOT, compression, requirements compliance, freshness, legacy cleanup. Use when auditing documentation structure.4license: MIT5---67> **Paths:** File paths (`references/`, `../ln-*`) are relative to this skill directory.89# Documentation Structure Auditor (L3 Worker)1011**Type:** L3 Worker1213Specialized worker auditing structural quality of project documentation.1415## Purpose & Scope1617- Audit documentation for **structural quality** across 8 categories18- Scan all `.md` files in project, build hierarchy from `AGENTS.md` when present19- Return structured findings to coordinator with severity, location, recommendations20- Calculate compliance score (X/10) for Documentation Structure2122## Inputs2324**MANDATORY READ:** Load `references/audit_worker_core_contract.md`, `references/docs_quality_contract.md`, `references/markdown_read_protocol.md`, and `references/mcp_tool_preferences.md`.25Optional rule catalog: load `references/docs_quality_rules.json` only when exact rule IDs, path matrices, or allowlisted placeholder exceptions are needed.26Tool policy: You may run as an isolated subagent where host `AGENTS.md` is not in scope, so default to hex-line MCP first for file reads, search, and edits. Load `references/mcp_integration_patterns.md` only when MCP behavior is unclear.2728Receives `contextStore` with: `tech_stack`, `project_root`, `output_dir`.2930`hex-line` is optional for this doc-only worker. Use it as an accelerator for large markdown outlines and targeted reads when available; otherwise continue with built-in `Read/Grep/Glob/Bash`.3132## Workflow33341) **Parse Context:** Extract tech stack, project root, output_dir from contextStore352) **Load Registry if Present:** Use `docs/project/.context/doc_registry.json` as the first routing source when available363) **Scan Docs:** Find all `.md` files in project (`AGENTS.md`, `CLAUDE.md`, `README.md`, `docs/**`)374) **Read Section-First:** For larger docs, outline first, then read header markers + `Quick Navigation` + `Agent Entry` + `Maintenance`385) **Build Tree:** Construct hierarchy from `AGENTS.md` outward links when present, otherwise from `CLAUDE.md`396) **Audit Categories 1-7:** Run structural checks (see Audit Categories below)407) **Collect Findings:** Record each violation with severity, location (file:line), effort estimate (S/M/L), recommendation418) **Calculate Score:** Count violations by severity, calculate compliance score (X/10)429) **Write Report:** Build full markdown report per `references/templates/audit_worker_report_template.md`, write to `{output_dir}/611-structure.md` in single Write call4310) **Return Summary:** Return minimal summary to coordinator (see Output Format)4445## Audit Categories4647| # | Category | What to Check |48|---|----------|---------------|49| 1 | **Hierarchy & Links** | `AGENTS.md` is canonical root when present; all docs reachable via links; no orphaned files; no broken links |50| 2 | **Single Source of Truth** | No content duplication; duplicates replaced with links to source; clear ownership |51| 3 | **Proactive Compression** | Eliminate verbose/redundant content; prose to tables; remove meaningless info; compress even under-limit files; see [size_limits.md](references/size_limits.md) |52| 4 | **Requirements Compliance** | Correct header markers, correct top sections, within size limits, no illegal code blocks, stack-appropriate doc links |53| 5 | **Freshness Indicators** | Detect staleness signals: dates >6 months in content, unsupported API/tool references, TODO/FIXME markers, placeholder text left in place; deep fact-checking handled by dedicated worker |54| 6 | **Legacy Cleanup** | No history sections; no "was changed" notes; no unsupported info; current state only |55| 7 | **Stack Adaptation** | Links/refs match project stack; no Python examples in .NET project; official docs for correct platform |56| 8 | **Import Pattern Compliance** | When `AGENTS.md` exists at repo root, `CLAUDE.md` must contain exactly one `@AGENTS.md` line and a bounded harness-specific delta (≤50 lines total). Any content in CLAUDE.md that duplicates AGENTS.md is drift. See `references/agent_instructions_writing_guide.md` for rationale |5758### Severity Mapping5960| Issue Type | Severity |61|------------|----------|62| Staleness indicators (old dates, unsupported refs, TODO markers) | MEDIUM |63| Broken links, orphaned docs | HIGH |64| Content duplication | MEDIUM |65| Missing compression opportunity | LOW |66| Legacy/history content | MEDIUM |67| Wrong stack references | HIGH |68| Import pattern drift (duplicated AGENTS.md content in CLAUDE.md, oversized stub, missing `@AGENTS.md` line) | HIGH |6970## Scoring Algorithm7172**MANDATORY READ:** Load `references/audit_scoring.md`.7374## Output Format7576**MANDATORY READ:** Load `references/templates/audit_worker_report_template.md`.7778Write 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.7980Write report to `{output_dir}/611-structure.md` with `category: "Documentation Structure"` and checks: hierarchy_links, ssot, compression, requirements_compliance, freshness_indicators, legacy_cleanup, stack_adaptation, import_pattern_compliance.8182Return summary per `references/audit_summary_contract.md`.8384Standalone mode still writes the same JSON summary to a worker-owned run-scoped artifact path per shared contract.8586## Critical Rules8788Apply the already-loaded `references/audit_worker_core_contract.md`.8990- **Do not auto-fix:** Report violations only; coordinator aggregates for user91- **Tech stack aware:** Use contextStore `tech_stack` to apply stack-specific checks (e.g., .NET vs Node.js doc standards)92- **No deep fact-checking:** Detect staleness signals only (dates, unsupported refs, TODO markers)93- **Compress always:** Size limits are upper bounds, not targets. A 100-line file instead of 300 is a win94- **No code in docs:** Documents describe algorithms in tables or ASCII diagrams. Code belongs in codebase95- **Code is truth:** When docs contradict code, report docs as needing update (not code)96- **Delete, don't archive:** Legacy content should be removed, not moved to "archive"97- **Location precision:** Always include `file:line` for programmatic navigation98- **Shared contract precedence:** Placeholder policy, template-metadata policy, and no-code exceptions come from `docs_quality_contract.md` / `docs_quality_rules.json`99100## Definition of Done101102Apply the already-loaded `references/audit_worker_core_contract.md`.103104- [ ] contextStore parsed successfully (including output_dir)105- [ ] All 8 structural categories audited106- [ ] Findings collected with severity, location, effort, recommendation107- [ ] Score calculated using penalty algorithm108- [ ] Report written to `{output_dir}/611-structure.md` (atomic single Write call)109- [ ] Summary written per contract110111## Reference Files112113- Size limits and targets: [references/size_limits.md](references/size_limits.md)114- Detailed checklist: [references/audit_checklist.md](references/audit_checklist.md)115116---117**Version:** 1.0.0118**Last Updated:** 2026-03-01
tuyv