ln-601-semantic-content-auditor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Semantic Content Auditor (L3 Worker)

Specialized worker auditing semantic accuracy of project documentation.

专注于审核项目文档语义准确性的工作组件。

Purpose & Scope

用途与范围

Worker in ln-600 coordinator pipeline - invoked by ln-600-docs-auditor for each project document
Verify document content matches stated SCOPE (document purpose)
Check content aligns with project goals (value contribution)
Validate facts against codebase (accuracy and freshness)
Return structured findings to coordinator with severity, location, fix suggestions

ln-600协调器流水线中的工作组件 - 由ln-600-docs-auditor针对每个项目文档调用
验证文档内容符合声明的SCOPE（文档用途）
检查内容与项目目标一致（价值贡献）
对照代码库验证事实（准确性与时效性）
向协调器返回包含严重程度、位置、修复建议的结构化审核发现

Target Documents

目标文档

Called ONLY for project documents (not reference/tasks):

Document	Verification Focus
`CLAUDE.md`	Instructions match project structure, paths valid
`docs/README.md`	Navigation accurate, descriptions match reality
`docs/documentation_standards.md`	Standards applicable to this project
`docs/principles.md`	Principles reflected in actual code patterns
`docs/project/requirements.md`	Requirements implemented or still valid
`docs/project/architecture.md`	Architecture matches actual code structure
`docs/project/tech_stack.md`	Versions/technologies match package files
`docs/project/api_spec.md`	Endpoints/contracts match controllers
`docs/project/database_schema.md`	Schema matches actual DB/migrations
`docs/project/design_guidelines.md`	Components/styles exist in codebase
`docs/project/runbook.md`	Commands work, paths valid

Excluded:

docs/tasks/

docs/reference/

docs/presentation/

tests/

仅针对项目文档调用（不包括参考文档/任务文档）：

文档	验证重点
`CLAUDE.md`	说明与项目结构匹配，路径有效
`docs/README.md`	导航准确，描述与实际一致
`docs/documentation_standards.md`	标准适用于当前项目
`docs/principles.md`	原则在实际代码模式中得到体现
`docs/project/requirements.md`	需求已实现或仍然有效
`docs/project/architecture.md`	架构与实际代码结构匹配
`docs/project/tech_stack.md`	版本/技术与包文件匹配
`docs/project/api_spec.md`	端点/契约与控制器匹配
`docs/project/database_schema.md`	架构与实际数据库/迁移文件匹配
`docs/project/design_guidelines.md`	组件/样式在代码库中存在
`docs/project/runbook.md`	命令可执行，路径有效

排除范围：

docs/tasks/

docs/reference/

docs/presentation/

tests/

Inputs (from Coordinator)

输入（来自协调器）

json

{
  "doc_path": "docs/project/architecture.md",
  "project_root": "/path/to/project",
  "tech_stack": {
    "language": "TypeScript",
    "frameworks": ["Express", "React"]
  }
}

json

{
  "doc_path": "docs/project/architecture.md",
  "project_root": "/path/to/project",
  "tech_stack": {
    "language": "TypeScript",
    "frameworks": ["Express", "React"]
  }
}

Workflow

工作流程

Phase 1: SCOPE EXTRACTION

阶段1：SCOPE提取

Read document first 20 lines
Parse
```

```
comment
If no SCOPE tag, infer from document type (see Verification Rules)
Record stated purpose/boundaries

读取文档前20行
解析
```

```
注释
如果没有SCOPE标签，根据文档类型推断（参见验证规则）
记录声明的用途/边界

Phase 2: CONTENT-SCOPE ALIGNMENT

阶段2：内容-范围匹配

Analyze document sections against stated scope:

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

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

对照声明的范围分析文档章节：

检查项	发现类型
章节不符合范围	OFF_TOPIC
范围方面未覆盖	MISSING_COVERAGE
超出范围的过多细节	SCOPE_CREEP
内容在其他地方重复	SSOT_VIOLATION

评分标准：

10/10：所有内容符合范围，范围完全覆盖
8-9/10：存在少量偏离主题的内容或小缺口
6-7/10：部分章节不匹配，覆盖不完整
4-5/10：严重不匹配，存在重大缺口
1-3/10：文档不符合其声明用途

Phase 3: FACT VERIFICATION

阶段3：事实验证

Per document type, verify claims against codebase:

Document	Verification Method
architecture.md	Check layers exist (Glob for folders), verify imports follow described pattern (Grep)
tech_stack.md	Compare versions with package.json, go.mod, requirements.txt
api_spec.md	Match endpoints with controller/route files (Grep for routes)
requirements.md	Search for feature implementations (Grep for keywords)
database_schema.md	Compare with migration files or Prisma/TypeORM schemas
runbook.md	Validate file paths exist (Glob), test command syntax
principles.md	Sample code files for principle adherence patterns
CLAUDE.md	Verify referenced paths/files exist

Finding Types:

OUTDATED_PATH: File/folder path no longer exists
WRONG_VERSION: Documented version differs from package file
MISSING_ENDPOINT: Documented API endpoint not found in code
BEHAVIOR_MISMATCH: Described behavior differs from implementation
STALE_REFERENCE: Reference to removed/renamed entity

Scoring:

10/10: All facts verified against code
8-9/10: Minor inaccuracies (typos, formatting)
6-7/10: Some paths/names outdated, core info correct
4-5/10: Functional mismatches (wrong behavior described)
1-3/10: Critical mismatches (architecture wrong, APIs broken)

根据文档类型，对照代码库验证声明内容：

