ln-610-docs-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 Auditor (L2 Coordinator)

文档审核器（L2协调器）

Coordinates 4 specialized audit workers to perform comprehensive documentation quality analysis.

协调4个专业审核工作器，执行全面的文档质量分析。

Purpose & Scope

用途与范围

Coordinates 4 audit workers running in parallel:
- ln-611 (documentation structure) — 1 invocation
- ln-612 (semantic content) — N invocations (per target document)
- ln-613 (code comments) — 1 invocation
- ln-614 (fact verification) — 1 invocation
Detect project type + tech stack ONCE
Pass shared context to all workers (token-efficient)
Aggregate worker results into single consolidated report
Write report to
```
docs/project/docs_audit.md
```
(file-based, no task creation)
Manual invocation by user or called by ln-100-documents-pipeline

协调4个并行运行的审核工作器：
- ln-611（文档结构）—— 调用1次
- ln-612（语义内容）—— 调用N次（按目标文档数量调用）
- ln-613（代码注释）—— 调用1次
- ln-614（事实校验）—— 调用1次
一次性检测项目类型与技术栈
将共享上下文传递给所有工作器（token使用效率更高）
聚合所有工作器的结果，生成单一的合并报告
将报告写入
```
docs/project/docs_audit.md
```
（基于文件存储，不创建任务）
支持用户手动调用，也可被ln-100-documents-pipeline调用

Workflow

工作流

Discovery: Detect project type, tech stack, scan .md files
Context Build: Build contextStore with output_dir, project_root, tech_stack
Prepare Output: Create output directory
Delegate: Invoke 4 workers in parallel
Aggregate: Collect worker results, calculate overall score
Context Validation: Post-filter findings
Write Report: Save to
```
docs/project/docs_audit.md
```

发现阶段： 检测项目类型、技术栈，扫描.md文件
上下文构建： 构建contextStore，包含output_dir、project_root、tech_stack
输出准备： 创建输出目录
任务下发： 并行调用4个工作器
结果聚合： 收集工作器结果，计算总体得分
上下文校验： 对发现的问题进行后置过滤
报告写入： 保存到
```
docs/project/docs_audit.md
```

Phase 1: Discovery

阶段1：发现

Load project metadata:

```
CLAUDE.md
```
— root of documentation hierarchy
```
docs/README.md
```
— documentation index

Package manifests:

package.json

requirements.txt

go.mod

Cargo.toml

Existing docs in
```
docs/project/
```

Extract:

Programming language(s)
Major frameworks/libraries
List of
```
.md
```
files in project (for ln-611 hierarchy check)
Target documents for semantic audit (for ln-612)

Target documents for ln-612:

