trace-fix

/trace-fix: Trace Before You Fix

Why this protocol exists

Guess-and-ship debugging is expensive: every wrong fix costs a build, a test pass, and often a release. Worse, a wrong fix can look right (timing shifts, one manual test passes) and ship with false confidence. Investigations that follow a structured trace tend to find the cause in minutes; investigations that skip it tend to take many cycles.

Do not write fix code until you have passed Gate 3.

The pattern that wastes cycles

Illustrative example (invented):

Attempt 1: "It hangs. I bet it's parsing." -> Fix parsing -> Ship
Attempt 2: "Still hangs sometimes. Maybe main-thread work?" -> Wrap in Task -> Ship
Attempt 3: "Worked in one manual test" -> Ship with false confidence
Attempt 4: "It's back." -> ...

In this kind of story the actual cause is usually something nobody measured: for example, a loop of a few hundred iterations each doing a small synchronous call on the main actor, which starves the run loop. Parsing was never the bottleneck, and Task { @MainActor in } does not yield to the UI by itself. Nobody checked either assumption.

The Gates

GATE 1: TRACE the execution path

Answer these with evidence (file:line references), not guesses:

1. What user action triggers the bug?
2. What is the FULL execution path from that action to where things go wrong?
3. At which specific point does behavior diverge from expected?

How to trace:

• Start at the user action (button tap, view appear, notification, timer).
• Follow every call. For each function: what does it do, what does it call next, what does it return?
• Write the chain: UserTaps -> ViewAction -> ViewModel.method -> Service.method -> ...
• For crashes: find the first frame in your own code and trace backwards to the triggering action.

CHECKPOINT: a written trace with file:line for each step. If you cannot trace the full path, investigate that gap rather than guessing.

Anti-pattern: "I added logs to see what's happening." You must READ the output and state what it told you. If the logs show nothing, that is information: the path is not being hit, which changes your hypothesis.