debugging-before-fixes

Debugging before fixes

No fix without a root cause first. Patching symptoms burns review iterations and often adds a second bug. Guess-and-check thrashing is how tasks end blocked or review-exhausted under [[blocked-state]].

Step 1: build the feedback loop

Before investigating or fixing, stand up a fast, deterministic, agent-runnable loop that reproduces the failure on demand. Reach for the highest item on this list that actually reproduces the failure:

1. A failing unit, integration, or browser test.
2. The targeted command from the task record's Required Checks.
3. A curl or API smoke call against the dev stack.
4. A small CLI or script run against a checked-in fixture.
5. Replaying a captured payload, request, or log line through the failing code.
6. A throwaway harness in .agenticloop/tmp/ that calls the failing unit directly.
7. A fuzz or property loop when the triggering input is unknown.
8. git bisect or a differential loop when a previously passing behavior regressed.

Prefer the cheapest deterministic loop that still fails for the real reason. Capture the exact command: it becomes RED proof for [[tdd-implementation]] and evidence for [[verification-evidence]].

Phase 2: investigate

• Read the entire error message and stack trace.
• Run the Step 1 loop and watch the real failure.
• Diff what changed.
• Trace the bad value or state back to where it originates.

Phase 3: compare

Find code in this repo that does the same kind of thing and works. Read the reference fully, then list concrete differences between it and the broken path.

Phase 4: hypothesize and test

Calibrate effort to the failure:

• If the output fully explains a trivial error, fix it directly.
• If the failure is non-obvious, not fully explained, or already survived one fix attempt, write 3-5 ranked falsifiable hypotheses before changing code.

Put each hypothesis in this form:

If X is the cause, then observing or changing Y should produce Z.

Test hypotheses in rank order with the smallest observation or change that discriminates. Wrong hypotheses are reverted and recorded as ruled out.