microclaw Debugging
Don't guess-and-patch. Find the root cause first, then make the smallest fix.
Method
- Reproduce reliably. Get the exact steps, inputs, and environment that trigger it. A bug you can't reproduce, you can't confirm you've fixed.
- Read the actual error. The stack trace usually names the file/line and the failing operation. Start there, not at your guess.
- Isolate. Shrink the problem: comment out halves, hardcode inputs, binary-search the
commit history (
git bisect) or the code path until the failing piece is tiny. - Form one hypothesis about the cause, and make a prediction you can check ("if it's a null here, logging X will show None").
- Test the hypothesis with a print/log/breakpoint or a minimal script — don't assume.
- Fix the cause, not the symptom. Then re-run the reproduction to confirm it's gone, and check you didn't break a neighbor.
- Add a regression test so it can't silently come back.
Fast checks before deep diving
- Did it ever work? What changed (code, data, deps, env, time)? Check
git diff/git log. - Off-by-one, null/empty/zero, wrong type, wrong variable, stale cache, wrong env var.
- For "works on my machine": compare versions, paths, env vars, and locale/timezone.
Useful instrumentation
# Narrow a flaky failure by running it many times
for i in $(seq 1 50); do <command> || { echo "failed on $i"; break; }; done
Guidance
- State the root cause in one sentence before proposing the fix.
- If you can't reproduce it, say so and ask for the missing input/logs rather than guessing.
- Keep the fix minimal and explain why it addresses the cause.