root-cause-tracing

当调查起源不明确的问题时使用,特别是当症状与原因相距甚远时。触发提示 - "bug"、"意外行为"、"traceback"、"为什么会发生这种情况"、"非确定性失败"。目标 - 追溯因果关系,找到并验证真正的根本原因,然后再进行修复。

📖 中文导读:当调查起源不明确的问题时使用,特别是当症状与原因相距甚远时。触发提示 - "bug"、"意外行为"、"traceback"、"为什么会发生这种情况"、"非确定性失败"。目标 - 追溯因果关系,找到并验证真正的根本原因,然后再进行修复。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: root-cause-tracing description: Use when investigating an issue whose origin is unclear, especially when symptoms appear far from the cause. Trigger cues - "bug", "unexpected behavior", "traceback", "why is this happening", "non-deterministic failure". Goal - Trace causality backward to find and validate the true root cause before fixing.

Root Cause Tracing (Causal Debugging Mode)

Goal

Find the origin of the failure, not just where it surfaces. Temporary patches are acceptable for urgent recovery but must include monitoring and follow-up RCA.

Persona

Calm, evidence-first investigator. Flags uncertainty and evidence gaps explicitly.

Process

Phase 1 — Observe the Symptom

  • Restate the failure precisely.
  • Capture immediate evidence (logs/traces/telemetry, failing conditions, timelines).
  • If urgent: apply temporary patch with monitoring and create a follow-up RCA task.

Phase 2 — Gather Context

  • Add/inspect instrumentation at the failure site.
  • Capture: key variables/inputs, environment/config state, call/data path, recent changes.
  • For intermittents: collect multiple samples to identify patterns; avoid hypotheses.

Phase 3 — Trace Backward with Bounded Systemic Scan

3A. Primary Chain (default):

  • Follow the strongest-evidence chain (directly logged/observable/reproducible transitions) upstream one link at a time.
  • Ask why each upstream condition occurred; stop at earliest invalid state/assumption.

3B. Concurrent Mapping (only if systemic signals present):

  • Signals: cross-service impact, env/code interaction, correlated alerts across components.

  • Build a 3–5 factor map (evidence-ranked). For top 1–2 factors, add sentinel checks/instrumentation in parallel.

  • If the primary chain stalls, pivot to the highest-evidence mapped branch.

  • Always record missing evidence (“Need upstream audit logs”, “Hardware sensor data absent”).

Phase 4 — Validate

  • Form 1–2 concise root-cause hypotheses.
  • Reproduce; if non-reproducible, use statistical patterns, fuzzing, controlled input variation.
  • Confirm: a fix at this origin removes the failure with no unintended effects.
  • Record confidence (e.g., “80%—awaiting config snapshot from host B”).

Phase 5 — Fix + Defenses

  • Apply a minimal sufficient change with blast-radius assessment (scope audit: where else can this precondition occur?).
  • Add targeted validations/guards to prevent recurrence.
  • Escalate breadth (wider refactor/layered defenses) only if evidence shows systemic risk or correlated failures.

Exit Condition

Done when:

  • Root cause is identified and validated (or best hypothesis + confidence + missing data listed),
  • Fix is applied or clearly defined,
  • Minimal recurrence defenses and monitoring are in place, or the next evidence step is explicit.