playbook/.claude/skills/root-cause-tracing/SKILL.md

name: root-cause-tracing description: Root cause analysis (RCA) and tracing failures back to the original trigger across call stacks and data flows. Triggers: root cause, RCA, trace, why, 根因, 溯源, 复盘, 定位根因.

Root Cause Tracing（根因溯源 / RCA）

When to Use

• 错误发生在深层栈/异步链路/多模块交互处，症状离根因很远
• 需要写清楚“为什么会这样”以及“如何防止再发生”

Inputs（required）

• Symptom：错误现象 + 触发条件（脱敏后的日志/堆栈/截图）
• Repro：复现步骤（或说明目前无法稳定复现）
• Context：关键业务不变量/约束（例如权限边界、数据一致性要求）
• Timeline：最近变更范围（commit/PR/发布时间点，若可提供）

Procedure

1. Anchor the Symptom

   • 把“现象”翻译成可验证的断言（expected vs actual）
   • 明确影响面：用户/数据/安全/性能/成本

2. Trace the Path

   • 从症状点沿着：调用栈 → 异步链路 → 事件/消息 → 数据读写路径回溯
   • 标注每一跳的关键输入/输出（哪些值第一次变“坏”）

3. Find the First Divergence

   • 找到“最早的错误状态/错误输入/错误决策点”
   • 用对照实验证明：没有这个条件就不会出现症状

4. Prove the Root Cause

   • 用证据闭环：日志/trace/断言/最小复现/二分定位（如 git bisect）
   • 区分：
     • Root cause：触发源（必须修）
     • Contributing factors：放大器/缺失的 guardrail（建议补）

5. Fix at the Root + Add Guardrails

   • 在触发源处修复（输入校验/状态机/边界条件/并发控制）
   • 增加防线：断言、错误处理、熔断/限流、幂等、测试用例

Output Contract（RCA 模板）

• Impact：影响范围（用户/数据/安全/性能）+ 严重级别
• Trigger：触发条件（最小化）
• Root Cause：根因（定位到模块/函数/配置/依赖）
• Evidence：证据链（复现、日志片段、对照实验、定位方法）
• Fix：修复摘要（为什么这样修、是否兼容、回滚策略）
• Prevention：预防措施（测试、监控、校验、文档、流程）

Guardrails

• 只写“可证伪”的根因，不写形容词结论
• 无复现时：先补可观测性与缩小范围，再讨论修复