root-cause-tracing

Trace bugs backward through the call stack to identify the original trigger.

Updated Oct 22, 2025
One-click install
npx skills add https://github.com/franroa/chezmoi --skill root-cause-tracing-franroa
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: root-cause-tracing
Source: https://github.com/franroa/chezmoi/tree/main/dot_opencode/superpowers/skills/root-cause-tracing
Command: npx skills add https://github.com/franroa/chezmoi --skill root-cause-tracing-franroa

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

This Skill prevents you from wasting time fixing symptoms by guiding you to systematically trace bugs backward through the call stack to find their original trigger. It ensures fixes are applied at the source, making bugs structurally impossible.

Core Features & Use Cases

  • Backward Tracing Process: Guides you from the symptom, up the call chain, to the original trigger of invalid data or incorrect behavior.
  • Instrumentation for Deep Errors: Provides techniques for adding diagnostic logging and stack traces when manual tracing is difficult.
  • Polluter Identification: References a bisection script (find-polluter.sh) to pinpoint which test or code introduces unwanted state.
  • Use Case: When an error occurs deep in the execution stack (e.g., git init failing in the wrong directory), use this Skill to trace back and find why the wrong directory was passed, rather than just adding a check at the git init call.

Quick Start

Announce skill usage

I'm using the root-cause-tracing skill to find the source of this error.

The skill will then guide you through observing the symptom and tracing backward.

Frequently Asked Questions about root-cause-tracing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I trace a bug back to its root cause through the call stack?

Root-cause tracing guides you backward from the error symptom through the call chain to find the original trigger. Instead of fixing the error where it appears, you identify where invalid data or incorrect behavior originated, making the fix structural and permanent.

When should I use backward tracing instead of adding defensive checks at the error point?

Use backward tracing when errors occur deep in execution across long call stacks, especially in tests where data corruption's origin is unclear. Tracing to the source prevents the same bug from surfacing elsewhere, whereas defensive checks only mask symptoms.

How do I instrument code with logging and stack traces to trace hard-to-follow errors?

Add diagnostic logging at key decision points and capture full stack traces when errors occur. This instrumentation creates breadcrumbs through the execution path, revealing where state changed unexpectedly and narrowing the search space for the original trigger.

What's the best way to identify which test or code change introduced unwanted state?

Use bisection techniques to systematically narrow which test or code pollutes the state. The Skill references a polluter-finding script that isolates the exact source, letting you fix the root cause rather than working around side effects.

Can I use root-cause tracing to fix bugs that appear inconsistently across different execution paths?

Yes. By tracing backward through the call stack, you map how different execution paths converge at the error point, revealing which path introduced the invalid state. This uncovers the common origin even when symptoms vary.