diagnose

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.