Jesse Vincent (obra) / systematic-debugging
What does systematic debugging give you that guessing does not?
A cause you can name, and a reason to believe the bug is actually gone.
What to remember
- The phases exist to stop the jump from symptom to patch.
- A named cause is what tells you whether the fix should work, before you deploy it.
- Intermittent bugs are where it earns the most, because guessing there is close to random.
- It costs time on simple bugs. Save it for the ones that already cost you a day.
01What it changes in practice
Guess and patch works often enough to be dangerous. The bug disappears, everyone moves on, and the defect resurfaces in a different shape when the workaround stops covering it.
Staging the work means the reasoning is written down while it is still cheap to challenge. When the stated cause does not explain every observation, that mismatch is visible instead of buried in a diff.
02Where it disappoints
Without a reproduction the process stalls at the first phase, which is honest but not always what a team under pressure wants to hear.
It also overlaps with the lighter diagnosing-bugs skill. Pick the one that matches how much ceremony your team will actually tolerate.
Install and first run
- Install superpowers from obra/superpowers, published under MIT.
- Provide a reliable reproduction, or accept that the first phase will be about finding one.
- Do not accept a fix until the cause has been stated and shown to explain the observed behaviour.
Questions people actually ask
- When is it worth the overhead?
- When a bug is intermittent, or when it has already survived one fix. On simple bugs it is slower than fixing them.
- What if there is no reproduction?
- The first phase becomes finding one. That is the correct order, even when it feels slower than trying a change.
- How does it compare with diagnosing-bugs?
- Same intent, more structure. Choose one so the agent gets a single set of instructions.
Sources
Machine readable versions of this page