Bug Impact Analysis（Bug 修复影响分析）

AI 说明

目的：对 Bug 修复进行系统性影响分析——不只确认"修好了没"，更要回答"修了会影响什么"，确保修复是有底气的而非"改了就完"。

功能：借鉴 requirement-mining 的根因分析法定位 Bug 根因、评估修复是否对症，再结合 code-review 的多维度影响检查（调用链/条件路径/数据流/执行场景），产出含回归风险评估与测试建议的结构化报告。

使用场景：用户提供 Bug 现象与修复代码（diff/commit）要求评估修复风险时；仅有 Bug 描述需先做根因诊断时；修复合入前需要影响面与回归风险背书时；被 debug 调用做修复前方案评估或修复后影响质检时。

核心原则

先打根因，再评修复：必须先搞清 Bug 为什么发生，再评估修复是否对症
影响优先于正确：修复可能"局部正确"，但判断其是否安全的关键在于"会影响什么"
横向+纵向双重覆盖：纵向追溯调用链（谁调用了被改的代码），横向展开条件路径（不同参数/状态下是否都安全）
假设可验证：对影响范围的推断，给出可验证的建议（如运行特定测试、检查特定模块）
最小化交互：自主推理影响面，仅在关键信息缺失时提问
专家资产复用：分析前主动查询专家团，复用已知坑、实现导航等资产加速诊断
证据不足转排错：静态推理不足以支撑根因或影响结论时，转 debug 用运行时证据（复现/插桩/跑测试）取证，不凭推理定罪。详见「与 debug 的互引」
容错迭代：用户纠正后快速更新分析

执行流程

Step 0：上下文收集

在分析之前，收集必要信息：

Bug 描述：用户报告的 Bug 现象（如果有复现步骤、报错日志更好）
修复代码：已修复的代码变更（git diff、commit hash、或直接粘贴）
被改代码上下文：读取被修改文件的完整内容，理解函数/类/模块的完整职责
调用关系：通过符号搜索找到被修改代码的调用方和被调方
专家团查询：调用 use_skill("expert-solution-workflow") 查询被修改模块的相关经验、解决方案或记忆（如业务专家资产包；查询失败或不可用，忽略此步骤继续正常流程）。如有，加载相关资产（已知坑、实现导航、架构知识等），作为后续分析的重要参考。"已知坑"有助于快速定位根因，"实现导航"有助于理解代码逻辑和影响范围
强关联关系查询：分析影响范围前，调用 use_skill("ki-memory-lookup") 检索被改模块的强关联关系（跨模块契约/业务耦合），识别"改这里牵动了哪些其他模块"，作为影响范围分析的直接输入（查询失败或无可用记录，忽略继续）
决策记忆查询：调用 use_skill("ki-memory-lookup") 的决策记忆策略查被改模块的历史决策，核对其「重新评估触发条件」是否已满足；满足则说明该决策应当重新评估，作为影响范围分析的补充输入（查询失败或无可用记录，忽略继续）

如果只有 Bug 描述没有修复代码，先进入 Step 1 做根因诊断，帮助定位问题后，再对修复方案做影响分析；若定位根因需要运行时证据（复现/插桩/跑测试），调用 use_skill("debug") 取证并修复——其 Step 4 根因结论可直接作为本 skill Step 1 输入，修复完成后回到本 skill 做质检。全部转交时机见「与 debug 的互引」。

Step 1：Bug 根因分析

Bug 不仅仅是"哪里出错了"，更关键的是"为什么出错了"。借鉴 requirement-mining 的 Step 5 根本性分析法。

1.1 定位核心问题

Bug 的直接原因是什么？（如：空指针、类型错误、边界条件遗漏）
Bug 为什么会出现？（如：缺少校验、设计遗漏、外部依赖变化）
根因链：直接原因 ← 间接原因 ← 根本原因，一层层往下挖

1.2 评估根因的严重度

