---
name: bug-analysis
slug: bug-analysis
displayName: 缺陷分析
version: 0.8.1
description: "对已确认的 Bug 做根因定位、影响分析、回归建议时使用——复现 → 读代码定位根因 → 影响五面分析 → 回归建议，条目（根因/影响/Severity 依据/修复建议/回归建议五个扩展字段）落盘为 Bug 条目。不用于：仅收集 Bug 证据（automated-e2e-testing / api-testing）、疑似未定性缺陷（test-case-writing 的 Cx 记录）。"
---

# Bug 分析（bug-analysis）

对**已确认**的 Bug 做根因定位、影响分析、回归建议。

- **输入**：Bug 报告（现象 + 复现步骤 + 证据）、代码仓库、（可选）需求模型 / 测试用例；批量执行场景下 A 类条目可来自失败分流表（`../core/triage.md` 产出，条目附带的 G/S 信号摘要与 evidence 字段即复现起点）
- **输出（落盘）**：Bug 条目（结构见下），**追加进测试报告**（`../core/report-template.md` §3 的根因分析 / 影响范围 / Severity 依据 / 修复建议 / 回归建议五个扩展字段即本 skill 的填写范围）
- **边界**：输入是**已确认**的 Bug（用户或执行结果已定性"这是缺陷"）；审查发现的**疑似**缺陷（待验证）归 `test-case-writing` 的 Cx 记录；回归**范围选择**归 `regression-testing`

## When to Use

- Bug 已经定性确认，需要定位根因（读到 `文件:行` 的分叉点）
- 需要评估 Bug 的影响面（同根因其他路径 / 脏数据 / 受影响用户）
- 修复后需要回归用例建议（修复验证 + 关联回归）

## When NOT to Use

- 还没定性（"这是 Bug 还是特性？"）→ 先经用户裁决（Bug 定性检查点，见 `qa`）；证据收集阶段 → `automated-e2e-testing` 工作流二 / `api-testing`
- 代码审查发现的疑似缺陷（未复现、未定性）→ `test-case-writing` 的 Cx 缺陷记录（待实测确认）
- 需要回归清单（哪些用例要跑）→ `regression-testing`（本 skill 产出回归用例**建议**）
- 端到端流水线 → `qa` 编排（本 skill 是其阶段 6）

## Bug 条目结构（追加进测试报告）

条目字段与填写模板**以 `../core/report-template.md` §3 为唯一来源**（此时加载），本 skill 只补充填写语义：

- **本 skill 的填写范围**：根因分析 / 影响范围 / Severity 依据 / 修复建议 / 回归建议五个扩展字段（报告 §3 中除「复验轮次」外的 8 个基础字段——严重程度 / 状态（初始"新建"，后续随回归结果更新，见 `../core/report-template.md` 使用约定 6） / 发现方式 / 复现步骤 / 预期行为 / 实际行为 / 证据 / 环境——由发现方已填，不重写）
- **根因分析**必须标注 status：**Inference**（读代码推断，未运行验证）或 **Verified**（已通过复现/最小实验验证，E3）——不伪装推断为事实（状态语义见 `../core/evidence.md` 第 3 节）
- **影响范围 / Severity 依据**逐条给来源；证据链标注 evidence 等级（E0–E4 + `文件:行`）

## 工作流

### 1. 复现（先拿到稳定证据）

- 按 Bug 报告步骤复现；复现不了 → 不硬分析，区分"环境差异 / 数据依赖 / 概率性"，向用户要环境与数据线索
- 复现过程采集证据：请求/响应原文、日志、截图（E3 运行证据）
- **概率性 Bug 战术**：低频复现不硬等——① **基线量化**：先跑足样本量建复现频率基线（N≥10 次记录触发次数，如"N≥10 触发 2 次"），修复后同条件复验对比，避免单次通过误判已修复；② **定向提频**三类：并发类加大并发度 / 缩短操作间隔复跑，时间类取时区 / 跨日 / 跨秒边界时刻集中触发，环境类换设备 / 数据 / 网络条件对比隔离触发因素

### 2. 读代码定位根因

