用途
Documentation Audit 用于系统性地验证文档中的声明是否与代码库实际情况相符。其核心原则是：低召回率比误报更糟糕——被遗漏的声明会一直隐藏下去。因此该技能强调尽可能全面地提取和检查文档中的可验证声明。
主要能力
该技能采用两遍式流程：
- 第一遍（Pass 1）：直接从文档中提取声明并逐条验证。
- 第二遍 A（Pass 2A）：从已发现的错误声明中归纳模式，扩展搜索相似问题。
- 第二遍 B（Pass 2B）：对比代码库清单与文档条目，进行差距检测。
可验证的声明类型包括：
| 类型 | 示例 | 验证方式 |
|---|---|---|
| file_ref | scripts/foo.py | 文件是否存在？ |
| config_default | "defaults to 'AI Radio'" | 检查 schema/代码 |
| env_var | STATION_NAME | 是否在 .env.example 和代码中？ |
| cli_command | --normalize flag | 脚本是否支持？ |
| behavior | "runs every 2 minutes" | 检查定时器/代码 |
验证置信度分为三层：
- Tier 1（自动）：file_ref、config_default、env_var、cli_command
- Tier 2（半自动）：symbol_ref、version_req
- Tier 3（人工复核）：behavior、constraint
使用方式
快速开始步骤：
- 确定目标文档（仅面向用户的文档，跳过 plans/、audits/ 目录）
- 记录当前 git 提交哈希，用于报告头部
- 使用并行代理运行第一遍提取（每个文档一个代理）
- 分析错误声明中的模式
- 运行第二遍扩展搜索
- 生成 docs/audits/AUDIT_REPORT_YYYY-MM-DD.md
第二遍模式扩展：在第一遍之后，分析错误声明并搜索相似模式。例如：
- 发现死脚本 diagnose_track_selection.py → 搜索所有脚本引用 → 又发现 8 个死脚本
- 错误间隔 "every 10 seconds" → 搜索 "every \d+ (seconds?|minutes?)" → 又发现 3 处
- 错误服务名 ai-radio-break-gen.service → 搜索 service/timer 名称 → 发现命名不一致
应始终检查的常见模式：
- 死脚本：scripts/*.py 引用
- 定时器间隔：every \d+ (seconds?|minutes?)
- 服务名称：ai-radio-.service、.timer
- 配置变量：RADIO_* 环境变量
- CLI 标志：bash 块中的 --flag 模式
输出格式
生成 docs/audits/AUDIT_REPORT_YYYY-MM-DD.md，包含：
- 报告头部：生成日期、提交哈希
- 执行摘要：扫描文档数、验证声明数、验证为真的数量与比例、验证为假的数量与比例
- 需要修复的错误声明：按文档列出，包含行号、声明内容、实际情况、修复建议
- 模式汇总：模式、数量、根本原因
- 人工复核队列：需要人工验证的行为声明等
适用场景
适用于需要确保文档准确性的项目，尤其是文档与代码容易脱节的场景，例如：
- 项目文档中引用了已删除的脚本或文件
- 配置默认值、环境变量、CLI 命令与代码不一致
- 行为描述（如定时器间隔）与实际代码不符
- 需要系统性地发现文档遗漏或过时内容
限制
- 仅面向用户文档，跳过 plans/、audits/ 目录
- 部分声明类型（behavior、constraint）需要人工复核，无法完全自动验证
- 需要记录 git 提交哈希以生成报告
- 详细执行清单和反模式参见 checklist.md，声明提取模式参见 extraction-patterns.md
- 其他具体限制暂未提供