ln-614-docs-fact-checker

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 Fact-Checker (L3 Worker)

文档事实检查器（L3 Worker）

Specialized worker that extracts verifiable claims from documentation and validates each against the actual codebase.

一款专门用于从文档中提取可验证声明，并针对实际代码库进行逐一验证的Worker。

Purpose & Scope

目标与范围

Worker in ln-610 coordinator pipeline - invoked by ln-610-docs-auditor
Extract all verifiable claims from ALL
```
.md
```
files in project
Verify each claim against codebase (Grep/Glob/Read/Bash)
Detect cross-document contradictions (same fact stated differently)
Includes
```
docs/reference/
```
,
```
docs/tasks/
```
,
```
tests/
```
in scope
Single invocation (not per-document) — cross-doc checks require global view
Does NOT check scope alignment or structural quality

ln-610协调器管道中的Worker - 由ln-610-docs-auditor调用
从项目中所有.md文件提取全部可验证声明
针对代码库验证每个声明（使用Grep/Glob/Read/Bash）
检测跨文档矛盾（同一事实的表述不一致）
检查范围包含
```
docs/reference/
```
、
```
docs/tasks/
```
、
```
tests/
```
单次调用（非按文档调用）——跨文档检查需要全局视角
不检查范围对齐或结构质量

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

工作流程

Phase 1: Parse Context

阶段1：解析上下文

Extract tech stack, project root, output_dir from contextStore.

从contextStore中提取技术栈、项目根目录、输出目录信息。

Phase 2: Discover Documents

阶段2：发现文档

Glob ALL

.md

files in project. Exclude:

```
node_modules/
```
,
```
.git/
```
,
```
dist/
```
,
```
build/
```
```
docs/project/.audit/
```
(audit output, not project docs)
```
CHANGELOG.md
```
(historical by design)

遍历项目中所有.md文件，排除以下内容：

```
node_modules/
```
、
```
.git/
```
、
```
dist/
```
、
```
build/
```
```
docs/project/.audit/
```
（审计输出文件，非项目文档）
```
CHANGELOG.md
```
（按设计属于历史记录文件）

Phase 3: Extract Claims (Layer 1)

阶段3：提取声明（第一层）

MANDATORY READ: Load

shared/references/two_layer_detection.md

for detection methodology.

For each document, extract verifiable claims using Grep/regex patterns.

MANDATORY READ: Load references/claim_extraction_rules.md for detailed extraction patterns per claim type.

9 claim types:

#	Claim Type	What to Extract	Extraction Pattern
1	File paths	Paths to source files, dirs, configs	Backtick paths, link targets matching `src/` , `lib/` , `app/` , `docs/` , `config/` , `tests/`
2	Versions	Package/tool/image versions	Semver patterns near dependency/package/image names
3	Counts/Statistics	Numeric claims about codebase	`\d+ (modules
4	API endpoints	HTTP method + path	`(GET
5	Config keys/env vars	Environment variables, config keys	`[A-Z][A-Z_]{2,}` in config context, `process.env.` , `os.environ`
6	CLI commands	Shell commands	`npm run` , `python` , `docker` , `make` in backtick blocks
7	Function/class names	Code entity references	CamelCase/snake_case in backticks or code context
8	Line number refs	file:line patterns	`[\w/.]+:\d+` patterns
9	Docker/infra claims	Image tags, ports, service names	Image names with tags, port mappings in docker context

Output per claim:

{doc_path, line, claim_type, claim_value, raw_context}

【必读】 加载

shared/references/two_layer_detection.md

文件以了解检测方法。

针对每个文档，使用Grep/正则表达式提取可验证声明。

【必读】 加载references/claim_extraction_rules.md文件以获取各声明类型的详细提取规则。

9种声明类型：

序号	声明类型	提取内容	提取规则
1	文件路径	源文件、目录、配置文件的路径	反引号包裹的路径，匹配 `src/` 、 `lib/` 、 `app/` 、 `docs/` 、 `config/` 、 `tests/` 的链接目标
2	版本号	包/工具/镜像版本	依赖/包/镜像名称附近的语义化版本（Semver）格式内容
3	数量/统计数据	关于代码库的数值声明	`\d+ (modules
4	API端点	HTTP方法 + 路径	`(GET
5	配置键/环境变量	环境变量、配置键	配置上下文中的 `[A-Z][A-Z_]{2,}` 格式内容， `process.env.` 、 `os.environ` 相关内容
6	CLI命令	Shell命令	反引号块中的 `npm run` 、 `python` 、 `docker` 、 `make` 相关命令
7	函数/类名称	代码实体引用	反引号或代码上下文中的驼峰式/蛇形命名内容
8	行号引用	file:line格式内容	`[\w/.]+:\d+` 格式内容
9	Docker/基础设施声明	镜像标签、端口、服务名称	Docker上下文中的带标签镜像名称、端口映射内容

每个声明的输出格式：

{doc_path, line, claim_type, claim_value, raw_context}

。

Phase 4: Verify Claims (Layer 2)

阶段4：验证声明（第二层）

For each extracted claim, verify against codebase:

Claim Type	Verification Method	Finding Type
File paths	Glob or `ls` for existence	PATH_NOT_FOUND
Versions	Grep package files (package.json, requirements.txt, docker-compose.yml), compare	VERSION_MISMATCH
Counts	Glob/Grep to count actual entities, compare with claimed number	COUNT_MISMATCH
API endpoints	Grep route/controller definitions	ENDPOINT_NOT_FOUND
Config keys	Grep in source for actual usage	CONFIG_NOT_FOUND
CLI commands	Check package.json scripts, Makefile targets, binary existence	COMMAND_NOT_FOUND
Function/class	Grep in source for definition	ENTITY_NOT_FOUND
Line numbers	Read file at line, check content matches claimed context	LINE_MISMATCH
Docker/infra	Grep docker-compose.yml for image tags, ports	INFRA_MISMATCH

False positive filtering (Layer 2 reasoning):

Template placeholders (
```
{placeholder}
```
,
```
YOUR_*
```
,
```
<project>
```
,
```
xxx
```
) — skip
Example/hypothetical paths (preceded by "e.g.", "for example", "such as") — skip
Future-tense claims ("will add", "planned", "TODO") — skip or LOW
Conditional claims ("if using X, configure Y") — verify only if X detected in tech_stack
External service paths (URLs, external repos) — skip
Paths in SCOPE/comment HTML blocks describing other projects — skip
```
.env.example
```
values — skip (expected to differ from actual)

针对每个提取的声明，对照代码库进行验证：

声明类型	验证方法	问题类型
文件路径	使用Glob或 `ls` 检查是否存在	PATH_NOT_FOUND
版本号	检索包文件（package.json、requirements.txt、docker-compose.yml），对比版本	VERSION_MISMATCH
数量/统计数据	使用Glob/Grep统计实际实体数量，与声明数值对比	COUNT_MISMATCH
API端点	检索路由/控制器定义	ENDPOINT_NOT_FOUND
配置键/环境变量	检索源代码中的实际使用情况	CONFIG_NOT_FOUND
CLI命令	检查package.json脚本、Makefile目标、二进制文件是否存在	COMMAND_NOT_FOUND
函数/类	检索源代码中的定义	ENTITY_NOT_FOUND
行号引用	读取文件对应行内容，检查是否与声明上下文匹配	LINE_MISMATCH
Docker/基础设施	检索docker-compose.yml中的镜像标签、端口配置	INFRA_MISMATCH

误报过滤（第二层推理）：

模板占位符（
```
{placeholder}
```
、
```
YOUR_*
```
、
```
<project>
```
、
```
xxx
```
）——跳过
示例/假设路径（前缀为“例如”、“e.g.”、“such as”）——跳过
未来时态声明（“将添加”、“计划中”、“TODO”）——跳过或标记为低优先级
条件声明（“如果使用X，请配置Y”）——仅当技术栈中检测到X时才验证
外部服务路径（URL、外部仓库）——跳过
描述其他项目的SCOPE/注释HTML块中的路径——跳过
```
.env.example
```
中的值——跳过（预期与实际值不同）

Phase 5: Cross-Document Consistency

阶段5：跨文档一致性检查

Compare extracted claims across documents to find contradictions:

Check	Method	Finding Type
Same path, different locations	Group file path claims, check if all point to same real path	CROSS_DOC_PATH_CONFLICT
Same entity, different version	Group version claims by entity name, compare values	CROSS_DOC_VERSION_CONFLICT
Same metric, different count	Group count claims by subject, compare values	CROSS_DOC_COUNT_CONFLICT
Endpoint in spec but not in guide	Compare endpoint claims across api_spec.md vs guides/runbook	CROSS_DOC_ENDPOINT_GAP

Algorithm:

claim_index = {}  # key: normalized(claim_type + entity), value: [{doc, line, value}]
FOR claim IN all_verified_claims WHERE claim.verified == true:
  key = normalize(claim.claim_type, claim.entity_name)
  claim_index[key].append({doc: claim.doc_path, line: claim.line, value: claim.claim_value})

FOR key, entries IN claim_index:
  unique_values = set(entry.value for entry in entries)
  IF len(unique_values) > 1:
    CREATE finding(type=CROSS_DOC_*_CONFLICT, severity=HIGH,
      location=entries[0].doc + ":" + entries[0].line,
      issue="'" + key + "' stated as '" + val1 + "' in " + doc1 + " but '" + val2 + "' in " + doc2)

对比不同文档中的提取声明，找出矛盾：

检查项	方法	问题类型
同一路径，不同位置	按文件路径声明分组，检查是否均指向同一实际路径	CROSS_DOC_PATH_CONFLICT
同一实体，不同版本	按实体名称分组版本声明，对比版本值	CROSS_DOC_VERSION_CONFLICT
同一指标，不同数量	按主题分组数量声明，对比数值	CROSS_DOC_COUNT_CONFLICT
规范中有端点但指南中无	对比api_spec.md与guides/runbook中的端点声明	CROSS_DOC_ENDPOINT_GAP

算法：

claim_index = {}  # key: normalized(claim_type + entity), value: [{doc, line, value}]
FOR claim IN all_verified_claims WHERE claim.verified == true:
  key = normalize(claim.claim_type, claim.entity_name)
  claim_index[key].append({doc: claim.doc_path, line: claim.line, value: claim.claim_value})

FOR key, entries IN claim_index:
  unique_values = set(entry.value for entry in entries)
  IF len(unique_values) > 1:
    CREATE finding(type=CROSS_DOC_*_CONFLICT, severity=HIGH,
      location=entries[0].doc + ":" + entries[0].line,
      issue="'" + key + "' stated as '" + val1 + "' in " + doc1 + " but '" + val2 + "' in " + doc2)

Phase 6: Score & Report

阶段6：评分与报告

MANDATORY READ: Load

shared/references/audit_worker_core_contract.md

and

shared/references/audit_scoring.md

Calculate score using penalty formula. Write report.

【必读】 加载

shared/references/audit_worker_core_contract.md

和

shared/references/audit_scoring.md

文件。

使用惩罚公式计算评分，生成报告。

Audit Categories (for Checks table)

审计分类（用于检查表格）

ID	Check	What It Covers
`path_claims`	File/Directory Paths	All path references verified against filesystem
`version_claims`	Version Numbers	Package, tool, image versions against manifests
`count_claims`	Counts & Statistics	Numeric assertions against actual counts
`endpoint_claims`	API Endpoints	Route definitions against controllers/routers
`config_claims`	Config & Env Vars	Environment variables, config keys against source
`command_claims`	CLI Commands	Scripts, commands against package.json/Makefile
`entity_claims`	Code Entity Names	Functions, classes against source definitions
`line_ref_claims`	Line Number References	file:line against actual file content
`cross_doc`	Cross-Document Consistency	Same facts across documents agree

ID	检查项	覆盖范围
`path_claims`	文件/目录路径	验证所有路径引用与文件系统的一致性
`version_claims`	版本号	验证包、工具、镜像版本与清单文件的一致性
`count_claims`	数量/统计数据	验证数值声明与实际统计的一致性
`endpoint_claims`	API端点	验证路由定义与控制器/路由器的一致性
`config_claims`	配置与环境变量	验证环境变量、配置键与源代码的一致性
`command_claims`	CLI命令	验证脚本、命令与package.json/Makefile的一致性
`entity_claims`	代码实体名称	验证函数、类与源代码定义的一致性
`line_ref_claims`	行号引用	验证file:line与实际文件内容的一致性
`cross_doc`	跨文档一致性	验证同一事实在不同文档中的表述一致

Severity Mapping

严重程度映射

Issue Type	Severity	Rationale
PATH_NOT_FOUND (critical file: CLAUDE.md, runbook, api_spec)	CRITICAL	Setup/onboarding fails
PATH_NOT_FOUND (other docs)	HIGH	Misleading reference
VERSION_MISMATCH (major version)	HIGH	Fundamentally wrong
VERSION_MISMATCH (minor/patch)	MEDIUM	Cosmetic drift
COUNT_MISMATCH	MEDIUM	Misleading metric
ENDPOINT_NOT_FOUND	HIGH	API consumers affected
CONFIG_NOT_FOUND	HIGH	Deployment breaks
COMMAND_NOT_FOUND	HIGH	Setup/CI breaks
ENTITY_NOT_FOUND	MEDIUM	Confusion
LINE_MISMATCH	LOW	Minor inaccuracy
INFRA_MISMATCH	HIGH	Docker/deployment affected
CROSS_DOC_*_CONFLICT	HIGH	Trust erosion, contradictory docs

问题类型	严重程度	理由
PATH_NOT_FOUND（关键文件：CLAUDE.md、runbook、api_spec）	严重	导致初始化/入职流程失败
PATH_NOT_FOUND（其他文档）	高	存在误导性引用
VERSION_MISMATCH（主版本）	高	内容完全错误
VERSION_MISMATCH（次版本/补丁版本）	中	仅为表面差异
COUNT_MISMATCH	中	存在误导性指标
ENDPOINT_NOT_FOUND	高	影响API消费者
CONFIG_NOT_FOUND	高	导致部署失败
COMMAND_NOT_FOUND	高	导致初始化/CI流程失败
ENTITY_NOT_FOUND	中	造成混淆
LINE_MISMATCH	低	仅为轻微不准确
INFRA_MISMATCH	高	影响Docker/部署流程
CROSS_DOC_*_CONFLICT	高	降低信任度，文档内容矛盾

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}/614-fact-checker.md

with

category: "Fact Accuracy"

and checks: path_claims, version_claims, count_claims, endpoint_claims, config_claims, command_claims, entity_claims, line_ref_claims, cross_doc.

Return summary to coordinator:

Report written: docs/project/.audit/ln-610/{YYYY-MM-DD}/614-fact-checker.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}/614-fact-checker.md

