Bug Impact Analysis

---
name: bug-impact-analysis
description: Bug 修复影响分析。分析修复的根因是否被真正解决、修复是否引入副作用、影响范围和回归风险。触发短语：'分析这个bug的影响'、'这个修复会影响什么'、'bug impact analysis'、'评估修复风险'，或在用户描述 Bug 现象后要求自动分析时触发。
---

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

## AI 说明

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

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

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

## 核心原则

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

## 执行流程

### Step 0：上下文收集

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

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

```markdown
## 🔍 Bug 根因分析

**现象**：[Bug 的外在表现]

**直接原因**：[什么代码行为导致了这个现象]

**根因链**：
直接原因：[A]
    ← 间接原因：[B]
        ← 根本原因：[C]

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

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

### Step 2：修复方案评估

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

#### 2.1 修复是否解决根因

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

#### 2.2 修复判定

**情况 A：修复对症**
> 修复直接解决了根因，且方案合理。

**情况 B：修复治标不治本**
> 修复只处理了表象，根因仍在。建议：_[更根本的修复思路]_。

**情况 C：修复过度**
> 修复引入了不必要的复杂度或改变了不应改变的行为。建议简化方案。

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

```markdown
## 🩹 修复方案评估

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

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

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

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

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

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

#### 3.0 基础：获取影响面数据

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

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

#### 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 输出影响分析报告

```markdown
## 📊 影响范围分析

### 调用链影响

| # | 调用方 | 位置 | 影响级别 | 说明 |
|---|--------|------|----------|------|
| 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：回归风险评估

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

```markdown
## 🚨 回归风险评估

### 风险总览

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

### 高危风险详情

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

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

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

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

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

### Step 5：测试建议

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

```markdown
## 🧪 测试建议

### 必须补充的测试

| 测试场景 | 优先级 | 原因 | 建议测试类型 |
|----------|--------|------|--------------|
| [场景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：后续步骤

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

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

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 调用时跳过，由调用方统一集成）：

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

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

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

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

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

**存储路径映射**：

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