---
name: github-issue-analysis
description: 从 GitHub Issue 出发，按「问题理解 → 复现条件 → 代码定位 → 根因 → 修复方案 → 测试方案」的流程做根因分析，产出结构化报告。Use when analyzing a GitHub issue to locate the root cause and propose a fix and test plan.
license: Apache-2.0
metadata:
  version: "0.1.0"
---

# GitHub Issue 根因分析

把一个模糊的 Issue 报告，转化为「可定位、可复现、可修复、可验证」的结构化根因分析。

## 何时使用

- 收到一个 bug Issue，需要定位根因并给出修复 / 测试方案。
- 需要从 Issue 描述、讨论、关联 PR/Commit 中还原问题全貌。

## 前置阅读

- [Issue 分析工作流](references/issue-workflow.md)
- [根因分析模板](references/root-cause-template.md)

## 工作流

### 1. 问题理解

1. 通读 Issue 标题、正文、复现步骤、环境信息（版本 / OS / 配置）。
2. 提取：**现象**（发生了什么）、**期望**（应该怎样）、**影响**（范围与严重度）。
3. 留意讨论区中其他人的补充、已尝试的排查、被否决的猜测。

产出：一句话问题陈述 + 关键事实清单。

### 2. 复现条件分析

1. 梳理触发条件：输入、状态、并发 / 时序、配置、数据。
2. 判断是**必现**还是**偶发**；偶发要标注可能的时序 / 竞态因素。
3. 若 Issue 没给全复现步骤，列出「缺失信息」。

产出：复现条件清单 + 待确认项。

### 3. 代码定位

1. 用 MCP（`github` / `filesystem`）找到相关代码路径：
   - 从 Issue 提到的报错栈、日志、函数名入手。
   - 检索关联 PR / Commit 看是否已改动或引入。
2. 定位到具体文件、函数、代码行。

产出：可疑代码位置列表（按相关度排序）。

### 4. 根因分析

按 [root-cause-template.md](references/root-cause-template.md)：

1. 对每个可疑位置，验证它能否解释「现象 + 复现条件」。
2. 用「五个为什么」向深层追问，区分**直接原因**与**根本原因**。
3. 排除法：列出被否定的假设及否定依据。

产出：一条有证据的因果链（现象 → 直接原因 → 根本原因）。

### 5. 修复方案

1. 给出最小、可回滚的修复（含代码片段）。
2. 说明为什么这样修、会引入什么新风险。
3. 若存在多个方案，给对比与推荐。

产出：推荐修复 + 备选方案 + 风险说明。

### 6. 测试方案

1. 回归测试：覆盖复现条件，确保修复有效。
2. 边界 / 并发测试：覆盖时序与边界输入。
3. 说明如何验证「不再复现」。

产出：测试清单（含可执行的测试要点）。

### 7. 汇总报告

按模板输出。

## 输出模板

```text
## Issue 根因分析报告

### 问题陈述
<现象 / 期望 / 影响，一句话 + 事实清单>

### 复现条件
- <条件 1>
- <待确认：...>

### 代码定位
- [文件:行] <可疑点，相关度说明>

### 根因
- 直接原因：<...>
- 根本原因：<...>
- 已排除的假设：<假设 + 排除依据>

### 修复方案
<推荐方案 + 代码片段 + 风险>

### 测试方案
- <回归 / 边界 / 并发测试要点>
```

## 约束与边界

- 结论必须有证据，无法确认的标注「待验证」。
- 区分「Issue 里的推测」与「代码里的事实」。
- 不修改代码，除非用户明确要求；只产出方案。
- 对不可信仓库，只做静态阅读，不执行其脚本 / 构建。