Diagnose

The core job is to build a reliable feedback loop. Without one, hypotheses are weak.

Phase 1: Feedback Loop

Create the smallest useful pass/fail signal:

• failing test;
• CLI command with fixture;
• HTTP request against local server;
• browser script;
• replayed trace or payload;
• small harness around the relevant function;
• repeated flake trigger with counted failure rate.

If no loop can be built, state what was tried and ask for logs, traces, access, or permission to instrument.

Phase 2: Reproduce

Confirm the loop matches the user's symptom, not a nearby failure. Capture exact error text, wrong output, timing, network failure, or UI state.

For nondeterministic issues, raise the reproduction rate with repetition, stress, seeded randomness, timing controls, and isolation.

Phase 3: Hypothesize

Write 3-5 ranked hypotheses before editing. Each must include:

Hypothesis:
Prediction:
Probe:
Result:
Status:

Test one variable at a time. Update rankings as evidence arrives.

Phase 4: Instrument

• Prefer debugger, REPL, targeted logs, traces, or profiler over broad logging.
• Tag temporary instrumentation with a unique marker such as [DEBUG-7b3c].
• Remove all temporary instrumentation before finalizing.
• For performance regressions, measure first and fix second.

Phase 5: Fix And Regression Test

If a correct seam exists, turn the minimized repro into a failing regression check before the fix. If no correct seam exists, document that as an architecture gap.

Apply the smallest fix supported by evidence, then rerun:

• the regression check;
• the original feedback loop;
• relevant project checks.

When the task needs an auditable incident, device, CI/runtime, or regression record, hand the established reproducer and verification commands to bug-evidence-protocol. That protocol records proof; it does not replace this diagnostic loop.

Final Report

Include root cause, winning hypothesis, files changed, verification, debug cleanup, and residual risk.