root-cause-investigator

根因调查器

运用系统化的 5 Whys 方法，找出问题的根本原因，而不是只处理表面症状。通过结构化的证据收集与分析，引导深入调查。

触发条件

• 错误、缺陷或意外行为
• 构建失败或测试失败
• 性能问题或性能下降
• 集成问题
• 任何“无法正常工作”的情况

5 Whys 方法

系统地连续追问五次“为什么”，层层深入，找到根本原因：

1. Why #1：找出直接原因（症状）
2. Why #2：揭示流程／工作流问题
3. Why #3：发现系统层面的问题
4. Why #4：找出设计／架构问题
5. Why #5：揭示根本原因

调查工作流

1. 收集初始背景信息

收集与问题相关的信息：

## Issue Summary
[brief description of reported problem]

## Initial Symptoms
- what user is experiencing
- error messages or logs
- observable behavior

## Context Gathering
- environment details
- recent changes
- related components
- steps to reproduce

2. 应用 5 Whys 分析

按逐步深入的方式组织调查：

## 5-Why Analysis

### Why #1: [surface cause]
Evidence: [logs, errors, behavior]
Impact: [what this affects]

### Why #2: [deeper cause]
Evidence: [code, configuration]
Impact: [cascading effects]

### Why #3: [system cause]
Evidence: [architecture, dependencies]
Impact: [broader implications]

### Why #4: [process/design cause]
Evidence: [patterns, decisions]
Impact: [long-term effects]

### Why #5: [root cause]
Evidence: [fundamental issue]
Impact: [core problem]

3. 找出根本原因

记录需要处理的根本问题：

## Root Cause Identified
[the fundamental issue that needs addressing]

## Recommended Investigation Areas
- specific files to examine
- components to test
- systems to verify

调查原则

1. 避免预设解决方案——先理解问题，再着手修复
2. 收集证据——不要臆测，要用数据验证
3. 考虑多种原因——问题往往由多个因素共同导致
4. 记录调查结果——清晰的文档可以避免问题重现
5. 系统性思考——考虑更广泛的影响
6. 质疑假设——不要想当然地认为“它应该能正常工作”
7. 使用版本控制——检查问题何时引入

使用参考资料

调查过程中按需加载参考文件：

• references/patterns.md——按类别列出的常见根因模式（配置、竞态条件、资源耗尽、集成失败、构建／部署问题）
• references/techniques.md——包含命令示例的调查技巧（错误分析、代码调查、依赖项分析、环境调查）

最佳实践

• 在找出根本原因之前，不要急于提出解决方案
• 调查要全面、循序渐进
• 记录每个分析层级的证据
• 使用具体数据验证假设
• 从多个角度考虑问题（技术、环境、架构、外部依赖项、流程）

目标是找到根本原因，而不只是修复表面症状。