Diagnose
Use a feedback-loop-first debugging discipline. Do not guess from code inspection alone when a reproducible signal can be built.
Core rule
Build a fast, deterministic, agent-runnable pass/fail loop before fixing. If no loop can be built, say what was tried and ask for the missing artifact or access.
Process
1. Build the feedback loop
Try the narrowest reliable signal that reproduces the reported symptom:
- failing test at the seam that reaches the bug
- CLI command with fixture input and expected output
- HTTP request or curl script against a local server
- browser script for UI behavior
- captured trace, log, payload, or replay fixture
- throwaway harness around the smallest runnable subsystem
- repeated or fuzz loop for intermittent failures
- differential check between old/new versions or configs
Sharpen the loop until it is specific, repeatable, and as fast as practical. Assert the reported symptom, not merely "does not crash".
Do not move on until the loop fails in the expected way. For nondeterministic bugs, increase reproduction rate enough to debug against.
2. Reproduce and pin the symptom
Run the loop and confirm:
- it matches the user's reported failure, not a nearby failure
- it reproduces reliably enough for diagnosis
- the exact symptom is captured: error text, wrong output, timing, state, DOM, response, or logs
Wrong symptom means wrong fix.
3. Rank falsifiable hypotheses
Before changing code, write the smallest useful ranked set of falsifiable hypotheses. Each hypothesis must include a prediction:
If <cause> is true, then <probe/change> will show <observable result>.
Discard vague hypotheses. If useful, show the ranked list to the user before probing; proceed with the best current ranking if the user is not available.
4. Probe one variable at a time
Map each probe to one hypothesis. Prefer:
- debugger or REPL inspection when available
- targeted logs at decision boundaries
- narrow assertions in the repro loop
Never spray logs broadly. Tag temporary diagnostics with a unique prefix like [DEBUG-a4f2] so cleanup is mechanical.
For performance bugs, measure first: establish a baseline timing/profile/query plan, then compare one change at a time.
5. Fix with a regression check
If a correct test seam exists:
- turn the minimized repro into a failing regression test
- watch it fail for the right reason
- apply the smallest fix
- watch the regression test pass
- rerun the original feedback loop
If no correct seam exists, state that explicitly. Avoid adding a shallow test that cannot fail for the real bug pattern.
6. Cleanup and report
Before declaring done:
- rerun the original repro loop and confirm it no longer fails
- run the regression check, or document why no correct seam exists
- remove
[DEBUG-...]instrumentation - delete throwaway harnesses or move them only if they are intentionally retained
- report the winning hypothesis and the evidence that proved it
If the diagnosis reveals architectural friction, such as no test seam or tangled callers, recommend a follow-up after the fix is verified.