FOR doc IN [CLAUDE.md, docs/README.md, docs/documentation_standards.md,
            docs/principles.md, docs/project/*.md]:
  IF doc exists AND doc NOT IN [docs/tasks/*, docs/reference/*, docs/presentation/*]:
    semantic_targets.append(doc)

加载项目元数据：

```
CLAUDE.md
```
—— 文档层级结构的根文件
```
docs/README.md
```
—— 文档索引

包清单文件：

package.json

、

requirements.txt

、

go.mod

、

Cargo.toml

```
docs/project/
```
目录下已有的文档

提取内容：

编程语言
主流框架/库
项目中所有
```
.md
```
文件列表（供ln-611做层级校验）
语义审核的目标文档（供ln-612使用）

ln-612的目标文档：

FOR doc IN [CLAUDE.md, docs/README.md, docs/documentation_standards.md,
            docs/principles.md, docs/project/*.md]:
  IF doc exists AND doc NOT IN [docs/tasks/*, docs/reference/*, docs/presentation/*]:
    semantic_targets.append(doc)

Phase 2: Build contextStore

阶段2：构建contextStore

json

{
  "tech_stack": {"language": "...", "frameworks": [...]},
  "project_root": "...",
  "output_dir": "docs/project/.audit/ln-610/{YYYY-MM-DD}"
}

Where

{YYYY-MM-DD}

is current date (e.g.,

2026-03-01

json

{
  "tech_stack": {"language": "...", "frameworks": [...]},
  "project_root": "...",
  "output_dir": "docs/project/.audit/ln-610/{YYYY-MM-DD}"
}

其中

{YYYY-MM-DD}

是当前日期（例如

2026-03-01

）。

Phase 3: Prepare Output

阶段3：准备输出

bash

mkdir -p {output_dir}

No deletion of previous date folders — history preserved for comparison.

bash

mkdir -p {output_dir}

不会删除之前日期的文件夹——保留历史数据用于对比。

Phase 4: Delegate to Workers

阶段4：下发任务给工作器

Invoke all workers in parallel via Skill tool:

Worker	Invocations	Output
ln-611-docs-structure-auditor	1	`{output_dir}/611-structure.md`
ln-612-semantic-content-auditor	N (per target document)	`{output_dir}/612-semantic-{doc-slug}.md`
ln-613-code-comments-auditor	1	`{output_dir}/613-code-comments.md`
ln-614-docs-fact-checker	1	`{output_dir}/614-fact-checker.md`

Pass contextStore to each worker. For ln-612, additionally pass

doc_path

per invocation. ln-614 receives contextStore only — it discovers and scans all .md files internally.

Worker return format:

Report written: ... | Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

通过Skill工具并行调用所有工作器：

工作器	调用次数	输出路径
ln-611-docs-structure-auditor	1	`{output_dir}/611-structure.md`
ln-612-semantic-content-auditor	N（按目标文档数量调用）	`{output_dir}/612-semantic-{doc-slug}.md`
ln-613-code-comments-auditor	1	`{output_dir}/613-code-comments.md`
ln-614-docs-fact-checker	1	`{output_dir}/614-fact-checker.md`

将contextStore传递给每个工作器。针对ln-612，每次调用额外传递

doc_path

参数。ln-614仅接收contextStore——它会内部自行发现并扫描所有.md文件。

工作器返回格式：

Report written: ... | Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

Phase 5: Aggregate Results

阶段5：聚合结果

Parse scores from worker return values
Read worker reports from
```
{output_dir}/
```
for detailed findings
Calculate category scores:

Category	Source	Weight
Documentation Structure	ln-611	25%
Semantic Content	ln-612 (avg across docs)	30%
Code Comments	ln-613	20%
Fact Accuracy	ln-614	25%

Calculate overall score: weighted average of 4 categories

解析工作器返回值中的得分
从
```
{output_dir}/
```
读取工作器报告，获取详细问题
计算各分类得分：

分类	数据来源	权重
文档结构	ln-611	25%
语义内容	ln-612（所有文档的平均分）	30%
代码注释	ln-613	20%
事实准确性	ln-614	25%

计算总体得分：4个分类的加权平均值

Phase 6: Context Validation (Post-Filter)

阶段6：上下文校验（后置过滤）

MANDATORY READ: Load

shared/references/context_validation.md

Apply Rule 1 + documentation-specific inline filters:

FOR EACH finding WHERE severity IN (HIGH, MEDIUM):
  # Rule 1: ADR/Planned Override
  IF finding matches ADR → advisory "[Planned: ADR-XXX]"

  # Doc-specific: Compression context (from ln-611)
  IF Structure finding Cat 3 (Compression):
    - Skip if path in references/ or templates/ (reference docs = naturally large)
    - Skip if filename contains architecture/design/api_spec
    - Skip if tables+lists > 50% of content (already structured)

  # Fact-checker: Example/template path exclusion (from ln-614)
  IF Fact finding (PATH_NOT_FOUND):
    - Path in examples/ or templates/ directory reference → advisory
    - Path has placeholder pattern (YOUR_*, <project>, {name}) → remove

  # Fact-checker: Planned feature claims (from ln-614)
  IF Fact finding (ENTITY_NOT_FOUND, ENDPOINT_NOT_FOUND):
    - Entity mentioned in ADR/roadmap as planned → advisory "[Planned: ADR-XXX]"

  # Fact-checker: Cross-doc contradiction authority (from ln-614)
  IF Fact finding (CROSS_DOC_*_CONFLICT):
    - docs/project/ is authority over docs/reference/ → report reference doc

  # Comment-specific: Per-category density targets (from ln-613)
  IF Comment finding Cat 2 (Density):
    - test/ or tests/ → target density 2-10%
    - infra/ or config/ or ci/ → target density 5-15%
    - business/domain/services → target density 15-25%
    Recalculate with per-category target.

  # Comment-specific: Complexity context for WHY-not-WHAT (from ln-613)
  IF Comment finding Cat 1 (WHY not WHAT):
    - If file McCabe complexity > 15 → WHAT comments acceptable
    - If file in domain/ or business/ → explanatory comments OK

Downgraded findings → "Advisory Findings" section in report.

必读： 加载

shared/references/context_validation.md

应用规则1和文档专属的内置过滤规则：

FOR EACH finding WHERE severity IN (HIGH, MEDIUM):
  # Rule 1: ADR/Planned Override
  IF finding matches ADR → advisory "[Planned: ADR-XXX]"

  # Doc-specific: Compression context (from ln-611)
  IF Structure finding Cat 3 (Compression):
    - Skip if path in references/ or templates/ (reference docs = naturally large)
    - Skip if filename contains architecture/design/api_spec
    - Skip if tables+lists > 50% of content (already structured)

  # Fact-checker: Example/template path exclusion (from ln-614)
  IF Fact finding (PATH_NOT_FOUND):
    - Path in examples/ or templates/ directory reference → advisory
    - Path has placeholder pattern (YOUR_*, <project>, {name}) → remove

  # Fact-checker: Planned feature claims (from ln-614)
  IF Fact finding (ENTITY_NOT_FOUND, ENDPOINT_NOT_FOUND):
    - Entity mentioned in ADR/roadmap as planned → advisory "[Planned: ADR-XXX]"

  # Fact-checker: Cross-doc contradiction authority (from ln-614)
  IF Fact finding (CROSS_DOC_*_CONFLICT):
    - docs/project/ is authority over docs/reference/ → report reference doc

  # Comment-specific: Per-category density targets (from ln-613)
  IF Comment finding Cat 2 (Density):
    - test/ or tests/ → target density 2-10%
    - infra/ or config/ or ci/ → target density 5-15%
    - business/domain/services → target density 15-25%
    Recalculate with per-category target.

  # Comment-specific: Complexity context for WHY-not-WHAT (from ln-613)
  IF Comment finding Cat 1 (WHY not WHAT):
    - If file McCabe complexity > 15 → WHAT comments acceptable
    - If file in domain/ or business/ → explanatory comments OK

Downgraded findings → "Advisory Findings" section in report.

降级的问题会归入报告的「建议问题」部分。

Phase 7: Write Report

阶段7：写入报告

Write consolidated report to

docs/project/docs_audit.md

markdown

undefined

将合并后的报告写入

docs/project/docs_audit.md

：

markdown

undefined

Documentation Audit Report - {DATE}

Overall Score: X.X/10

Category	Score	Worker	Issues
Documentation Structure	X/10	ln-611	N issues
Semantic Content	X/10	ln-612	N issues (across M docs)
Code Comments	X/10	ln-613	N issues
Fact Accuracy	X/10	ln-614	N issues

Category	Score	Worker	Issues
Documentation Structure	X/10	ln-611	N issues
Semantic Content	X/10	ln-612	N issues (across M docs)
Code Comments	X/10	ln-613	N issues
Fact Accuracy	X/10	ln-614	N issues

Critical Findings

[Category]
```
path/file:line
```
- Issue. Action: Fix suggestion.

[Category]
```
path/file:line
```
- Issue. Action: Fix suggestion.

Advisory Findings

(Context-validated findings downgraded from MEDIUM/HIGH)

Recommended Actions

Priority	Action	Location	Category
High	...	...	...

undefined

Priority	Action	Location	Category
High	...	...	...

undefined

Scoring Algorithm

评分算法

MANDATORY READ: Load

shared/references/audit_scoring.md

for unified scoring formula.

必读： 加载

shared/references/audit_scoring.md

获取统一评分公式。

Critical Notes

关键注意事项

Pure coordinator: Does NOT perform any audit checks directly. ALL auditing delegated to workers.
Fix content, not rules: NEVER modify standards/rules files to make violations pass
Fact verification via ln-614: Dedicated worker extracts and verifies all claims across ALL docs
Compress always: Size limits are upper bounds, not targets
No code in docs: Documents describe algorithms in tables or ASCII diagrams
Code is truth: When docs contradict code, always update docs
Delete, don't archive: Legacy content removed, not archived

纯协调器： 不直接执行任何审核检查，所有审核工作都下发给工作器处理。
修改内容而非规则： 绝对不要修改标准/规则文件来让违规项通过审核
通过ln-614进行事实校验： 专属工作器会提取并校验所有文档中的所有声明
始终压缩： 大小限制是上限，而非目标值
文档中不要包含代码： 文档使用表格或ASCII图描述算法
代码是事实依据： 当文档与代码冲突时，始终更新文档
删除而非归档： 遗留内容直接移除，不要归档

Definition of Done

完成定义

Project metadata discovered (tech stack, doc list)
contextStore built with output_dir =
```
docs/project/.audit/ln-610/{YYYY-MM-DD}
```
Output directory created (no deletion of previous runs)
All 4 workers invoked and completed
Worker reports aggregated: 4 category scores + overall
Context Validation applied to all findings
Consolidated report written to
```
docs/project/docs_audit.md
```

已完成项目元数据发现（技术栈、文档列表）
已构建contextStore，其中output_dir =
```
docs/project/.audit/ln-610/{YYYY-MM-DD}
```
已创建输出目录（不删除之前的运行记录）
所有4个工作器都已调用并执行完成
已聚合工作器报告：4个分类得分+总体得分
已对所有问题应用上下文校验
已将合并报告写入
```
docs/project/docs_audit.md
```

Reference Files

参考文件

Context validation rules:
```
shared/references/context_validation.md
```
Audit scoring formula:
```
shared/references/audit_scoring.md
```

Worker report template:

shared/templates/audit_worker_report_template.md

Task delegation pattern:

shared/references/task_delegation_pattern.md

Version: 5.0.0 Last Updated: 2026-03-01

上下文校验规则：
```
shared/references/context_validation.md
```
审核评分公式：
```
shared/references/audit_scoring.md
```

工作器报告模板：

shared/templates/audit_worker_report_template.md

任务下发模式：

shared/references/task_delegation_pattern.md

版本： 5.0.0 最后更新时间： 2026-03-01