文档	验证方法
architecture.md	检查层级是否存在（使用Glob匹配文件夹），验证导入是否遵循描述的模式（使用Grep）
tech_stack.md	对照package.json、go.mod、requirements.txt比较版本
api_spec.md	匹配端点与控制器/路由文件（使用Grep搜索路由）
requirements.md	搜索功能实现（使用Grep搜索关键词）
database_schema.md	对照迁移文件或Prisma/TypeORM架构
runbook.md	验证文件路径存在（使用Glob），测试命令语法
principles.md	抽样检查代码文件是否遵循原则模式
CLAUDE.md	验证引用的路径/文件存在

发现类型：

OUTDATED_PATH：文件/文件夹路径已不存在
WRONG_VERSION：文档记录的版本与包文件不符
MISSING_ENDPOINT：文档记录的API端点未在代码中找到
BEHAVIOR_MISMATCH：描述的行为与实现不符
STALE_REFERENCE：引用已删除/重命名的实体

评分标准：

10/10：所有事实均已对照代码验证
8-9/10：存在轻微不准确（拼写错误、格式问题）
6-7/10：部分路径/名称过时，核心信息正确
4-5/10：功能不匹配（描述的行为错误）
1-3/10：严重不匹配（架构错误、API失效）

Phase 4: SCORING & REPORT

阶段4：评分与报告

Calculate final scores and compile findings:

scope_alignment_score = weighted_average(coverage, relevance, focus)
fact_accuracy_score = (verified_facts / total_facts) * 10

overall_score = (scope_alignment * 0.4) + (fact_accuracy * 0.6)

Fact accuracy weighted higher because incorrect information is worse than scope drift.

计算最终分数并整理审核发现：

scope_alignment_score = weighted_average(coverage, relevance, focus)
fact_accuracy_score = (verified_facts / total_facts) * 10

overall_score = (scope_alignment * 0.4) + (fact_accuracy * 0.6)

事实准确率权重更高，因为错误信息比范围偏离的影响更严重。

Output Format

输出格式

Return JSON to coordinator:

json

{
  "doc_path": "docs/project/architecture.md",
  "scope": {
    "stated": "System architecture with C4 diagrams, component interactions",
    "coverage_percent": 85
  },
  "scores": {
    "scope_alignment": 8,
    "fact_accuracy": 6,
    "overall": 7
  },
  "summary": {
    "total_issues": 4,
    "high": 1,
    "medium": 2,
    "low": 1
  },
  "findings": [
    {
      "severity": "HIGH",
      "type": "BEHAVIOR_MISMATCH",
      "location": "line 45",
      "issue": "Architecture shows 3-tier (Controller->Service->Repository) but code has Controller->Repository direct calls",
      "evidence": "src/controllers/UserController.ts:23 imports UserRepository directly",
      "fix": "Update diagram to show actual pattern OR refactor code to match docs"
    },
    {
      "severity": "MEDIUM",
      "type": "OUTDATED_PATH",
      "location": "line 78",
      "issue": "References src/services/legacy/ which was removed",
      "evidence": "Folder does not exist: ls src/services/legacy/ returns error",
      "fix": "Remove reference or update to current path"
    }
  ]
}

向协调器返回JSON：

json

{
  "doc_path": "docs/project/architecture.md",
  "scope": {
    "stated": "System architecture with C4 diagrams, component interactions",
    "coverage_percent": 85
  },
  "scores": {
    "scope_alignment": 8,
    "fact_accuracy": 6,
    "overall": 7
  },
  "summary": {
    "total_issues": 4,
    "high": 1,
    "medium": 2,
    "low": 1
  },
  "findings": [
    {
      "severity": "HIGH",
      "type": "BEHAVIOR_MISMATCH",
      "location": "line 45",
      "issue": "Architecture shows 3-tier (Controller->Service->Repository) but code has Controller->Repository direct calls",
      "evidence": "src/controllers/UserController.ts:23 imports UserRepository directly",
      "fix": "Update diagram to show actual pattern OR refactor code to match docs"
    },
    {
      "severity": "MEDIUM",
      "type": "OUTDATED_PATH",
      "location": "line 78",
      "issue": "References src/services/legacy/ which was removed",
      "evidence": "Folder does not exist: ls src/services/legacy/ returns error",
      "fix": "Remove reference or update to current path"
    }
  ]
}

Verification Rules by Document Type

按文档类型划分的验证规则

See references/verification_rules.md for detailed per-document verification patterns.

详细的逐文档验证模式请参见references/verification_rules.md。

Critical Rules

核心规则

Read before judge: Always read full document and relevant code before reporting issues
Evidence required: Every finding must include
```
evidence
```
field with verification command/result
Code is truth: When docs contradict code, document is wrong (unless code is a bug)
Scope inference: If no SCOPE tag, use document filename to infer expected scope
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

先阅读再判断： 在报告问题前，务必完整阅读文档及相关代码
需提供证据： 每个审核发现必须包含
```
evidence
```
字段，记录验证命令/结果
代码即事实： 当文档与代码矛盾时，文档有误（除非代码是bug）
范围推断： 如果没有SCOPE标签，使用文档文件名推断预期范围
避免误报： 宁可遗漏问题，也不要错误报告
位置精准： 审核发现必须始终包含行号
可执行的修复建议： 每个审核发现必须有具体的修复建议

Definition of Done

完成标准

Document read completely
SCOPE extracted or inferred
Content-scope alignment analyzed
Facts verified against codebase (with evidence)
Both scores calculated
JSON result returned to coordinator

Version: 1.0.0 Last Updated: 2026-01-28

已完整阅读文档
已提取或推断SCOPE
已分析内容与范围的匹配度
已对照代码库验证事实（并提供证据）
已计算两项分数
已向协调器返回JSON结果

版本： 1.0.0 最后更新： 2026-01-28