> For the complete documentation index, see [llms.txt](https://um.fz.ax/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://um.fz.ax/dev/debugging.md).

# debugging

**UNDERSTAND THE SYSTEM**

* read the manual
* read everything in depths
* know the fundamentals
* know the road map
* understand your tools
* look up the details

**MAKE IT FAIL**

* do it again
* start at the beginning
* stimulate the failure
* but don't stimulate the failure
* find the uncontrolled condition that makes it intermittent
* record everything and find the signature of intermittent bugs
* don't trust statistics too much
* know that "that" can happen
* never throw away a debugging tool

**QUIT THINKING AND LOOK**

* see the failure
* see the details
* build instrumentation in
* add instrumentation on
* don't be afraid to dive in
* watch out for heisenburg
* guess only to focus the search

**DIVIDE AND CONQUER**

* narrow the search with successive approximation
* get the range
* determine which side of the bug you are on
* use easy-to-spot test patterns
* start with the bad
* fix the bugs you know about
* fix the noise first

**CHANGE ONE THING AT A TIME**

* isolate the key factor
* grab the brass bar with both hands
* change one test at a time
* compare it with a good one
* determine what you changed since the last time it worked

**KEEP AN AUDIT TRAIL**

* write down what you did, in what order, and what happened as a result
* understand any detail could be the important one
* correlate events
* understand audit trails for design are also good for testing
* write it down

**CHECK THE PLUG**

* question your assumptions
* start at the beginning
* test the tool

**GET A FRESH VIEW**

* ask for fresh insights
* tap expertise
* listen to the voice of experience
* know that help is all around you
* don't be proud
* report symptoms, not theories
* realize that you don't have to be sure

**IF YOU DIDN'T FIX IT, IT AIN'T FIXED**

* check that it's really fixed
* check that it's really your fix that fixed it
* know that it never just goes away by itself
* fix the cause
* fix the process