This is where you could stop. Instead they went up.

The call chain.

An empty string as a working directory raises no error - it resolves to the process's current directory. The one holding the source code.

The real cause. A top-level variable initialisation reading a value before that value existed.

The fix at the source. Access to the temporary directory was turned into a getter that throws when read too early. Not a check for an empty string in five places, but the removal of any way to read the value before its time.

Five levels of tracing, one fix at the source, one thousand eight hundred and forty-seven tests green and zero pollution.

Five steps backward

The process is short and repeatable on any stack.

Record the symptom - write down the concrete failure, not your reading of it. Find the immediate cause - which operation directly produces the unwanted effect. Ask what called it, and go one level up. Trace the values - which argument went wrong, and at what point. Find the original trigger - where correct state first stopped being correct.

The distance between the first step and the last is usually the distance between a green test and a fixed program.

When there is nowhere to trace

Here is an honest branch that retellings tend to drop.

The source's decision graph has a branch for "can you trace backwards". If you cannot - a dead end, a broken chain - it prescribes fixing at the symptom point. The technique does not demand heroism for the sake of principle.

Tracing becomes mandatory in other cases: the error appears deep rather than at the entry point; the stack shows a long chain; it is unclear where an invalid value originated; you need to find which test or code triggers the problem.

Conversely, if the error sits right at a boundary and the bad input is obvious, a multi-level investigation is overkill.

Giving yourself a stack trace

When the chain is not visible from the ordinary error message, the source suggests temporary instrumentation right before the dangerous operation:

Three rules are stated separately, and each of them was earned.

Log before the dangerous operation, not after it fails: afterwards, part of the state has already changed.

In tests use console.error, not the project logger: a test runner may well suppress the logger, and you will stare at empty output having concluded the code never reached that line.

Collect the output the simple way:

Then you look through the stacks for test file names, the line number that produced the call, and a repeating pattern: the same test, the same parameter.

What to put in the log

Who polluted the state

A separate class of problem: something appears "after the tests", but you do not know after which one. One test left a file, an environment variable, singleton state or a database row - and a different one fails.

The same skill directory holds a bisection script. It takes what to look for and a glob for the test files:

The script runs tests one by one and stops at the first one after which the thing appeared. The idea carries to any stack: run the candidates in isolation, check the invariant after each, stop at the first offender.

Four layers after the fix

Finding the source is half the work. The other half is in a neighbouring file of the same skill, and its principle is put like this: a single check means "we fixed the bug", a check at every layer means "we made the bug impossible".

The difference is not in the amount of code but in the fact that different layers catch different cases. Entry validation cuts off most bugs. Business logic catches the edge cases. An environment guard blocks what is dangerous in a particular context. A diagnostic log helps when the others did not fire.

In the case above, after fixing the source they added exactly four layers:

The third layer is particularly good: it does not validate data, it forbids a dangerous action in the context where it has no business happening.

And an important caveat that separates defence from a substitute for investigation. If by design a value cannot be empty, work out why it became empty rather than scattering if (!dir) through five files. Boundary checks are what you do after finding the source, not instead of it.

The three-attempt rule

Here is the thing most retellings of the technique leave out entirely, and it may be the most valuable part.

What do you do when a fix does not help? Count the attempts. Fewer than three - go back to phase one and re-analyse with the new information. Three or more - stop and question the architecture.

The signs are stated concretely: each fix uncovers new coupling or shared state somewhere else; the fix demands "massive refactoring"; each fix creates a symptom elsewhere.

At that point you are told to ask questions of a different order - is this pattern fundamentally sound, are we sticking with it through sheer inertia - and to discuss it with your human partner before attempting a fourth fix. It is stated plainly: this is not a failed hypothesis, this is the wrong architecture.

The rule is primitive in its simplicity, and that is exactly why it works. It puts a counter where stubbornness usually takes over.

Red flags

The skill carries a list of thoughts at which you should stop and go back to the start. It is written in the first person - these are the phrases you catch in your own head.

"Quick fix for now, investigate later." "Just try changing this and see if it works." "Add several changes, run the tests." "Skip the test, I will verify by hand." "It is probably X, let me fix that." "I do not fully understand but this might work." "One more attempt" - when there have already been two.

Listed separately are the signals from the person next to you that mean you are doing it wrong: "Is that not happening?" - you assumed without verifying. "Will it show us...?" - you should have gathered evidence. "Stop guessing." "Ultra-think this" - question the fundamentals, not the symptoms.

Excuses and what is behind them

The table of rationalisations in the skill is worth quoting almost in full.

And one line from the same place that is worth the whole table: ninety-five percent of "there is no root cause here" cases are incomplete investigation.

Why this is mainly about agents

A language model optimises what it can see, by construction. It saw an exception, it edited the function next to it. The test went green, so the task is done.

The technique puts a procedure in that path, forcing it to gather evidence and move up the dependency chain. The effect shows up in four ways.

Fewer accidental patches: the agent does not add a fallback merely because the test passes with it. A better explanation: what comes out is a causal chain, not a list of edited files. Lower regression risk: the fix lands closer to the place where the invariant broke. And verifiability - every step can be confirmed by a stack, a log, a test or a reproduction.

That last one is the real difference from "the model thought about it and decided". The chain can be re-checked.

Where one chain is not enough

Backward tracing assumes the causal link coincides with a synchronous call stack. In concurrent and distributed systems it does not.

For races, event-driven architectures and failures that live only in production you need other instruments: end-to-end request identifiers, distributed tracing, event timestamps, lock diagnostics, database transaction logs, sometimes a debugger or a profiler.

The "trace backwards" principle still holds - what changes is what carries the chain. In an event-driven system you reconstruct it through queue messages, callbacks, database rows and network requests.

Conclusion

Root Cause Tracing offers no new tool. It offers a prohibition: do not stop at the first plausible cause.

A good outcome of such an investigation fits into a single chain - symptom, immediate cause, the bad data or state, its origin, the fix at the source, the confirmation. If that chain has not been proved, the word "fixed" usually means "the test is green right now".

For a person this is a professional habit you either developed or did not. For an agent it is an external constraint that can be switched on - and one that visibly changes the quality of what it calls a fix.

Sources

The material was verified on 14 August 2026 against the Superpowers repository. The technique was studied from the primary source skills/systematic-debugging/root-cause-tracing.md rather than secondary catalogues; the examples, the call chain, the defence layers and the three-attempt rule are given as they are written in the skill. The repository is MIT licensed. Supplemented on 15 August 2026 against a fresh clone: the trace chain, the four defence layers, the three-attempt rule, the red flags, the partner's signals and the rationalisations table were checked line by line and held; the wording of one table row was corrected.

• GitHub - obra/superpowers
• root-cause-tracing.md - the technique itself
• systematic-debugging - four phases, the iron law, the three-attempt rule
• defense-in-depth.md - validation at every layer after the fix
• find-polluter.sh - bisection across tests