，设置

category: "Fact Accuracy"

，并包含以下检查项：path_claims、version_claims、count_claims、endpoint_claims、config_claims、command_claims、entity_claims、line_ref_claims、cross_doc。

向协调器返回摘要：

Report written: docs/project/.audit/ln-610/{YYYY-MM-DD}/614-fact-checker.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
Code is truth: When docs contradict code, document is wrong (unless code is a bug)
Evidence required: Every finding includes verification command used and result
No false positives: Better to miss an issue than report incorrectly. When uncertain, classify as LOW with note
Location precision: Always include
```
file:line
```
for programmatic navigation
Broad scope: Scan ALL .md files — do not skip docs/reference/, tests/, or task docs
Cross-doc matters: Contradictions between documents erode trust more than single-doc errors
Batch efficiently: Extract all claims first, then verify in batches by type (all paths together, all versions together)

【必读】 加载

shared/references/audit_worker_core_contract.md

文件。

禁止自动修复： 仅报告违规情况；由协调器汇总后提交给用户
代码为事实标准： 当文档与代码矛盾时，文档错误（除非代码存在bug）
需提供证据： 每个问题需包含使用的验证命令及结果
避免误报： 宁可不报告问题，也不要错误报告。存在疑问时，标记为低优先级并添加说明
位置精确： 始终包含
```
file:line
```
格式信息，支持程序化导航
范围全面： 扫描所有.md文件——不要跳过docs/reference/、tests/或任务文档
跨文档检查至关重要： 文档间的矛盾比单文档错误更影响信任度
高效批量处理： 先提取所有声明，再按类型批量验证（如所有路径一起验证，所有版本一起验证）

