documentation-impact

文档影响

让文档与用户实际使用时的行为相符。在决定哪些文档需要修改前，先检查实际变更及其调用方。确认无需修改并给出依据，也是完整的结果。

选择模式和范围

当任务授权更新文档时，使用 author。对于审计、独立审查、状态请求或其他只读任务，使用 review。遵循调用方指定的模式。如果更新权限不明确，则以 review 模式检查并报告。

• 在 author 模式下，在授权的变更范围内更新受影响的文档。不要改动无关编辑。
• 在 review 模式下，只检查，不要编辑你所评估的工件。将发现反馈给其作者。不要修正文档后再为自己的修复背书。

调用工作流负责委派、模型选择、后续工作和人工审核关卡。不要在此处另行启动协调者或发布工作流。

依据已接受的请求、问题单或现有工作说明开展工作。不要要求提供新的规范、工单、文档树或工作台账。

将检查范围限定为你实际检查的内容：

• 对于已提交的工作，确定并记录固定的基线和头部提交。检查这两个版本之间的差异，以及对应版本中的实现和文档上下文。
• 对于本地工作，还要检查暂存和未暂存的变更，以及相关的未跟踪文件。记录这些输入的内容指纹或保留的快照。表面干净的 HEAD 或文件名列表无法标识脏文件的具体内容。
• 对于 Git 之外的内容，记录范围内实现和文档的明确内容快照。如果无法获取相关输入，请指出这一缺口，不要声称已覆盖。

记录已检查的路径，以及指纹方法或保留快照的位置，以便其他 Agent 能够复现比较。返回结果前重新检查输入。如果并发编辑导致输入发生变化，请重新检查受影响的内容，或说明结果已无法反映当前工件。

将变更映射到读者

阅读仓库说明，并找出其维护的文档和示例所在位置。追踪变更的行为，确认哪些人会使用、运行、升级或开发该项目。即使应用代码没有变化，也要涵盖公开工作流中技能和配置的变更。

当变更影响以下内容时，请考虑相应的文档类型：

变更的行为	候选文档
安装、入门或基本用法	README、快速入门、教程
命令、API、标志、默认值、配置或环境变量	CLI 和 API 参考、配置指南、可执行示例
兼容性、存储或升级行为	迁移和升级说明、弃用通知
面向发布的行为	发布说明或变更日志（如果仓库有维护）
模块边界、数据流或运维行为	架构说明、图表、运行手册、开发者指南

在已修改文件之外搜索旧名称、旧值和相互矛盾的示例。结合上下文阅读匹配到的声明。近期时间戳、路径匹配、生成的文本或渲染后的图表都不能证明内容准确。

针对每项受影响的读者任务，指出相应的维护文档，或说明为何无需修改文档。现有文档可能已经正确。内部重构可能完全不影响文档所描述的约定。不要为了让检查显得有成果而创建填充内容。

更新或检查

在 author 模式下，只进行满足行为变更所需的最小修正。遵循仓库的文档布局和生成命令。更新生成文档的源文件，而不是手动编辑生成的输出。

对你编写或审阅的文档使用 technical-writing 技能，然后对其使用 unslop 技能。示例必须对应真实的符号、路径、标志、默认值和受支持版本。示例路径必须能在读者的机器上解析。对于特定于机器的路径，请使用明确的占位符，并说明如何查找或提供实际值。如果前面的步骤创建了临时路径，则该路径有效。作者未作说明的临时路径不能作为可用示例。如果升级需要用户采取操作，请说明该操作以及变更前后的行为。

通过实现代码追踪文档所述的效果。接受或报告某个设置，并不能证明相应操作确实会执行。如果预期行为与观察到的行为不一致，请将其作为实现问题报告，而不是将缺陷描述为受支持的行为。

在 review 模式下，依据实现代码自行推导受影响的读者任务。对照源代码检查作者的覆盖范围判断，包括声称没有任何变更的情况。将作者的回执视为需要检查的证据，而不是最终结论。

如果图示比文字更能说明受影响的关系，请使用仓库现有的图示格式。对照实现代码检查每个变更涉及的参与者、连线、方向和边界。如果有可用的可视化工具，可用它们帮助呈现发现。否则，请使用 Markdown 或现有的图示源文件。不要安装可视化依赖，不要要求提供品牌素材，也不要等待批注反馈才完成本轮检查。

判断 author 模式是否需要审查

author 阶段必须且只能返回以下一项结果：

• independent review required：文档已变更、公开工作流或已记录的契约已变更，或者仍存在未解决的文档缺口。
• independent review not required：仅当证据表明内部变更不影响文档时才可使用。

公开工作流或文档发生变更时，不得使用 independent review not required。记录支持 author 阶段结论的证据及其所依据的产物。只有当 author 阶段的结果为 independent review required 时，完成或发布工作流才能启动独立审查。

需要独立审查时，应由另一位 Agent 在不编辑产物的情况下审查最终产物。独立审查的结论为 pass、needs changes 或 unverified。修复完成后，审查者应检查最终产物，再返回 pass。只有在所审查的变更、文档及相关上下文仍一致时，才可复用该结论。变基后补丁 ID 相同，并不能证明文档上下文未发生变化。请重新检查该上下文，或重新执行审查。

验证并返回结果

运行相关的仓库文档检查；在任务权限允许且安全的情况下，使用实际实现验证变更后的示例。对用作完成证据的命令，使用 verify-commands 技能。审查模式下，运行检查时不得修改受审文件；如果检查会写入输出，请使用一次性副本。

检查事实含义以及语法和渲染效果。示例即使能运行，但默认行为有误，或图表凭空加入了审批步骤，仍然是错误的。将不安全或无法执行的检查报告为验证缺口。切勿为了验证示例而部署、发布文档或更改外部数据。

在对话中或现有工作记录中返回简明结果：

• 模式、范围和检查的修订版本或快照，包括相关本地更改。
• 受影响的读者任务和文档路径，以及所做的更新或保持不变的依据。
• 实际运行的检查、检查结果，以及仍未解决的问题或验证缺口。
• 在作者模式下，给出作者结果及其证据。在审查模式下，返回 pass、needs changes 或 unverified。对于已确认的遗漏或错误声明，使用 needs changes；对于证据不足以作出判断的情况，使用 unverified。

作者结果不等同于独立审查结论。