Back to Details

ln-611-docs-structure-auditor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
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.
路径说明： 文件路径（
shared/
、
references/
、
../ln-*
）均相对于技能仓库根目录。若在当前工作目录（CWD）未找到，请定位到当前SKILL.md所在目录，再向上一级即为仓库根目录。

Documentation Structure Auditor (L3 Worker)

文档结构审核器（L3 Worker）

Specialized worker auditing structural quality of project documentation.
专门用于审核项目文档结构质量的Worker。

Purpose & Scope

目标与范围

  • Worker in ln-610 coordinator pipeline - invoked by ln-610-docs-auditor
  • Audit documentation for structural quality across 7 categories
  • Scan all 
    .md
    files in project, build hierarchy from CLAUDE.md
  • Return structured findings to coordinator with severity, location, recommendations
  • Calculate compliance score (X/10) for Documentation Structure
  • 作为ln-610协调器流水线中的Worker - 由ln-610-docs-auditor调用
  • 从7个维度审核文档的结构质量
  • 扫描项目中所有
    .md
    文件，基于CLAUDE.md构建文档层级
  • 向协调器返回包含问题严重程度、位置及改进建议的结构化检测结果
  • 计算文档结构的合规性得分（X/10）

Inputs (from Coordinator)

输入参数（来自协调器）

MANDATORY READ: Load 
shared/references/audit_worker_core_contract.md
.
Receives 
contextStore
with: 
tech_stack
, 
project_root
, 
output_dir
.
必读要求： 加载
shared/references/audit_worker_core_contract.md
文件。
接收包含以下内容的
contextStore
：
tech_stack
、
project_root
、
output_dir
。

Workflow

