root-cause-tracing

Root-cause tracing guides you backward through the execution stack to identify where invalid data originated, not just where the error manifested. Start by observing the symptom, find the immediate cause, then systematically trace up through layers to locate the original trigger using instrumentation and stack-trace logging.

Apply backward tracing by inserting instrumentation like console.error() with stack traces at each layer. This reveals where parameters become invalid or empty—for example, tracking an empty projectDir parameter backward to the test setup that caused it—enabling fixes at the source rather than symptom masking.

Root-cause tracing includes a find-polluter.sh script that isolates which test introduces unwanted state or files. Run it to pinpoint the exact test setup causing side effects, then trace backward through that test's initialization to find where the incorrect behavior originates.

Fixing symptoms at the error site masks the root cause, leaving the underlying defect intact. Root-cause tracing enforces a defense-in-depth principle: trace backward to discover the original trigger—like a wrong file path or repository initialization—so the fix prevents the problem upstream.

Yes. Root-cause tracing handles cross-layer integration failures by applying backward tracing and instrumentation across repository, file-path, and initialization boundaries. It's designed for scenarios where bugs arise far from entry points with long, noisy call chains and unclear data origins.

When call chains are long and noisy, or data origins are unclear, add instrumentation with console.error() and stack traces to pinpoint which operation produced invalid data. This transforms an opaque stack trace into concrete evidence of where the problem started.