name	systematic-debugging
description	Use when a test fails, a build breaks, or runtime behavior is wrong and the cause is not immediately obvious — especially before changing code to "see if it helps".

Systematic debugging

A failing check is a question ("why did this happen?"), not a prompt to start editing. Guessing-and-checking edits the code before you understand it; it usually masks the symptom, leaves the real bug, and burns turns. Find the cause first, then make one targeted fix.

The loop

Reproduce. Run the exact failing command and read the FULL output and exit code — not a summary, not memory of a past run. If you can't reproduce it, you can't fix it; say so.
Isolate. Narrow to the smallest input/file/line that still fails. Read the full failing function and the code that calls it — the cause often sits outside the line the error points at.
Find the root cause. State, in one sentence, the actual mechanism: "X is null here because Y never set it." If you can't write that sentence, you don't understand it yet — keep reading, don't start editing.
Fix the cause, not the symptom. Make the smallest change that addresses the mechanism you named. Do not swallow the error, loosen the assertion, or special-case the one failing input to make it pass.
Verify. Re-run the exact command from step 1, fresh. Confirm it now passes AND that you didn't break a sibling — run the surrounding tests too.

Red flags — stop if you think any of these

The thought	The reality
"Let me just try this and see if it works."	You're editing before you understand. Reproduce and isolate first.
"I'll wrap it in try/catch / loosen the test."	That hides the bug, it doesn't fix it. Find why it throws.
"It only fails sometimes, probably flaky."	"Probably" is not a root cause. Isolate the condition that triggers it.
"The fix is obvious from the error message."	Confirm the mechanism by reading the code; error messages mislead.

When you're stuck

If two genuine attempts at the root cause fail, stop and say what you tried, what you ruled out, and what you'd need to get unblocked. An honest dead-end beats a symptom-masking patch that ships a latent bug.

Systematic debugging

The loop

Reproduce. Run the exact failing command and read the FULL output and exit code — not a summary, not memory of a past run. If you can't reproduce it, you can't fix it; say so.

Isolate. Narrow to the smallest input/file/line that still fails. Read the full failing function and the code that calls it — the cause often sits outside the line the error points at.

Find the root cause. State, in one sentence, the actual mechanism: "X is null here because Y never set it." If you can't write that sentence, you don't understand it yet — keep reading, don't start editing.

Fix the cause, not the symptom. Make the smallest change that addresses the mechanism you named. Do not swallow the error, loosen the assertion, or special-case the one failing input to make it pass.

Verify. Re-run the exact command from step 1, fresh. Confirm it now passes AND that you didn't break a sibling — run the surrounding tests too.

Red flags — stop if you think any of these

The thought

The reality

"Let me just try this and see if it works."

You're editing before you understand. Reproduce and isolate first.

"I'll wrap it in try/catch / loosen the test."

That hides the bug, it doesn't fix it. Find why it throws.

"It only fails sometimes, probably flaky."

"Probably" is not a root cause. Isolate the condition that triggers it.

"The fix is obvious from the error message."

Confirm the mechanism by reading the code; error messages mislead.

When you're stuck

systematic-debugging