工作流程

  1. Parse Context: Extract tech stack, project root, output_dir from contextStore
  2. Scan Docs: Find all 
    .md
    files in project (CLAUDE.md, README.md, docs/**)
  3. Build Tree: Construct hierarchy from CLAUDE.md outward links
  4. Audit Categories 1-7: Run structural checks (see Audit Categories below)
  5. Collect Findings: Record each violation with severity, location (file:line), effort estimate (S/M/L), recommendation
  6. Calculate Score: Count violations by severity, calculate compliance score (X/10)
  7. 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
  8. Return Summary: Return minimal summary to coordinator (see Output Format)
  1. 解析上下文： 从contextStore中提取技术栈、项目根目录、输出目录信息
  2. 扫描文档： 查找项目中所有
    .md
    文件（包括CLAUDE.md、README.md、docs/**下的文件）
  3. 构建层级树： 基于CLAUDE.md的外部链接构建文档层级结构
  4. 审核7个维度： 执行结构检查（详见下方「审核维度」）
  5. 收集检测结果： 记录每个问题的严重程度、位置（文件:行号）、修复工作量预估（S/M/L）及改进建议
  6. 计算得分： 根据问题严重程度统计，计算合规性得分（X/10）
  7. 生成报告： 按照
    shared/templates/audit_worker_report_template.md
    模板构建完整的Markdown报告，通过单次写入操作保存至
    {output_dir}/611-structure.md
  8. 返回摘要： 向协调器返回精简的结果摘要（详见「输出格式」）

Audit Categories

审核维度

#CategoryWhat to Check
1Hierarchy & LinksCLAUDE.md is root; all docs reachable via links; no orphaned files; no broken links
2Single Source of TruthNo content duplication; duplicates replaced with links to source; clear ownership
3Proactive CompressionEliminate verbose/redundant content; prose to tables; remove meaningless info; compress even under-limit files; see size_limits.md
4Requirements ComplianceCorrect sections; within size limits; no code blocks (tables/ASCII diagrams/text only); stack-appropriate doc links
5Freshness IndicatorsDetect 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
6Legacy CleanupNo history sections; no "was changed" notes; no deprecated info; current state only
7Stack AdaptationLinks/refs match project stack; no Python examples in .NET project; official docs for correct platform
序号维度检查内容
1层级与链接CLAUDE.md为根文档；所有文档均可通过链接访问；无孤立文件；无失效链接
2单一信息源（SSOT）无内容重复；重复内容已替换为指向源文件的链接；明确内容归属
3主动压缩删除冗长/冗余内容；将叙述性文本转为表格；移除无意义信息；即使文件未超限也需压缩；参考size_limits.md
4需求合规性章节设置正确；文件大小符合限制；无代码块（仅允许表格/ASCII图/纯文本）；文档链接与技术栈匹配
5新鲜度指标检测过时信号：内容中存在超过6个月的日期、已废弃的API/工具引用、TODO/FIXME标记、遗留占位文本；深度事实核查由专用Worker处理
6遗留内容清理无历史章节；无「已修改」类注释；无已废弃信息；仅保留当前状态内容
7技术栈适配链接/引用与项目技术栈匹配；.NET项目中无Python示例；使用对应平台的官方文档链接

Severity Mapping

严重程度映射

Issue TypeSeverity
Staleness indicators (old dates, deprecated refs, TODO markers)MEDIUM
Broken links, orphaned docsHIGH
Content duplicationMEDIUM
Missing compression opportunityLOW
Legacy/history contentMEDIUM
Wrong stack referencesHIGH
问题类型严重程度
过时信号（旧日期、已废弃引用、TODO标记）中（MEDIUM）
失效链接、孤立文档高（HIGH）
内容重复中（MEDIUM）
未利用压缩机会低（LOW）
遗留/历史内容中（MEDIUM）
技术栈引用错误高（HIGH）

Scoring Algorithm

评分算法

MANDATORY READ: Load 
shared/references/audit_worker_core_contract.md
and 
shared/references/audit_scoring.md
.
必读要求： 加载
shared/references/audit_worker_core_contract.md
和
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 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.
Return summary to coordinator:
Report written: docs/project/.audit/ln-610/{YYYY-MM-DD}/611-structure.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)
必读要求： 加载
shared/references/audit_worker_core_contract.md
和
shared/templates/audit_worker_report_template.md
文件。
将报告写入
{output_dir}/611-structure.md
，需包含
category: "Documentation Structure"
及检查项：hierarchy_links、ssot、compression、requirements_compliance、freshness_indicators、legacy_cleanup、stack_adaptation。
向协调器返回如下摘要：
Report written: docs/project/.audit/ln-610/{YYYY-MM-DD}/611-structure.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
.
  • 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/references/audit_worker_core_contract.md
文件。
  • 禁止自动修复： 仅报告问题；由协调器汇总后提交给用户处理
  • 技术栈感知： 利用contextStore中的
    tech_stack
    执行技术栈专属检查（如.NET与Node.js的文档标准差异）
  • 不做深度事实核查： 仅检测过时信号（日期、已废弃引用、TODO标记）
  • 始终压缩内容： 大小限制为上限而非目标。100行的文件比300行更优
  • 文档中禁止代码： 文档需通过表格或ASCII图描述算法；代码应存放在代码库中
  • 代码为事实标准： 当文档与代码冲突时，报告文档需更新（而非修改代码）
  • 直接删除，而非归档： 遗留内容应直接删除，而非移至「归档」目录
  • 位置精准： 必须包含
    文件:行号
    信息，支持程序化导航

Definition of Done

完成标准

MANDATORY READ: Load 
shared/references/audit_worker_core_contract.md
.
  • contextStore parsed successfully (including output_dir)
  • All 7 structural categories audited
  • Findings collected with severity, location, effort, recommendation
  • Score calculated using penalty algorithm
  • Report written to 
    {output_dir}/611-structure.md
    (atomic single Write call)
  • Summary returned to coordinator
必读要求： 加载
shared/references/audit_worker_core_contract.md
文件。
  • 成功解析contextStore（包括output_dir）
  • 已完成全部7个结构维度的审核
  • 已收集包含严重程度、位置、工作量、改进建议的检测结果
  • 已通过惩罚算法计算得分
  • 已将报告写入
    {output_dir}/611-structure.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
  • 大小限制与目标：size_limits.md
  • 详细检查清单：references/audit_checklist.md
版本： 1.0.0 最后更新日期： 2026-03-01