Debugging workflows
A repeatable loop for reproduction steps, hypotheses, instrumentation, patch notes, and final verification.
Takeaway
AI is most useful in debugging when it keeps the reproduction, hypothesis, evidence, and verification separated.
01
Write the reproduction first
Start with exact steps, input data, expected behavior, actual behavior, and the smallest command or route that reproduces the problem. The assistant can reason better when the failing path is concrete.
A reproduction is also a boundary. It keeps the investigation from expanding into unrelated cleanup before the actual failure is understood.
- Record the route, command, input, expected result, and actual result.
- Capture the smallest failing case before adding more logs.
- Keep screenshots or terminal output focused on the failure, not the whole session.
02
List competing hypotheses
Ask for two or three plausible causes and the fastest observation that would distinguish them. This prevents chasing the first confident explanation.
The value of AI here is structured breadth. It can suggest likely causes, but each hypothesis needs a concrete observation before it becomes the accepted explanation.
- Pair every hypothesis with a command, log, or code path to inspect.
- Prefer observations that eliminate multiple causes quickly.
- Update the hypothesis list when new evidence contradicts the first guess.
03
Close the loop
After the fix, record what changed, which hypothesis won, what commands passed, and which user flow was checked manually. That note improves the next debugging session.
The closing note should be factual and short. It is not a postmortem unless the issue had user impact, but it should still preserve the useful lesson.
- Link the fix back to the original reproduction.
- Run the focused check and the normal project verification path.
- Add a regression test when the failure mode is easy to recreate.