变更影响分析
默认只读。先用真实依赖与现有文档证明影响面，再实施；未知项明确标“未验证”。
修改前
依次回答：
- 代码：入口、直接调用方、下游消费者、生成物和兼容层会受什么影响？
- 数据：Schema、迁移、历史数据、序列化、缓存和幂等键是否变化？
- 接口：API、消息、文件格式或 CLI 是否改变？消费者和提供者分别是谁？
- 测试：哪些成功标准、TEST-ID、契约测试和回归命令应证明变更正确？
- 文档：是否影响 MAP、ARCHITECTURE、STATUS、LOG、CONTEXT、ADR、CONTRACT、Spec/Plan、TESTS 或 REGRESSION？
- 发布：部署顺序、兼容窗口、数据恢复、回滚命令和不可逆部分是什么？
证据优先取自真实 import/调用、路由、Schema、配置、生成脚本、git grep、git diff 和可执行测试。不要凭目录名猜依赖。
路由规则
-
模块职责、公共入口、依赖或状态写入变化：修改前后执行
architecture-docs的“模块文档与代码边界一致性”；读取双方适用的模块入口、CONTEXT 与契约，输出约定到代码的证据和未知项。方法只在该 Skill 维护，不以本次入口文档有 diff 代替检查。 -
架构、数据库、认证、部署拓扑或长期技术策略：检查
domain-modeling/ ADR。 -
跨端接口：先更新
contract-first管理的唯一契约源，再规划消费者、提供者和联调证据。 -
需求、业务规则、风险或 Bug：让成功标准保留在 Spec/Issue，并用
test-collaboration关联 TEST-ID。 -
Module 行为或下游依赖变化：实施后运行
module-regression；若权责、状态归属、Interface、依赖方向或核心流转改变，调用architecture-docs判断必要性并维护实际架构主记录，确保 MAP 能导航；无需创建或证据不足时说明依据与缺口。 -
数据库迁移、破坏性接口、认证和生产发布：必须写回滚条件、恢复步骤、兼容期和不可逆部分；缺任何一项就标为阻塞，不代替人执行回滚。
输出
小改动在回复中给出：影响对象、证据、所需验证、文档同步和未知项。只有跨模块、高风险或用户明确要求留档时，才把报告写入 docs/impacts/；写文件前先确认，避免制造一次性文档。
按事实核对文档
解决“AI 改完功能或接口，用户还得自己找漏改文档，下一轮又被旧说明误导”的问题。候选检索由 Agent 执行并完成判读，向用户交付具体冲突、依据和处理结果，不把原始候选清单当成完成。
变更后的语义审查与阶段同步共用此流程。先通过现有确定性审计，再由当前 Agent 执行；路径映射、文件修改时间、Markdown 已产生 diff 或扫描退出码 0 都不能代替内容核对。
先单独运行 python3 <插件目录>/scripts/audit-docs.py --root <项目根> --scope full 并检查退出码；非零就停止候选检索、语义核对及据此进行的文档同步。即使判断是原有问题或误报，也须修复并复跑通过后再继续；超出授权或无法修复时报告阻塞。不用分号或忽略失败的命令串绕过此步骤。已提交审查须对受检快照审计，可复用同一 base/head 的 PR 检查结果。
先自动收集候选，再执行下方判读；输出是线索，不是过期结论：
bash# 已提交变更：比较共同祖先与 head，只读提交快照 python3 <插件目录>/scripts/find-doc-impact.py --root <项目根> --base <基线> --head <受检提交> # 日常维护：比较任务开始时的提交与当前文件，含未提交及非忽略的未跟踪文件 python3 <插件目录>/scripts/find-doc-impact.py --root <项目根> --base <任务起点> --worktree
检索合并 change_rules、变更路径引用、diff 中的标识符，返回候选路径、行号、原文和命中依据。功能变化补充 --term '功能名' 或旧流程术语，重点核对 Spec、使用说明与相关流程；契约变化重点核对机器契约引用、API 说明、调用示例与接入指南。架构、MAP、STATUS、LOG 按实际影响核对，不要求每次全改。
候选包括历史与无关同名内容，须读上下文排除；标识符未变的行为变化、同义表达和外部资料仍需 Agent 补查。无命中不能判无影响；报告跳过文件、不可访问资料及检索范围。退出 0 仅表示检索完成，退出 2 表示执行失败。没有可靠基线时列出缺口并按文档当前声明核对，不伪造变更范围。需求与实现冲突分别报告，不自动改写已确认 Spec。
- 固定范围和版本。 记录实际 base/head 提交及其共同祖先，以共同祖先为比较起点，读取该起点与 head 的 diff 和旧／新正文；不要把当前工作区修复当作已提交内容。审查未提交修改时另列暂存／未暂存／未跟踪范围及相关文件哈希。基线或来源缺失时标未验证，不猜旧规则。
- 提取改变的事实。 从代码、机器契约、配置及已确认需求中核对旧值、新值和原因，覆盖接口输入输出、流程步骤／条件、职责、依赖和外部副作用。契约删除一个字段并新增另一个字段，只能先记为删除／新增；有确认来源或实现证据才称重命名。内部修复若未改变对外事实，记录依据后结束相应同步检查。
- 找到主记录与引用。 从项目地图、契约入口、需求主记录及
change_rules命中项开始，再用rg／git grep查变更对象的路径、旧标识和相关术语，沿链接补读映射外的说明。已提交审查应对 head 快照检索。无链接但描述同一事实的说明也要核对；检索无结果不证明没有遗漏，记录实际检索范围及不可访问对象。 - 逐条判读候选。 阅读命中位置的上下文，确认是否属于同一接口／流程、是否仍作为当前操作依据。当前正文与新事实冲突时给出具体位置、旧表述和对照证据，文件本次改过也不能跳过。历史记录、引用和无关同名字段不因关键词命中而要求改写；历史内容仍被当作当前指引时，报告误用它的入口。纯引用且目标有效时说明无需同步正文。
- 核对重复与证据。 同一生效规则若有可独立编辑的多份正文，列出主记录与副本，建议其余位置改引用；主源不明先待核实，不自行选一份覆盖。机器契约、实现和历史各自承担职责，不按相同词句数量判重复。测试结果引用原始回执及对应版本／输入哈希，结果缺失或已过期时标未验证，不重抄结果补齐表格。
- 交付并按变化失效。 在现有回复、PR 或审查记录中输出下表，绑定范围与版本。相关契约、代码或文档变化后重核受影响项，旧结论不自动沿用。不新建同步台账，不因普通待复核项一律阻断提交；沿用项目已有风险与合并要求。
| 事实变化及依据 | 文档位置与原表述 | 结论与下一步 |
|---|---|---|
| 旧／新事实，来源路径与版本 | 路径、行号／条款、必要短引文；重复项另指主记录 | 已核对：需要更新／无需更新及理由；待复核：候选尚未判读；未验证：缺少何种来源或执行证据 |
先报告需要更新的当前说明，再列无需更新的反例和剩余缺口。没有实际运行文档中的步骤时，不声称已复现失败；未知项不能计入通过。治理成本只记录本轮实际核对、修改的文档及原始回执位置，耗时未测就注明未知，不预设节省比例。
可复跑的接口字段样例及审查验收见 接口变更场景。它只验证这一切片，不代表所有事实类型或业务项目都已覆盖。
实施后对照
完成实现后检查：
- 实际改动是否解决 Spec/Issue 中的原始问题。
- 实际 diff 是否超出已声明范围；超出项是否获得授权并补充影响分析。
- 测试和人工证据是否真正覆盖成功标准，而非只证明命令运行过。
- CONTEXT、ADR、CONTRACT、TESTS、REGRESSION、MAP、ARCHITECTURE、STATUS 和 LOG 是否按实际变化同步。
- 是否遗留临时代码、兼容逻辑、迁移尾项或后续 Issue。
默认在交付回复中报告对照结论。只有高风险变更或用户要求正式评审时，才保存到 docs/reviews/。不要创建通用 REFLECTION.md。
