# The Debug Loop: 10 Prompts The recovery prompts for when agent coding goes sideways. Rule zero: stop prompting fixes, start prompting investigation. Each prompt is paste-ready. Fill the [SLOTS], paste, and do not let the agent skip the output format. Order matters. 1 through 4 are investigation, 5 and 6 force understanding, 7 through 10 are the fix and the insurance. If you are tempted to jump straight to prompt 7, you are about to make the bug worse. --- ## 1. Reproduce it deterministically Use first, always. A bug you cannot reproduce on demand is a bug you cannot verify is fixed. ``` We have a bug: [ONE-SENTENCE SYMPTOM, e.g. "checkout returns 500 for some users"]. Before touching any code, build me a deterministic reproduction: 1. Write the smallest possible script or test that triggers the bug on demand (a single command I can run, e.g. a test file or a curl call). Put it in [REPRO PATH, e.g. scripts/repro-checkout-500.sh]. 2. Run it and confirm it fails. Paste the exact failing output. 3. If you cannot reproduce it, do NOT guess at a fix. Instead list the top 3 pieces of information you would need to reproduce it (specific log lines, input values, environment details) and stop there. Constraints: - Do not modify any production code in this step. - The repro must not depend on manual clicking or timing luck. - If the bug is intermittent, run the repro [N, e.g. 20] times and report the failure rate as a number. Output format: (a) the repro file, (b) the command to run it, (c) the failing output, (d) failure rate if intermittent. ``` --- ## 2. Read before you write The single highest-leverage debugging prompt. Agents default to writing; force reading. ``` Do not write or edit any code in this session until I say "go". Read the code involved in [SYMPTOM] and give me a written trace: 1. Start at [ENTRY POINT, e.g. the POST /checkout handler] and follow the execution path to where the failure appears. List each file and function in order, with one line on what it does to the relevant data. 2. Quote the exact lines (with file paths and line numbers) where the failing value is created, transformed, and consumed. 3. Note anything surprising: dead code, duplicate logic, TODOs, error handling that swallows exceptions, values that change type along the way. Constraints: - Quotes must be real code you read, not reconstructions from memory. - If you hit a boundary you cannot read (external API, compiled dependency), say so explicitly instead of describing what it "probably" does. Output format: numbered trace, then a "surprises" list. No proposed fixes yet. ``` --- ## 3. Instrument the boundary When the trace is not enough and you need to see live values. ``` The failure in [SYMPTOM] involves data crossing from [SIDE A, e.g. the client form] to [SIDE B, e.g. the API handler / the DB layer / the third-party SDK]. Add temporary instrumentation at that boundary: 1. Log the exact value entering the boundary and the exact value leaving it, with a unique prefix [PREFIX, e.g. "DBG-LOOP:"] so we can grep for it. 2. Include types, lengths, and null/undefined states, not just the values. 3. Run the repro from earlier ([REPRO COMMAND]) and paste every DBG line. 4. State in one sentence where the value stops matching expectations. Constraints: - Instrumentation only. Do not "fix things while you are in there". - Never log secrets, tokens, or full user records; redact to shape and length. - All added lines must contain the prefix so removal later is one grep. Output format: diff of instrumentation, repro output, one-sentence conclusion. ``` --- ## 4. Binary search the timeline When it used to work and you do not know which change broke it. ``` This worked at [KNOWN-GOOD POINT, e.g. commit abc123 / yesterday's deploy / before we added feature X]. It fails now. Find the breaking change by bisecting, not by rereading the whole diff. 1. Confirm the repro ([REPRO COMMAND]) fails on the current state. 2. Use git bisect (or manual checkout of midpoint commits if bisect is not practical) between [KNOWN-GOOD REF] and HEAD, running the repro at each step. Log each commit tested and its pass/fail. 3. When you land on the first bad commit, show me: the commit hash, its message, its full diff, and the specific hunk you believe introduced the bug, with reasoning. Constraints: - Do not edit code during the bisect. Checkouts only. - If the repro cannot run on old commits (schema drift, missing env), say which commit range is untestable instead of guessing. - Return the working tree to its original state when done. Output format: bisect log table (commit, result), then first-bad-commit report. ``` --- ## 5. Explain it to me first The gate between investigation and fixing. No explanation, no fix. ``` Before proposing any fix for [SYMPTOM], explain the bug to me: 1. Root cause in 2 sentences maximum, in plain language. 2. The mechanism: the exact chain from cause to visible symptom, step by step, quoting the specific lines of code involved. 3. Why it presents the way it does: why [SPECIFIC WEIRDNESS, e.g. "only some users" / "only on the second click" / "only in prod"]. 4. Confidence: high / medium / low, and the one experiment that would move low or medium to high. Constraints: - If you cannot fill in point 3, your explanation is incomplete. Say "I cannot yet explain [WEIRDNESS]" and propose the next investigation step instead of a fix. - No code changes in this message. I will reply "go" if the explanation holds. Only then do you propose a fix. ``` --- ## 6. Three hypotheses ranked When the agent (or you) has tunnel vision on one theory. ``` For the bug [SYMPTOM], with the evidence so far ([PASTE KEY EVIDENCE: repro output, log lines, trace conclusions]), give me exactly three distinct hypotheses for the root cause. For each hypothesis: 1. The claim, one sentence. 2. What evidence supports it and what evidence contradicts it (be honest about the contradicting part). 3. A cheap discriminating test: the fastest check that would confirm or kill this hypothesis specifically. Estimate the time in minutes. 4. Probability estimate as a percentage. The three must sum to roughly 100. Constraints: - The hypotheses must be genuinely different mechanisms, not three flavors of the same theory. - Rank by probability, highest first. - Do not fix anything. After the table, run the cheapest discriminating test for the top hypothesis and report the result. Output format: table with columns Hypothesis / For / Against / Test / Minutes / Probability, then the test result. ``` --- ## 7. Minimal fix only Use only after prompts 5 or 6 produced a confirmed root cause. ``` Root cause is confirmed: [ONE-SENTENCE ROOT CAUSE]. Implement the minimal fix: 1. Change only what the root cause requires. Target: fewer than [N, e.g. 15] changed lines. If the true fix needs more, stop and tell me why before writing it. 2. No refactoring, no renaming, no "while I'm here" improvements, no new dependencies, no formatting changes outside touched lines. 3. Run the repro ([REPRO COMMAND]) and paste the passing output. 4. Run the existing test suite ([TEST COMMAND]) and paste the summary line. Constraints: - If the repro still fails, do not stack a second change on top. Revert your change, say the hypothesis was wrong, and go back to investigation. - One hypothesis, one change, one verification. Never two changes per run. Output format: the diff, repro output, test suite summary, and one sentence on why this change is sufficient. ``` --- ## 8. Prove it with a test The fix is not done until the bug cannot come back silently. ``` The fix for [SYMPTOM] is in. Now lock it down: 1. Convert the repro into a permanent automated test in [TEST PATH]. The test name should describe the bug, e.g. test_checkout_rejects_expired_coupon, not test_fix or test_bug. 2. Prove the test actually guards the bug: temporarily revert the fix (stash or comment it), run the test, show me it FAILS, then restore the fix and show me it PASSES. Paste both outputs. 3. Add a one-line comment above the test linking the context: "Regression test for [SHORT BUG DESCRIPTION], fixed [DATE]." Constraints: - The test must fail for the original reason, not for setup errors. - No sleeps or timing hacks; if the bug is timing-dependent, make the test control the clock or the ordering explicitly. Output format: the test file, the fail-then-pass proof, and the final test suite summary. ``` --- ## 9. What else does this touch The blast-radius check before you call it shipped. ``` We changed [FILES/FUNCTIONS CHANGED] to fix [SYMPTOM]. Before we ship, map the blast radius: 1. List every caller and consumer of the changed functions, modules, or schemas. Use actual search of the codebase (grep/references), not memory. 2. For each, state in one line whether the behavior change can affect it, and how: no effect / benign effect / needs verification. 3. For every "needs verification" item, run the relevant test or a quick manual check and report the result. 4. Check the non-code surface too: config files, environment variables, migrations, cron jobs, API consumers outside this repo, cached values that might hold the old behavior. Constraints: - "No callers found" must be backed by the search command you ran and its output, not asserted. Output format: table with columns Consumer / Effect / Verified how / Result, then a yes/no shipping verdict with one sentence of reasoning. ``` --- ## 10. Write the postmortem note Two minutes now saves you re-debugging the same class of bug next month. ``` Write a postmortem note for the bug we just fixed and append it to [NOTES PATH, e.g. docs/debug-log.md]. Keep it under 15 lines: - Date: [TODAY] - Symptom: what we saw, one line. - Root cause: the actual mechanism, two lines max. - Time sink: where the debugging time actually went, and what would have found it faster. - Fix: one line plus the commit/PR reference. - Regression test: file and test name. - Prevention: one concrete rule, check, or CLAUDE.md line that would stop this class of bug from happening again. If it belongs in CLAUDE.md or a lint rule, propose the exact text. Constraints: - Plain facts, no narrative. A future agent should be able to read this in 20 seconds and avoid the same hole. Output format: the appended note, plus the proposed prevention rule as a separate copy-ready block if there is one. ``` --- ## Quick reference | # | Prompt | Use when | |---|--------|----------| | 1 | Reproduce it deterministically | Always, first | | 2 | Read before you write | Before any code changes | | 3 | Instrument the boundary | Trace alone did not localize it | | 4 | Binary search the timeline | It worked before, unclear when it broke | | 5 | Explain it to me first | Gate before any fix | | 6 | Three hypotheses ranked | Tunnel vision, or explanation is shaky | | 7 | Minimal fix only | Root cause confirmed | | 8 | Prove it with a test | Right after the fix passes | | 9 | What else does this touch | Before shipping | | 10 | Write the postmortem note | Before you forget | Part of the Debug Loop resource. No warranty; adapt slots to your stack.