drvoss Diagnose
Diagnose is for problems that are still poorly shaped. Before deep debugging, build the smallest feedback loop that proves whether each change helps or hurts. A fast loop usually does more for bug finding than another round of guesswork.
When to Use
- The symptom is real, but the shortest reliable repro is still unclear
- A bug, regression, or performance issue needs a faster test loop before fixing
- Multiple causes seem plausible and you need to rank them instead of chasing all of them
- The system is large enough that targeted instrumentation beats broad logging
When NOT to Use
| Instead of diagnose | Use |
|---|---|
| You already have a stable repro and need root-cause discipline | systematic-debugging |
| The failure is a compiler, type, or dependency error | fix-build-errors |
| The issue is security-sensitive | security-scan or pr-security-review |
The 6-Step Loop
1. Build the feedback loop first
Create the fastest signal that tells you whether you are closer to the answer:
- a narrow failing test
- a single command that reproduces the symptom
- a benchmark or script with stable inputs
If a proposed fix does not improve that loop, it is too early to trust it.
2. Reproduce
Capture the exact symptom, input, and environment. Shrink it until it is cheap to rerun.
3. Rank 3-5 hypotheses
Do not hold one vague hunch in your head. Write a short ranked list:
- most likely
- plausible alternative
- annoying edge case
Then test them in order, demoting the ones the evidence weakens.
4. Instrument narrowly
Add only the probes needed to separate the top hypotheses. Prefer:
- one focused log or metric
- one temporary assertion
- one small trace around the suspect boundary
Avoid "log everything" unless you have no tighter cut.
5. Fix and add the regression check
Once one hypothesis is confirmed, make the smallest durable fix and lock it in with the same feedback loop that exposed it.
6. Clean up and record the root cause
Remove temporary probes and write down:
- what the real failure was
- which signal exposed it
- what regression check now protects it
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "I'll know the bug when I see it." | Without a loop, every change feels equally plausible. |
| "I need more logs everywhere." | Untargeted logs create noise faster than clarity. |
| "I only have one theory." | Rank multiple hypotheses so the next test actually rules something out. |
Red Flags
- The repro still depends on manual luck
- You are editing code before defining the loop that will prove the fix
- Logs keep growing, but no hypothesis gets ruled out
- You cannot explain why hypothesis #1 beats hypothesis #2
Verification
- The feedback loop is fast enough to run repeatedly
- 3-5 concrete hypotheses were ranked
- Instrumentation was targeted, not broad and permanent
- The final fix is covered by a regression check
See Also
systematic-debugging— deeper 4-phase root-cause workflow once the loop existsperformance-optimization— measurement-driven performance worktdd-workflow— turn the repro into a durable failing test