Definition of Done

完成标准

MANDATORY READ: Load

shared/references/audit_worker_core_contract.md

contextStore parsed successfully (including output_dir)
All
```
.md
```
files discovered (broad scope)
Claims extracted across 9 types
Each claim verified against codebase with evidence
Cross-document consistency checked
False positives filtered via Layer 2 reasoning
Score calculated using penalty algorithm
Report written to
```
{output_dir}/614-fact-checker.md
```
(atomic single Write call)
Summary returned to coordinator

【必读】 加载

shared/references/audit_worker_core_contract.md

文件。

成功解析contextStore（包括output_dir）
发现所有.md文件（范围全面）
提取9种类型的声明
每个声明均对照代码库验证并提供证据
完成跨文档一致性检查
通过第二层推理过滤误报
使用惩罚算法计算评分
将报告写入
```
{output_dir}/614-fact-checker.md
```
（原子单次写入操作）
向协调器返回摘要

Reference Files

参考文件

Audit output schema:

shared/references/audit_output_schema.md

Detection methodology:

shared/references/two_layer_detection.md

Claim extraction rules: references/claim_extraction_rules.md

Version: 1.0.0 Last Updated: 2026-03-06

审计输出 schema：

shared/references/audit_output_schema.md

检测方法：

shared/references/two_layer_detection.md

声明提取规则：references/claim_extraction_rules.md

版本： 1.0.0 最后更新： 2026-03-06