Bug investigation notes

Debugging goes wrong in a familiar way: you form a theory, start changing code, and two hours later cannot say which change did what or what you have already ruled out. Writing the investigation down as you go turns it into a small experiment: state a hypothesis, predict what you would see if it were true, run one test, record the result.

These notes keep observation, theory, and conclusion separate. They also end with the parts that stop the bug coming back: the root cause stated plainly, the fix, and a test that fails without the fix.

When to use it

• A developer is mid-hunt and pastes logs, stack traces, or rough notes, asking "what do we know so far?"
• A bug is intermittent or flaky and attempts need careful tracking.
• A production incident needs a technical write-up of cause and fix.
• They fixed something and want the reasoning recorded for the team.