debug-mode

Debug Mode

Fix only a proven cause; a plausible fix that passes once proves nothing. Already inside a debug-mode run → continue the loop.

Respect the user's verb: diagnose ends before Fix and applies no fix; remove every temporary log before its report. debug, or a bug report with no verb, runs through Fix.

Workflow

1. Understand. Done when symptoms, affected surface, expected behavior, actual behavior, and a reproduction path are known.
2. Red loop. Build one command that drives the bug's code path and asserts its exact symptom: a failing test, a curl script, a CLI run on a fixture, a headless-browser script, a replayed trace. Make it tight: deterministic, fast, runnable unattended, asserting the symptom rather than "didn't crash". For a flaky bug, raise the reproduction rate (loop the trigger, add stress) until it is debuggable. For slow code, the loop is a baseline measurement (timing harness, profiler, query plan, production traces) that goes red above a stated threshold. When no command is practical (auth-walled, user-specific, production-only), say so and rely on instrumentation in steps 5-6. Done when the command has run red on this bug, or its absence is stated.
3. Minimize. With a loop, shrink the repro one cut at a time (inputs, callers, config, data, steps), rerunning the loop after each cut. Done when every remaining part matters: removing any one turns the loop green. Without a loop, go straight to step 4.
4. Hypothesize. Done when 2-3 ranked hypotheses each name the observation that would confirm or reject it.
5. Instrument. For slow code, profile the minimized repro or bisect between known-good and known-bad states (git bisect run with the loop). Otherwise add temporary logs. Done when the observations distinguish the hypotheses without leaking secrets or changing the behavior; if they change it, observe from a less invasive point.
6. Reproduce. Done when the bug has been triggered and the evidence collected, through the loop when one exists. If the flow is auth-walled or user-specific, ask the user to reproduce and wait.
7. Analyze. Done when evidence confirms one hypothesis or rejects every current one explicitly. When it rejects them all, write new hypotheses from the evidence and return to step 5.
8. Fix. When a seam exercises the real bug pattern, turn the minimized repro into a regression test first. Done when the smallest evidence-backed fix is applied, the loop (when one exists) has gone green on the original scenario, and every temporary log is removed.

Logs

• Write structured events through the app's own logger or a local file: hypothesis_id, event, a request or session id that ties one user action together, the observed values, and a timestamp.
• Tag every temporary log with one unique prefix (e.g. [DEBUG-a4f2]), so removal is a single grep.

Report Format

End with this shape:

## Symptoms
## Hypotheses Tested
## Evidence Collected
## Confirmed Root Cause
## Fix Applied
## Instrumentation Removed
## Residual Risk

If no fix was applied, say that under Fix Applied and name the missing evidence.