Engineering practice · topic F5 · 25 hours
Debugging methodology
Robot failures are usually many causes, one symptom. With the wrong method you will spend two weeks fixing a problem that only «looks fixed».
What to learn
- Bisection localization: cut the chain in the middle to decide whether the problem is in the first half or the second
- Minimal reproduction: compress the problem to its shortest path
- Log levels and choosing where to place instrumentation
- The hypothesis–verification loop: change one variable at a time
The lesson · plain words
Debugging methodology is the most valuable and hardest-to-teach thing in engineering. This page gives three reusable patterns: bisection, minimal reproduction, and «suspect your own code first».
Bisection: finding the boundary is the fastest blade
Find the one commit out of 16 that introduced a bug: test the middle, go left if bad and right if good, and 4 tests pin it down. See the figure below. git bisect automates exactly this — you only supply a script that judges good or bad.
Bisection variants are everywhere: parameter bisection (start speed at 0.5× and double it rung by rung, find where it breaks), data bisection (which image category triggers the false detections), chain bisection (camera → network → algorithm, disconnect segment by segment). Any «fault inside a range» is this problem.
Interactive figure · drag it and see
Minimal reproduction: strip the environment to the bone
If you cannot reproduce it, you cannot fix it. A minimal reproduction = the smallest scenario where the bug still lives after stripping everything irrelevant: least code, simplest input, most stable environment. Writing the minimal reproduction is often the process of finding the answer.
Robotics-specific moves: fix the random seed + record sensor data and replay it (F4's replay testing) + shut down unrelated nodes. Most «happens occasionally» bugs become «happens always» through data replay.
Three counterintuitive principles
① Suspect your own code before the library/hardware (order by probability); ② change one variable, look at one result — changing two together makes the test worthless; ③ write logs at the «hypothesized boundary», not sprayed everywhere — logging is itself bisection.
One more discipline: after fixing, answer «why did nothing catch this earlier» — add a test (F4's replay) or a check. Otherwise the same bug comes back wearing new clothes.
How deep to go
You can demonstrate a full git bisect; convert an intermittent bug into «replay + minimal reproduction»; and restate the three principles to your team. Debugging skill is the scientific method made concrete for engineering — form a hypothesis, design the experiment, eliminate variables.
Three questions — do you really get it?
1. What is the principle behind git bisect?
- AExhaustive testing
- BBinary search for the commit that introduced the bug
- CRandom sampling
Show answer
B. Each test halves the candidates. 16 commits take 4 tests, 64 take 6.
2. What is the main tool for turning an «intermittent bug» into a «deterministic one»?
- AFix the seed + replay recorded data
- BRun it more times
- CReboot the machine
Show answer
A. Replay makes the inputs fully deterministic. Intermittency usually comes from timing or random inputs — replay eliminates both.
3. You changed two variables at once and the bug disappeared. What should you do?
- ACommit and ship it
- BRevert them one at a time to verify which one worked
- CAssume both were effective
Show answer
B. Not knowing which change worked means the next bug cannot be fixed back. The single-variable rule is the floor of debugging.
Keep going deeper
Links without a marker stay on this site; the rest point to the Chinese edition until its translation batch lands.
How it fails in the field
- Changing three parameters at once; the symptom disappears and nobody knows which change did it
- No record of the debugging process; the same problem comes around and gets debugged from scratch again
You have learned enough when
The Chinese edition carries the full topic page for Debugging methodology, including the complete outline, depth requirements per career track, and further derivations: robotguide.dev/k/F5/.