根因类型	风险等级	说明
系统性缺陷	🔴 高	设计层面问题（如缺少错误处理机制、接口契约不明确），同类问题可能广泛存在
实现遗漏	🟡 中	某个边界条件或异常路径未覆盖
外部依赖变化	🟡 中	上游接口/数据格式变更导致
单点疏忽	🟢 低	纯编码疏忽（如拼写错误、类型写错）

关键判断：根因是系统性的还是单点的？如果是系统性缺陷，同类 Bug 可能存在于其他位置，需要标记出来。

证据不足时转交：若静态推理无法唯一定位根因（多个假设难定夺），或根因结论缺运行时支撑，调用 use_skill("debug") 取证（复现/插桩/跑测试），拿到证据后回填本 Step，不凭推理定罪。

1.3 输出根因诊断

## 🔍 Bug 根因分析

**根因链（🕸 文字树，自上而下）**：
现象：[Bug 的外在表现]
│
▼
直接原因：[什么代码行为导致了这个现象]
│
▼
间接原因：[B]
│
▼
根本原因：[C]　← 根因

**根因类型**：[系统性缺陷 / 实现遗漏 / 外部依赖变化 / 单点疏忽]

**同类风险排查**（仅系统性缺陷时）：
- 同样的模式在哪些地方也存在？
- [列出可能受同类问题影响的位置]

🕸 文字树最小语法（跨 skill 统一，4 条）：① │+▼ 串联向下、├─ └─ 分支 / 并行；② 节点挂状态与关键信息，关键节点打标记（← 根因 / ← 待验证 / ← 系统性缺陷）；③ 多假设并列时分 ├─ └─、单链因果用 │+▼；④ 只画结构类信息（根因链 / 影响链 / 数据流），清单与判定仍用表格；节点 ≤15、层级 ≤4，不画决策路径与审批流。

Step 2：修复方案评估

有了根因分析后，评估修复方案是否对症。借鉴 requirement-mining 的 Step 5.2 方案评估法。

2.1 修复是否解决根因

检查维度	问自己
根因覆盖率	修复是否解决了根因，还是只处理了表面症状？
问题完整性	修复是否覆盖了 Bug 的所有触发场景？
方案级别	修复是"打补丁"还是"修正设计"？

2.2 修复判定

情况 A：修复对症

修复直接解决了根因，且方案合理。

情况 B：修复治标不治本

修复只处理了表象，根因仍在。建议：[更根本的修复思路]。

情况 C：修复过度

修复引入了不必要的复杂度或改变了不应改变的行为。建议简化方案。

情况 B 的落地：更深层修复的实施交 use_skill("debug") 走最小修复闭环（修复 + 回归验证），完成后回到本 skill 质检——本 skill 不改代码，只给出更根本的修复思路。

## 🩹 修复方案评估

**修复内容**：[简述修复做了什么]

**判定**：[情况 A / B / C]

**理由**：[为什么这样判断]

**如果治标不治本**：
- 根因：[XXX]
- 建议的更深层修复：[YYY]
- 当前修复的局限性：[ZZZ]

Step 3：影响范围分析（核心步骤）

这是本 skill 的核心。系统性地分析修复会影响到哪些代码。

3.0 基础：获取影响面数据

