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:

1. most likely
2. plausible alternative
3. 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 exists
• performance-optimization — measurement-driven performance work
• tdd-workflow — turn the repro into a durable failing test