Diagnose Issue

Find the cause with evidence before changing behavior. Diagnosis is read-only unless the user explicitly asks to fix or implement.

Use research-ladder.md when external docs or tool behavior matter. Use repo Glossary and ADRs when present.

Process

Build the fastest useful feedback loop: focused test, build, CLI call, request, browser check, trace replay, benchmark, or small disposable harness.
Reproduce the reported symptom when feasible and capture the exact failure. For flaky behavior, record a baseline reproduction rate and raise it enough to compare changes. If reproduction is unavailable, distinguish conclusions from hypotheses and request only the missing evidence that matters.
Read full errors, logs, stack traces, recent diffs, dependency/config changes, environment differences, callers, and nearby working examples as relevant.
Keep ranked falsifiable hypotheses only while uncertainty remains. When direct evidence explains the cause, proceed to verification instead of manufacturing alternatives.
Instrument the boundary that separates plausible causes. Minimize a reproducible symptom by removing inputs, steps, config, or callers one at a time until only load-bearing elements remain. Trace bad values to their source, measure performance, and wait on real async conditions rather than arbitrary sleeps.
State the most supported cause and the evidence that rules in or out meaningful alternatives.