先判有没有代码索引（仓库有 .fe-index/ 时，这一步最省）：use_skill("index-lookup") 读 .fe-index/INDEX.md 匹配被改文件——后端查 tables.md（表 → 模块反向）与 modules/*.md（被依赖 + 事件/命令耦合），前端查 apis/*.md（接口 → 页面）。索引给的是候选影响面清单，逐条仍要回源码确认（无索引 / 未命中 / 过期 → 按原流程，不阻塞）。

查询调用关系数据库（如可用），获取被修改代码的符号信息：

被修改的函数/方法/类：
  - 直接调用方（谁调用了它）
  - 间接调用方（调用方的调用方）
  - 被调方（它调用了谁）
  - 同模块相关函数
  - 接口/抽象类的其他实现

3.1 纵向影响：调用链分析

沿着调用链向上追溯，分析修复对每个调用方的影响：

调用方	调用位置	调用方式	是否受影响	影响说明
`function_A()`	`file_a.py:42`	直接调用	✅/⚠️/❌	[修改对调用方的影响]
`function_B()`	`file_b.py:100`	间接调用	✅/⚠️/❌	[二级调用方是否受影响]
`ClassName.method()`	`file_c.py:88`	继承覆盖	✅/⚠️/❌	[子类实现是否受影响]

影响级别说明：

✅ 无影响：调用方不依赖被修改的行为
⚠️ 需检查：调用方可能受影响，建议人工确认
❌ 确定受影响：调用方的行为会因修复而改变，必须相应调整

3.2 横向影响：条件路径分析

借鉴 code-review 的维度 0.7，检查修复在不同参数/条件下的行为：

参数空间枚举：

参数/条件组合	修复前行为	修复后行为	语义是否一致
`param=A`	[原行为]	[新行为]	✅/⚠️/❌
`param=B`（边界）	[原行为]	[新行为]	✅/⚠️/❌
`param=空/None`	[原行为]	[新行为]	✅/⚠️/❌
`param=异常值`	[原行为]	[新行为]	✅/⚠️/❌

关键问题：

修复是否在某些参数路径上改变了返回值的语义（类型、含义、空值处理）？
修复是否在正常路径生效但在异常路径不生效（或相反）？
修复是否改变了函数的副作用（日志、缓存更新、状态变更）？

3.3 深度影响：数据流分析

修复是否改变了数据的流向或状态？

检查维度	分析内容
返回值变化	返回值的类型/空值/含义是否变化？调用方是否按旧语义消费返回值？
副作用变化	修复是否新增/移除了 I/O、缓存写入、状态变更、事件触发？
异常传播	修复是否改变了异常的类型或抛出时机？调用方的异常处理是否匹配？
全局状态	修复是否影响了全局变量、配置项、单例状态？

3.4 执行场景分析

借鉴 code-review 的维度 0.8，分析修复在不同执行场景下的表现：

场景	修复前行为	修复后行为	语义一致性
正常执行	[行为]	[行为]	✅/⚠️/❌
首次执行/初始化	[行为]	[行为]	✅/⚠️/❌
重复执行	[行为]	[行为]	✅/⚠️/❌
高并发执行	[行为]	[行为]	✅/⚠️/❌
降级/容错	[行为]	[行为]	✅/⚠️/❌
外部依赖失败	[行为]	[行为]	✅/⚠️/❌

待验证项的运行时验证：上述分析中标注 [需确认] 或 ⚠️ 需检查的影响项，建议调用 use_skill("debug") 用运行时证据验证（构造复现用例/插桩观察真实行为）。凡能用复现验证的影响结论，不凭静态推理定论。

3.5 输出影响分析报告

## 📊 影响范围分析

### 调用链影响

**🕸 影响链文字树**（树看结构：谁牵动谁、几层；**受影响判定与说明仍看下方表**，树的级别标记须与表一致；调用方 ≥2 或有二级调用方时必画，最小语法见 Step 1.3）：

```text
`update_status()`（被修复函数）
├─ `handler()`（api.py:42）　← ❌ 确定受影响
│  └─ `dispatch()`（router.py:88）　← ⚠️ 需检查
└─ `scheduler()`（cron.py:100）　← ⚠️ 需检查
   └─ （无下游）
```

| # | 调用方 | 位置 | 影响级别 | 说明 |
|---|--------|------|----------|------|
| 1 | `handler()` | `api.py:42` | ❌ 确定受影响 | 返回值类型从 `dict` 变为 `dict | None`，调用方需要增加判空 |
| 2 | `scheduler()` | `cron.py:100` | ⚠️ 需检查 | 使用了被修改函数的返回结果，但已有判空处理 |
| 3 | `test_foo()` | `test_api.py:55` | ✅ 无影响 | 测试直接调用，无依赖 |

### 条件路径影响

| 参数条件 | 修复前 | 修复后 | 一致性 | 说明 |
|----------|--------|--------|--------|------|
| `user_type="admin"` | 返回全量数据 | 返回全量数据 | ✅ | 行为不变 |
| `user_type=None` | 抛出 TypeError | 返回空列表 | ⚠️ | 语义变化，调用方可能依赖旧行为 |
| `user_type=""` | 返回空列表 | 返回空列表 | ✅ | 行为不变 |

### 数据流影响

- **返回值**：[是否有变化及影响]
- **副作用**：[是否有变化及影响]
- **异常传播**：[是否有变化及影响]
- **全局状态**：[是否有变化及影响]

### 场景覆盖

| 场景 | 影响 | 说明 |
|------|------|------|
| 正常执行 | ✅ | 行为符合预期 |
| 高并发 | ⚠️ | 修复移除了锁检查，并发下可能出问题 |
| 降级容错 | ❌ | 异常路径未被修复，同样问题仍存在 |

Step 4：回归风险评估

综合以上分析，对修复引入回归的风险做分级评估：

## 🚨 回归风险评估

### 风险总览

| 风险等级 | 数量 | 说明 |
|----------|------|------|
| 🔴 高危 | N | 确定会导致其他功能异常 |
| 🟡 中危 | N | 可能影响，需人工确认 |
| 🟢 低危 | N | 几乎无影响 |

### 高危风险详情

**[R1] 风险名称**
- 影响范围：[受影响的功能/模块]
- 触发条件：[什么时候会出问题]
- 影响表现：[用户会看到什么]
- 修复建议：[如何避免这个回归]

### 未被修复的同类风险

如果根因是系统性的，列出**此次修复未覆盖的同类问题**：

- `file_x.py:line_y`：同样的模式，同样的风险
- `module_z/xxx.py`：相同的外部依赖处理，可能同样有问题

**同类风险的确认**：上述位置是否真被触发，交 `use_skill("debug")` 逐个复现确认；**未确证的只标为「疑似同类」**，不计入确定风险。

Step 5：测试建议

基于影响分析，给出需要补充的测试：

## 🧪 测试建议

### 必须补充的测试

| 测试场景 | 优先级 | 原因 | 建议测试类型 |
|----------|--------|------|--------------|
| [场景1] | P0 | [如果没有这个测试，回归风险高] | 单元/集成/E2E |
| [场景2] | P1 | [建议补充以提升覆盖] | 单元/集成/E2E |

### 回归测试检查清单

- [ ] 调用方 `function_A()` 的现有测试是否仍然通过？
- [ ] 边界条件 `param=None` 是否被测试覆盖？
- [ ] 异常路径 `xxx_fails` 是否被测试覆盖？
- [ ] 并发场景下的行为是否被验证？

Step 6：输出完整分析报告

将以上分析合并为结构化报告：

# Bug 修复影响分析报告

## 📋 基本信息
- **Bug 描述**：[用户原始描述]
- **修复内容**：[修复摘要]
- **影响文件**：[文件列表]
- **分析时间**：[时间]

## 🔍 Bug 根因分析
[Step 1 输出]

## 🩹 修复方案评估
[Step 2 输出]

## 📊 影响范围分析
### 调用链影响
### 条件路径影响
### 数据流影响
### 场景覆盖
[Step 3 输出]

## 🚨 回归风险评估
[Step 4 输出]

## 🧪 测试建议
[Step 5 输出]

## 📝 总结与行动项

| 优先级 | 行动项 | 关联影响 |
|--------|--------|----------|
| P0 | [必须做的事] | R1, R2 |
| P1 | [建议做的事] | C1 |
| P2 | [可选的增强] | - |

Step 7：后续步骤

分析报告输出后，询问用户选择后续动作：

分析报告已完成，请选择后续步骤：

1. 🩹 进行修复 — 基于分析报告中的建议，对代码进行修复（多方案/核心路径时走 debug 最小修复闭环）
2. 🔬 转 debug 取证 — 影响项标注 `[需确认]`、同类风险待复现确认，或根因缺运行时证据时取证验证
3. 🧪 发起 challenger 质疑 — 对分析报告本身进行二次审查，检查是否存在遗漏或误判

请选择 [1 / 2 / 3 / 无需后续]

选择 1：进行修复

根据报告中 P0 行动项，对代码实施修复
多方案取舍或涉及核心路径时，交 use_skill("debug") 走最小修复闭环（修复 + 回归验证），完成后回到本 skill 复检
修复完成后自动进入 writing-pipeline（auto-review → 视复杂度触发 challenger）

选择 2：转 debug 取证

调用 use_skill("debug")，把待验证项（复现条件/插桩点/需确认的调用方）交给它取证
取证结论回填影响分析报告，更新风险等级与测试建议后，再让用户选择是否修复

选择 3：发起 challenger 质疑

调用 use_skill("challenger")，对本次分析报告进行二次审查
challenger 将质疑策略聚焦于：根因是否找对、影响面是否遗漏、风险评估是否过度/不足
质疑结果反馈后，用户可选择更新报告或直接进入修复

与 debug 的互引（取证与落地）

完整分工与双向接力全景以 debug skill 为 SSOT，本节只定义本 skill 转交 debug 的场景。

时机	触发条件	动作
无修复代码	只有 Bug 描述，且定位根因需运行时证据	转 debug 取证修复；其 Step 4 根因结论直接作为本 skill Step 1 输入
Step 1 根因证据不足	静态推理无法唯一定位根因，或多假设难定夺	转 debug 复现/插桩取证，证据回填后再继续
Step 2 情况 B（治标不治本）	更深层修复方案需要落地	实施交 debug 最小修复闭环（修复 + 回归验证），完成后回本 skill 复检
Step 3 影响项待验证	标注 `[需确认]` 或 ⚠️ 需检查	转 debug 用运行时证据验证，不凭静态推理定论
Step 4 同类风险	列出的同类位置是否被真实触发	逐个交 debug 复现确认；未确证只标「疑似同类」

方向不对称提示：debug 修复完成后默认可转本 skill 质检（单向强依赖）；本 skill 转 debug 是条件触发——仅当结论缺运行时证据、或需要落地修复时才转，静态可定论的不转，避免无谓的排错开销。

互转终止规则：同一问题在两侧往返各限一次（本 skill → debug → 本 skill 后停止互转），输出「阻塞清单」请用户补充信息或人工介入。完整规则以 debug skill 为 SSOT。

行为边界

分析阶段不修改代码：分析过程只输出报告，不直接修改代码；仅当用户在 Step 7 明确选择"进行修复"后，方可实施代码修复
结论分工：本 skill 只出影响分析结论，根因取证与修复实施交 debug；被 debug 调用（修复前评估/修复后质检）时只做静态影响推理，不接管修复
不替代测试：测试建议用于指导，实际测试仍需开发者编写和执行
推理可追溯：每个影响结论必须关联到具体的调用链、条件路径或数据流推理
不确定性标注：对无法确认的影响标注 [需确认]
根因优先：在分析影响前必须先找到根因，否则影响分析缺乏基准
专家资产优先：当专家团存在相关模块资产时，优先利用已知坑和实现导航辅助分析，减少重复调研
不编造调用关系：必须通过代码搜索确认调用关系，不允许凭空推测

需求管理集成

当项目配置了 .requirements/config 且 storage_path 指向有效目录时，独立使用的分析完成后自动执行集成操作（被其他 skill 调用时跳过，由调用方统一集成）：

获取需求上下文：分析前，如果关联了 REQ-ID，先读取需求信息作为参照：

req list --id {REQ-NNN} --deps

写入分析报告到需求目录后，调用 req update 注册文档关联：

req update {REQ-NNN} \
  --docs add review/bug-impact-analysis.md,review --changelog "完成 Bug 修复影响分析"

错误处理：
- 需求 ID 不存在或未关联 REQ → 跳过集成，不影响分析本身
- 文件锁超时 → 自动重试 1 次，仍失败则告知用户

存储路径映射：

产出物	存储路径	docs 类型
Bug 修复影响分析报告	`review/bug-impact-analysis.md`	`review`

bug-impact-analysis

SKILL.mdskills/bug-impact-analysis/SKILL.md