qa-bug-root-cause-analysis

当某个 Bug 频繁复现、线上有缺陷需要做事后分析、或者发现同一类问题反复出现需要根治时使用此技能。从症状出发用 5Why、因果图和鱼骨图等方法系统化定位缺陷根源，区分直接原因、间接原因和系统原因。不要只修症状——根因分析的价值在于找到让同类 Bug 不再发生的系统性改进措施，同时分析漏测原因来优化测试设计。 ⚠️ 本技能示例可能调用外部日志/监控工具，请在受控环境执行。触发场景：Bug根因、根因分析、为什么出Bug、深层原因、定位问题、排查方向、反复出现同类问题需要根因改进时。 Use when the user asks about: root cause analysis for recurring or escaped defects using 5 Whys, fishbone diagrams, and causal diagrams, plus escaped-defect analysis.

kokxi@kokxi

Install

openclaw skills install @kokxi/qa-bug-root-cause-analysis

⚠️ 本技能单独使用效果有限，建议配合完整技能集（12 步工作流）使用。安装：npx skills add Kokxi/qa-test-skills

⚠️ 安全警告：本技能的示例可能涉及订单号、支付金额、截图、身份证、手机号等敏感数据。实际使用时请勿粘贴真实生产数据、客户信息或财务凭证；测试前应脱敏/掩码处理。本技能仅在 workspace/ 输出评估文件，不持久化、不外传、不跨会话复用。

Bug根因分析

核心原则

看到错误，能快速缩小根因范围——这不是魔法，是可学习的映射模式。

加载时机

什么时候读	读哪个
定位到具体症状后，查对应的根因与验证手段	`references/symptom-rca-map.md`

症状分类与根因映射的完整内容已下沉至 references/symptom-rca-map.md，避免每次触发都占用上下文。

分析流程

步骤1：收集信息

text

信息收集清单：
├─ 症状描述：具体表现是什么？
├─ 复现步骤：怎么复现？
├─ 环境信息：什么环境下出现？
├─ 时间信息：什么时候出现？
├─ 影响范围：影响多大？
└─ 相关日志：日志有什么？

步骤2：分类症状

text

根据症状表现分类：
- 返回错误 → 代码/数据/配置/依赖层
- 数据不对 → 写入/读取/同步/转换问题
- 性能退化 → 数据库/代码/缓存/资源问题
- 没反应 → 前端/网络/后端/中间件问题
- 偶发问题 → 并发/环境/数据/时序问题

步骤3：缩小范围

text

根据症状分类，逐层排查：
1. 先排除外部因素（依赖/环境）
2. 再排除配置因素
3. 再排查数据因素
4. 最后排查代码因素

步骤4：验证假设

text

验证方法：
1. 复现问题
2. 修改假设条件
3. 验证问题是否消失
4. 确认根因

根因分析表

Bug ID	症状分类	根因方向	根本原因	验证方法
BUG-001	返回错误	数据层	数据格式错误	修改数据后验证
BUG-002	性能退化	数据库	慢查询	添加索引后验证

症状分类速查

从现象到根因方向

现象	症状分类	大概率方向	优先排查
报500错误	返回错误	后端异常/数据异常	日志ERROR + 入参数据
返回空数据	返回错误	查询条件/权限过滤	SQL日志 + 权限配置
页面白屏	返回错误	前端解析/接口数据格式	F12看接口响应
金额不对	数据不对	计算逻辑/精度问题	核对计算公式
状态不更新	数据不对	状态机/回调处理	检查状态流转日志
账单对不上	数据不对	数据一致性/事务问题	核对多个数据源
页面越来越慢	性能退化	慢查询/数据累积	慢SQL日志
高峰期就挂	性能退化	并发/资源不足	压测复现+监控
点按钮没反应	没反应	前端事件绑定/接口不通	F12看请求是否发出
加载中不动	没反应	后端处理卡住/死锁	线程堆栈+DB锁查询
偶尔支付失败	偶发问题	并发冲突/超时	并行多次复现
特定时间出问题	偶发问题	定时任务/缓存过期	核对定时任务时间+缓存策略
只有某用户出问题	偶发问题	数据隔离/权限	对比正常/异常用户数据

输出示例

Bug描述："用户支付成功但订单状态仍为待支付" → 症状分类：数据不一致（症状2） → 根因映射：数据层问题→检查支付回调处理逻辑 → 分析流程：

收集信息：支付网关回执、订单日志、数据库记录
分类症状：数据不一致
缩小范围：支付回调→订单状态更新→数据库写入
验证假设：手动触发回调验证状态变更

Bug描述："页面加载越来越慢" → 症状分类：性能退化（症状3）→ 数据库/缓存层排查

检查清单

根因分析完成后检查：

是否收集了完整信息？
是否正确分类症状？
是否逐层排查根因？
是否验证了根因假设？
根因描述是否清晰？
验证方法是否可行？