用途
Docs Drift Review 是一个文档审查类技能，用于分析仓库文档与实现之间的偏差。当用户提出以下需求时可使用该技能：
- 对比文档与实现
- 查找过时或错误的文档
- 审查 README、指南、API 文档、设计文档、注释或入门文档
- 提出文档改进建议
- 识别拼写、语法、命名一致性或重组问题
- 准备文档清理计划
- 核实某个功能或接口变更后是否有对应的文档更新
主要产出
该技能产生的报告会：
- 识别文档与代码之间的实现偏差
- 区分已确认问题与可能但未经验证的担忧
- 针对措辞、示例、拼写、结构和导航提出精确改进建议
- 按用户影响对发现的问题排序
- 推荐最小且合理的补丁集
非目标
该技能明确不做以下事情：
- 编造代码或测试不支持的行为
- 在针对性补丁足够时重写全部文档
- 将风格偏好标记为缺陷，除非它们降低了清晰度或与仓库惯例冲突
- 仅凭命名差异就断定存在偏差，而不检查上下文
- 在用户未明确要求时修改文件
输入检查顺序
技能会优先按以下顺序检查：
- AGENTS.md 及附近的 agent 指令
- 顶层 README*
- docs/、documentation/、guides/、examples/ 等文档目录
- API 规范与模式，如 OpenAPI、JSON Schema、protobuf、CRD、GraphQL schema
- 实现被记录行为的源代码
- 覆盖被记录行为的测试
- 配置文件、CLI 帮助文本和示例清单
- 变更日志、迁移指南、发布说明
核心工作流程
步骤 1：构建文档地图
创建紧凑清单：主要文档文件及其用途、覆盖的功能领域、每个领域可能的真实来源文件、看起来过时的部分（如带版本的命令、标志、环境变量、API 路径、截图、复制的输出或分步流程）。
步骤 2：构建实现地图
识别入口点、公共接口、命令、标志、配置键、环境变量、API 路由、请求/响应结构、功能开关、默认值、约束、示例与测试夹具，以及相关测试。在判断当前行为时，优先参考测试和模式，而非注释。
步骤 3：对比文档与实现
检查重命名或移除的命令、标志、环境变量、配置字段、API；变更的默认值；变更的前置条件或设置步骤；过时的示例或示例输出；未记录的新行为；文档声称支持但代码不再提供的行为；文档遗漏的在实际中重要的约束、边界情况或失败模式。
对于每个疑似偏差项：在文档中找到确切证据，在代码/测试/规范中找到确切证据，然后判定为已确认偏差、可能偏差或证据不足。
步骤 4：审查文档质量
检查拼写和语法错误、产品/功能/命令/文件/概念命名不一致、含糊措辞、跨文件重复内容、信息架构薄弱、章节位置错误、可扫描性差、没有解释的示例、没有可运行示例的解释、缺失的交叉链接、过时的文件路径或仓库布局引用。
步骤 5：生成按优先级排序的报告
将发现的问题组织为：关键正确性问题、重要缺失或过时内容、清晰度与可用性改进、文案编辑问题、重组建议。
每个发现包括：严重程度（critical / high / medium / low）、置信度（confirmed / likely / uncertain）、文档文件、实现文件、简要说明、推荐修复方案，以及可选的建议替换文本。
严重程度指南
- critical：破坏设置、涉及安全、破坏迁移或破坏 API 的文档错误
- high：实质性误导、浪费时间或导致错误使用的文档
- medium：缺失上下文、遗漏、过时示例或影响成功的结构问题
- low：拼写、语法、命名一致性和润色
证据规则
优先使用来自代码、测试、模式、生成的帮助或示例的直接证据。如果行为不明确，要明确说明。不要仅从类型名或注释推断运行时行为。如果测试与文字文档矛盾，应将其视为偏差信号并记录矛盾。如果文档与代码矛盾但代码看起来是意外或有缺陷的，不要决定策略，应中立地报告不一致。
输出格式
使用以下结构：
摘要：整体文档健康状况的简要说明、按严重程度统计的发现数量、前三问题。
发现：每个发现包含 ID、严重程度、置信度、文档证据、实现证据、重要性说明、推荐修复方案、建议文本（仅在有帮助时）。
覆盖缺口：列出已实现但未记录的功能领域。
重组建议：建议合并、拆分、移动或索引页。
快速改进：列出最小的高价值文档修复。
可选补丁计划：如果用户要求编辑，提出安全的逐文件序列。
审查启发式
特别关注以下偏差模式：README 说的是一个命令，CLI 帮助暴露的是另一个；文档列出的标志不存在于解析器定义中；文档遗漏了代码现在强制要求的必需环境变量或凭据；示例使用旧的 API 路径或字段名；文档描述的默认值在配置代码中已变更；迁移指南不再匹配实际升级路径；文档引用了仓库中已移动的目录或文件；生成的产物或 CRD 已变更但文字文档未变更；截图或输出片段不再匹配当前 UX 或日志。
拼写与风格启发式
标记：重复词语、明显拼写错误、产品名称大小写不一致、命令/文件名/标志/环境变量的代码字体不一致、标题与章节内容不匹配、应转换为步骤/表格/项目符号列表的段落、需要目录或子章节拆分的长页面。除非本地惯例明确，否则不要过度纠正内部风格。
重组启发式
在以下情况下建议重组：同一概念在 3 个或更多地方解释；入门与参考材料混在一起；迁移指南埋在发布说明中；示例与其演示的功能分离；顶层 README 承担了过多内容；配置或 API 参考没有单一真实来源。
当被要求编辑时
如果用户希望进行更改：先编辑最高严重程度的正确性问题，然后修复过时的示例和缺失的前置条件，再改进命名一致性和结构，保持差异最小且可审查，除非仓库明显已迁移，否则保留既有术语。
建议提示
该技能应能处理的请求示例：
- “审查文档是否存在实现偏差。”
- “将 README 和 docs/ 与当前 CLI 和配置进行对比。”
- “查找过时示例并提出修复方案。”
- “审计 API 文档与服务器实现。”
- “建议文档重组和文案编辑改进。”
完成标准
当满足以下条件时任务完成：主要文档表面已对照当前实现进行检查；发现基于证据并已按优先级排序；报告清楚区分已确认问题与猜测；建议的修复足够具体，可实现。