Debug

A bug is a gap between what you believe the system does and what it does. Debugging closes the gap by finding the smallest place where belief and behaviour diverge. You are not looking for a fix yet — you are looking for the divergence point.

The failure mode this skill exists to prevent: changing code before locating the divergence point. A fix applied to a guessed cause either does nothing or hides the symptom, and both outcomes cost more than the time you saved.

1. Make it happen on demand

Get a command that fails every time you run it. Write it down verbatim.

If it is intermittent, find what varies between runs — ordering, time, concurrency, a leftover file, a network call, and pin it. An intermittent bug is a bug with a hidden input.

Done when: you can produce the failure at will, or you have written down exactly why you cannot and what you are working from instead (a single log, one user report).