变更影响分析

默认只读。先用真实依赖与现有文档证明影响面，再实施；未知项明确标“未验证”。

修改前

按本次风险回答相关项；范围明确的小修直接核对相关代码与检查，不展开全部维度或全量读取文档：

1. 代码：入口、直接调用方、下游消费者、生成物和兼容层会受什么影响？
2. 数据：Schema、迁移、历史数据、序列化、缓存和幂等键是否变化？
3. 接口：API、消息、文件格式或 CLI 是否改变？消费者和提供者分别是谁？
4. 测试：哪些成功标准、TEST-ID、契约测试和回归命令应证明变更正确？
5. 文档：是否影响 MAP、ARCHITECTURE、STATUS、LOG、CONTEXT、ADR、CONTRACT、Spec/Plan、TESTS 或 REGRESSION？
6. 发布：部署顺序、兼容窗口、数据恢复、回滚命令和不可逆部分是什么？

证据优先取自真实 import/调用、路由、Schema、配置、生成脚本、git grep、git diff 和可执行测试。不要凭目录名猜依赖。

路由规则

• 模块职责、公共入口、依赖或状态写入变化：修改前后执行 architecture-docs 的“模块文档与代码边界一致性”；读取双方适用的模块入口、CONTEXT 与契约，输出约定到代码的证据和未知项。方法只在该 Skill 维护，不以本次入口文档有 diff 代替检查。
• 架构、数据库、认证、部署拓扑或长期技术策略：检查 domain-modeling / ADR。
• 跨端接口：先更新 contract-first 管理的唯一契约源，再规划消费者、提供者和联调证据。
• 需求、业务规则、风险或 Bug：复用已有成功标准与相关测试；只有测试入口、重要覆盖范围或测试资产需要维护时使用 test-collaboration，普通修复不强制 TEST-ID。
• 跨 Module 行为或下游依赖变化：实施后按实际影响使用 module-regression；若权责、状态归属、Interface、依赖方向或核心流转改变，调用 architecture-docs 判断必要性并维护实际架构主记录，确保 MAP 能导航；无需创建或证据不足时说明依据与缺口。
• 数据库迁移、破坏性接口、认证和生产发布：必须写回滚条件、恢复步骤、兼容期和不可逆部分；缺任何一项就标为阻塞，不代替人执行回滚。

输出

小改动在回复中给出：影响对象、证据、所需验证、文档同步和未知项。只有跨模块、高风险或用户明确要求留档时，才把报告写入 docs/impacts/；写文件前先确认，避免制造一次性文档。

按事实核对文档

解决“AI 改完功能或接口，用户还得自己找漏改文档，下一轮又被旧说明误导”的问题。候选检索由 Agent 执行并完成判读，向用户交付具体冲突、依据和处理结果，不把原始候选清单当成完成。

变更后的语义审查与阶段同步共用此流程。先从实际 diff 确定改变的事实和受影响说明；局部任务直接核对主记录与引用，无需先跑全项目审计。路径映射、文件修改时间、Markdown 已产生 diff 或扫描退出码 0 都不能代替内容核对。

需要机械检查时运行 python3 <插件目录>/scripts/audit-docs.py --root <项目根> --scope <范围>：入口或日志用 spine，决策用 adr，链接、测试引用或位置规则用 artifacts；首次整体接入、全项目审计或既有门禁要求时用 full。同一范围、版本和输入未变时复用结果，不因进入另一个 Skill 重跑。非零时保留退出码、具体失败与范围，不能给出整体通过结论；无关历史问题或疑似误报不阻断候选检索、问题定位及授权内独立文档的同步。文件不可读、基线无效或主源冲突使依据不可靠时，只暂停依赖该依据的判断和写入。修复后复跑受影响检查，未解决项如实保留；提交、PR 与发布仍须满足项目既有门禁，不能以局部修复或语义判断覆盖失败。已提交审查须对受检快照审计，可复用同一 base/head 的 PR 检查结果。

影响范围跨文件或尚不明确时，用现有脚本收集候选，再执行下方判读；已定位的小改动可直接用 rg 核对主记录和引用。输出是线索，不是过期结论：

# 已提交变更：比较共同祖先与 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。

1. 固定范围和版本。 记录实际 base/head 提交及其共同祖先，以共同祖先为比较起点，读取该起点与 head 的 diff 和旧／新正文；不要把当前工作区修复当作已提交内容。审查未提交修改时另列暂存／未暂存／未跟踪范围及相关文件哈希。基线或来源缺失时标未验证，不猜旧规则。
2. 提取改变的事实。 从代码、机器契约、配置及已确认需求中核对旧值、新值和原因，覆盖接口输入输出、流程步骤／条件、职责、依赖和外部副作用。契约删除一个字段并新增另一个字段，只能先记为删除／新增；有确认来源或实现证据才称重命名。内部修复若未改变对外事实，记录依据后结束相应同步检查。
3. 找到主记录与引用。 从项目地图、契约入口、需求主记录及 change_rules 命中项开始，再用 rg／git grep 查变更对象的路径、旧标识和相关术语，沿链接补读映射外的说明。已提交审查应对 head 快照检索。无链接但描述同一事实的说明也要核对；检索无结果不证明没有遗漏，记录实际检索范围及不可访问对象。
4. 逐条判读候选。 阅读命中位置的上下文，确认是否属于同一接口／流程、是否仍作为当前操作依据。当前正文与新事实冲突时给出具体位置、旧表述和对照证据，文件本次改过也不能跳过。历史记录、引用和无关同名字段不因关键词命中而要求改写；历史内容仍被当作当前指引时，报告误用它的入口。纯引用且目标有效时说明无需同步正文。
5. 核对重复与证据。 同一生效规则若有可独立编辑的多份正文，列出主记录与副本，建议其余位置改引用；主源不明先待核实，不自行选一份覆盖。机器契约、实现和历史各自承担职责，不按相同词句数量判重复。测试结果引用原始回执及对应版本／输入哈希，结果缺失或已过期时标未验证，不重抄结果补齐表格。
6. 交付并按变化失效。 在现有回复、PR 或审查记录中输出下表，绑定范围与版本。相关契约、代码或文档变化后重核受影响项，旧结论不自动沿用。不新建同步台账，不因普通待复核项一律阻断提交；沿用项目已有风险与合并要求。

先报告需要更新的当前说明，再列无需更新的反例和剩余缺口。没有实际运行文档中的步骤时，不声称已复现失败；未知项不能计入通过。治理成本只记录本轮实际核对、修改的文档及原始回执位置，耗时未测就注明未知，不预设节省比例。

可复跑的接口字段样例及审查验收见 接口变更场景。它只验证这一切片，不代表所有事实类型或业务项目都已覆盖。

实施后对照

完成实现后检查：

1. 实际改动是否解决 Spec/Issue 中的原始问题。
2. 实际 diff 是否超出已声明范围；超出项是否获得授权并补充影响分析。
3. 测试和人工证据是否真正覆盖成功标准，而非只证明命令运行过。
4. 文档事实改变时是否已同步受影响主记录；事实未变不更新，不逐份检查全部治理载体。
5. 是否遗留临时代码、兼容逻辑、迁移尾项或后续 Issue。

默认在交付回复中报告对照结论。只有高风险变更或用户要求正式评审时，才保存到 docs/reviews/。不要创建通用 REFLECTION.md。