Use Debug Mode when the failure is reproducible but the cause is not obvious from static code. It is especially useful for timing issues, regressions, performance problems and bugs where normal Agent mode keeps guessing.
1. Write exact reproduction steps plus expected and actual behavior
Record the smallest reproducible sequence, environment and expected versus actual behavior. If the bug cannot be reproduced consistently, note the frequency and conditions instead of asking the agent to “fix what looks wrong.”
2. Switch to Debug Mode and let Cursor enumerate competing hypotheses before editing
Ask Debug Mode to enumerate competing hypotheses before editing. A useful list names the observable signal that would support or falsify each hypothesis, so instrumentation has a purpose.
3. Allow narrow instrumentation and reproduce the problem exactly as instructed
Allow only targeted temporary instrumentation at decision points relevant to those hypotheses. Avoid broad logging that changes timing, leaks sensitive values or makes the evidence harder to interpret.
4. Inspect the captured runtime evidence and identify the hypothesis actually supported
Reproduce the bug exactly and compare the captured runtime evidence against the hypothesis list. Prefer the explanation that accounts for all observed signals, not simply the first suspicious line of code.
5. Apply the smallest fix, reproduce again, then remove all temporary instrumentation
Apply the smallest fix, rerun the original reproduction and related regression tests, then remove every temporary log/probe. The final diff should contain the fix and tests, not the investigation scaffolding.
Use Debug Mode. Do not patch yet. Reproduction: [steps]. Expected: [expected]. Actual: [actual]. Generate 3–5 hypotheses, instrument only the minimum points needed to distinguish them, ask me to reproduce, then use the logs to choose the root cause before editing.
Jumping straight to a fix; adding logs everywhere; changing behavior while measuring it; not reproducing after the patch; leaving instrumentation in production code.
Finish check
The chosen fix is supported by runtime evidence, the original reproduction no longer fails, and all temporary logging or probes have been removed.