Debug Decision Worksheet (Printable)

How to use this worksheet

Work top to bottom and do not skip the first block. The value of a bug report comes almost entirely from whether someone else can reproduce the failure, and reproduction depends on facts that are easy to leave out because they feel obvious while you are staring at the screen: the exact command, the exact versions, and the exact first error. Fill those in while the terminal is still open rather than reconstructing them from memory an hour later.

Why the first error line, not the last

Stack traces and build logs wrap the original failure in layers of context that were added while unwinding. The top-most error is usually the closest thing to the cause, while the bottom of the output is often a generic message emitted by whichever component gave up last. Copying only the last line is the single most common reason a report cannot be actioned, because it describes a symptom rather than the fault.

Reduce the case before you file it

A minimal reproduction is worth more than a long description. Remove code, config, and dependencies one at a time until the failure disappears, then add the last removed piece back. What remains is the smallest case that still fails, and in practice it frequently reveals the cause on its own before the report is even written.

Then write the go / no-go decision down

The second block exists to stop you from digging into a problem that should be triaged first. If the failure never worked on any machine, it is a setup or compatibility issue rather than a regression. If it reproduces on a clean checkout, the difference is in your environment or your uncommitted changes. Answering those two questions before you start reading source code saves the most time of anything on this page.