Run a systematic debugging session from symptom to root cause
Guessing at fixes based on the symptom usually costs more time than isolating the actual cause first.
- Outcome
- A reproduced, isolated trigger, a root cause found through genuine hypothesis testing rather than guessing, and a verified fix backed by a regression test — instead of a patch aimed at the symptom that may or may not have actually addressed the cause.
- Time
- 30-90 minutes depending on how elusive the bug is
This workflow is part of PromptKit Pro
A handful of prompts and workflows stay free for everyone — Pro unlocks the full library, including this one, plus the guided runner.
Debugging a confusing issue by guessing at fixes based on the visible symptom often works eventually, but wastes real time on fixes aimed at the wrong layer — a patch that makes the symptom go away without addressing the actual cause tends to resurface later in a different form. This playbook runs the process in order: reproduce and isolate the trigger reliably, form and test real hypotheses about the cause rather than guessing at fixes, then verify the fix and lock in a regression test.
When not to use this
For an obvious, one-line bug with a clear cause visible from the error alone, this full process is unnecessary ceremony — just fix it. This is for something genuinely confusing enough that guessed fixes haven't worked.
Did this work?
The fix is verified against a reliable reproduction, backed by a regression test — not shipped on the hope that it addressed whatever was actually wrong.
Tested on claude-opus-5. Evidence status is draft; it moves to battle-tested only on recorded runs, never by hand.