- 从现象入口（页面/接口）向下追：入口 → 调用链 → 数据读写，定位到**具体行为与预期的分叉点**（`文件:行`）
- 检查常见根因类别：边界未防护 / null 未兜底 / 状态竞态 / 事务不完整 / 缓存不一致 / 权限漏判 / 并发覆盖 / 配置漂移
- 根因结论标注 status：**Inference**（代码推断，未运行验证）或 **Verified**（已通过复现/最小实验验证，E3）——不伪装推断为事实

### 3. 影响分析（五面）

- **功能面**：同一根因会波及哪些入口/路径（grep 相同模式的其他调用点）
- **数据面**：是否已产生脏数据、影响存量数据的范围
- **用户面**：受影响角色与操作路径
- **安全面**：该缺陷是否构成**可被利用的窗口**（越权可达 / 敏感数据暴露 / 注入面）——命中即 Severity 上浮一级（S2→S1、S1→S0，S0 封顶）。注意与第 4 步定级规则的分工：安全面用于**潜在窗口**的上浮；已构成**实际安全后果**（数据丢失 / 资损 / 实际越权达成）的直接 S0，不适用上浮口径
- **修复波及面**：预期修复方式会改动哪些代码 / 配置 / 数据——修复本身改变的行为就是回归建议的直接输入（衔接第 5 步）

### 4. 定级与修复建议

- Severity 按后果分级（S 系与用例优先级 P 系分离）：数据丢失/资损/**已构成实际安全后果**（实际越权达成的数据暴露等）→ S0；核心功能**主路径**不可用 → S0，核心功能**旁路**不可用 → S1；部分降级 → S1；体验问题 → S2。仅构成**潜在可利用窗口**的安全问题不上浮到 S0，按第 3 步安全面上浮一级（两处口径互证，防同触双规则）
- 修复建议给**方向**（如"导入路径补同创建路径的校验"），不越界替开发写补丁

### 5. 回归建议（衔接 regression-testing）

- 修复验证用例：直接复现该 Bug 的用例（没有则建议新增，给 TC 编号建议）；建议新增的用例按 `../core/case-format.md` 格式与 `../core/executability.md` 可执行性标准描述，保证落到用例文件即可执行
- 关联回归：同根因模式的其他路径 + 该功能的锚点用例
- **双向互链**：本条目编号写进对应回归清单的"关联 Bug"行、清单中修复验证用例的 TC 编号回填本条目"回归建议"——Bug 清单 ↔ 回归清单双向可溯（清单侧模板见 regression-testing）
- 回归**范围选择**（跑哪些既有用例、分级）移交 `regression-testing`

### 6. 落盘

单阶段独立使用：Bug 条目追加进测试报告对应条目（补根因分析等五个扩展字段）；无报告时可新建报告文件（按 `../core/report-template.md`）。作为流水线 Bug 分析阶段运行：不新建、不改写最终测试报告——条目统一写 `{项目}/Bug条目_{日期}.md` 中转文件，由编排收尾阶段拼装，避免与收尾报告同名双写造成双数据源。
- **沉淀判定**（收尾必做）：本次根因+修法若过 `qa-memory` 的写入判据（"三个月后新会话重测能省一次重新发现"），按其流程沉淀为项目 `.qa/` 知识库的 defect 条目（evidence 指向本 Bug 条目），供后续会话直接复用

## Common Mistakes

| 错误 | 后果 | 正确做法 |
|------|------|---------|
| 未复现就开始分析 | 根因建立在想象上 | 先复现拿 E3 证据；复现不了先要线索 |
| 根因推测定性为事实 | 虚假结论传播 | status 标注 Inference/Verified（`../core/evidence.md`） |
| 现象当根因（"接口超时，根因：接口超时"） | 分析空转 | 追到行为与预期分叉的 `文件:行` |
| 影响范围只看单点 | 同根因其他路径漏修漏测 | grep 相同模式，功能/数据/用户/安全/修复波及五面分析 |
| 越界写补丁代码 | 职责越界、干扰开发 | 给修复方向与验证建议 |
| 把回归范围选择也做了 | 与 regression-testing 职责重叠 | 本 skill 出回归**建议**，范围选择移交 |
| 疑似缺陷（未定性）直接进本流程 | 与 Cx 记录职责混淆 | 输入必须是已确认 Bug；未定性先走裁决 |