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}.
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 shared/references/audit_worker_core_contract.md, shared/references/docs_quality_contract.md, shared/references/docs_quality_rules.json, and shared/references/markdown_read_protocol.md.
MANDATORY READ: Load shared/references/mcp_tool_preferences.md and shared/references/mcp_integration_patterns.md
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
shared/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, deprecated 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 deprecated 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 and GEMINI.md must each contain exactly one @AGENTS.md line and a bounded harness-specific delta (≤50 lines total per file). Any content in CLAUDE.md or GEMINI.md that duplicates AGENTS.md is drift. See shared/references/agent_instructions_writing_guide.md for rationale |
Severity Mapping
| Issue Type |
Severity |
| Staleness indicators (old dates, deprecated 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 / GEMINI.md, oversized stub, missing @AGENTS.md line) |
HIGH |
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}/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 shared/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
MANDATORY READ: Load shared/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, deprecated 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
MANDATORY READ: Load shared/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-auditor-53description: Checks hierarchy, links, SSOT, compression, requirements compliance, freshness, legacy cleanup. Use when auditing documentation structure.4license: MIT5---67> **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}`.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 `shared/references/audit_worker_core_contract.md`, `shared/references/docs_quality_contract.md`, `shared/references/docs_quality_rules.json`, and `shared/references/markdown_read_protocol.md`.25**MANDATORY READ:** Load `shared/references/mcp_tool_preferences.md` and `shared/references/mcp_integration_patterns.md`2627Receives `contextStore` with: `tech_stack`, `project_root`, `output_dir`.2829`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`.3031## Workflow32331) **Parse Context:** Extract tech stack, project root, output_dir from contextStore342) **Load Registry if Present:** Use `docs/project/.context/doc_registry.json` as the first routing source when available353) **Scan Docs:** Find all `.md` files in project (`AGENTS.md`, `CLAUDE.md`, `README.md`, `docs/**`)364) **Read Section-First:** For larger docs, outline first, then read header markers + `Quick Navigation` + `Agent Entry` + `Maintenance`375) **Build Tree:** Construct hierarchy from `AGENTS.md` outward links when present, otherwise from `CLAUDE.md`386) **Audit Categories 1-7:** Run structural checks (see Audit Categories below)397) **Collect Findings:** Record each violation with severity, location (file:line), effort estimate (S/M/L), recommendation408) **Calculate Score:** Count violations by severity, calculate compliance score (X/10)419) **Write Report:** Build full markdown report per `shared/templates/audit_worker_report_template.md`, write to `{output_dir}/611-structure.md` in single Write call4210) **Return Summary:** Return minimal summary to coordinator (see Output Format)4344## Audit Categories4546| # | Category | What to Check |47|---|----------|---------------|48| 1 | **Hierarchy & Links** | `AGENTS.md` is canonical root when present; all docs reachable via links; no orphaned files; no broken links |49| 2 | **Single Source of Truth** | No content duplication; duplicates replaced with links to source; clear ownership |50| 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) |51| 4 | **Requirements Compliance** | Correct header markers, correct top sections, within size limits, no illegal code blocks, stack-appropriate doc links |52| 5 | **Freshness Indicators** | Detect staleness signals: dates >6 months in content, deprecated API/tool references, TODO/FIXME markers, placeholder text left in place; deep fact-checking handled by dedicated worker |53| 6 | **Legacy Cleanup** | No history sections; no "was changed" notes; no deprecated info; current state only |54| 7 | **Stack Adaptation** | Links/refs match project stack; no Python examples in .NET project; official docs for correct platform |55| 8 | **Import Pattern Compliance** | When `AGENTS.md` exists at repo root, `CLAUDE.md` and `GEMINI.md` must each contain exactly one `@AGENTS.md` line and a bounded harness-specific delta (≤50 lines total per file). Any content in CLAUDE.md or GEMINI.md that duplicates AGENTS.md is drift. See `shared/references/agent_instructions_writing_guide.md` for rationale |5657### Severity Mapping5859| Issue Type | Severity |60|------------|----------|61| Staleness indicators (old dates, deprecated refs, TODO markers) | MEDIUM |62| Broken links, orphaned docs | HIGH |63| Content duplication | MEDIUM |64| Missing compression opportunity | LOW |65| Legacy/history content | MEDIUM |66| Wrong stack references | HIGH |67| Import pattern drift (duplicated AGENTS.md content in CLAUDE.md / GEMINI.md, oversized stub, missing `@AGENTS.md` line) | HIGH |6869## Scoring Algorithm7071**MANDATORY READ:** Load `shared/references/audit_worker_core_contract.md` and `shared/references/audit_scoring.md`.7273## Output Format7475**MANDATORY READ:** Load `shared/references/audit_worker_core_contract.md` and `shared/templates/audit_worker_report_template.md`.7677Write 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.7879Write 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.8081Return summary per `shared/references/audit_summary_contract.md`.8283Standalone mode still writes the same JSON summary to a worker-owned run-scoped artifact path per shared contract.8485## Critical Rules8687**MANDATORY READ:** Load `shared/references/audit_worker_core_contract.md`.8889- **Do not auto-fix:** Report violations only; coordinator aggregates for user90- **Tech stack aware:** Use contextStore `tech_stack` to apply stack-specific checks (e.g., .NET vs Node.js doc standards)91- **No deep fact-checking:** Detect staleness signals only (dates, deprecated refs, TODO markers)92- **Compress always:** Size limits are upper bounds, not targets. A 100-line file instead of 300 is a win93- **No code in docs:** Documents describe algorithms in tables or ASCII diagrams. Code belongs in codebase94- **Code is truth:** When docs contradict code, report docs as needing update (not code)95- **Delete, don't archive:** Legacy content should be removed, not moved to "archive"96- **Location precision:** Always include `file:line` for programmatic navigation97- **Shared contract precedence:** Placeholder policy, template-metadata policy, and no-code exceptions come from `docs_quality_contract.md` / `docs_quality_rules.json`9899## Definition of Done100101**MANDATORY READ:** Load `shared/references/audit_worker_core_contract.md`.102103- [ ] contextStore parsed successfully (including output_dir)104- [ ] All 8 structural categories audited105- [ ] Findings collected with severity, location, effort, recommendation106- [ ] Score calculated using penalty algorithm107- [ ] Report written to `{output_dir}/611-structure.md` (atomic single Write call)108- [ ] Summary written per contract109110## Reference Files111112- Size limits and targets: [references/size_limits.md](references/size_limits.md)113- Detailed checklist: [references/audit_checklist.md](references/audit_checklist.md)114115---116**Version:** 1.0.0117**Last Updated:** 2026-03-01
majiayu000