The Debug Loop

NOTE

Use this page as a prompt reference. Every file below is built to be handed straight to an AI. Download it, drop it into Claude, ChatGPT, Cursor, or Lovable, and say "use this as my playbook." The prompts on this page are copy-paste ready.

WATCH OUT

The one rule that breaks the spiral: stop prompting for fixes, start prompting for investigation. "Fix this error" invites a guess. "Trace this value from the form to the database and show me where it changes" produces evidence. Agents are genuinely good at investigation. They read code fast, they grep everything, they don't get bored. You just have to ask for that instead of a fix.

NOTE

You won't need all 7 steps for every bug. A typo-class bug is reproduce, fix, regression-proof, done in 10 minutes. The full loop is for the bugs that survived your first two attempts. The moment a bug survives two fix attempts, drop into the full loop. That's the trigger.

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.

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.

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.

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.

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.

NOTE

Point 3 is the lie detector. A pattern-matched guess can produce a plausible root cause, but it usually can't explain the weird specifics ("why only on the second click?"). If the explanation doesn't cover the weirdness, the explanation is wrong, and you just saved yourself a bad fix round.

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.

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.

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.

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.

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.

PAYOFF

The postmortem note compounds. After a couple months you have a debug-log.md the agent can read at the start of any debugging session, and it stops re-making your project's signature mistakes. It's the cheapest 15 lines you'll write all week.

## Debugging rules

When we are debugging (a test fails, an error appears, behavior is wrong),
switch from building mode to investigation mode. These rules override your
defaults until the bug is fixed and regression-tested.

### Investigation before code

- Prefer READING code to WRITING code. Before proposing any change, trace
  the execution path and quote the specific lines involved (file + line).
- Never propose a fix until you can state the root cause in two sentences
  AND explain why the bug presents exactly the way it does (why these
  inputs, why intermittent, why only in this environment). If you cannot,
  say what information is missing and how to get it.
- If you cannot reproduce the bug with a command or test, your first task
  is building that reproduction, not fixing anything.

### One hypothesis at a time

- State your current hypothesis explicitly before each change.
- One hypothesis, one change, one verification run. Never stack a second
  change on top of an unverified first change.
- If a change does not fix the repro, REVERT it before trying the next
  hypothesis. Do not leave failed-fix debris in the working tree.
- After 3 failed hypotheses, stop proposing fixes. Summarize what has been
  ruled out and recommend either instrumentation, a git bisect, or reverting
  to the last known-good state.

### Honest verification

- Never claim something is fixed without running the reproduction and
  showing the passing output in the same message. "This should fix it"
  is banned vocabulary; run it.
- Never weaken, skip, delete, or mark-as-expected-failure a test to make
  the suite pass. If you believe a test itself is wrong, stop and say so;
  the human decides.
- Do not silence errors (empty catch blocks, broad exception handlers,
  ignoring return codes, @ts-ignore, eslint-disable) as a fix. Silencing
  a symptom is not fixing a bug.
- When the fix works, immediately convert the reproduction into a permanent
  regression test, and prove it: show the test failing with the fix
  reverted and passing with the fix applied.

### Minimal footprint

- Fixes change the fewest lines that the root cause requires. No
  refactoring, renaming, dependency bumps, or formatting churn inside a
  bugfix. Propose cleanups separately, after the fix ships.
- Temporary debug logging must carry a "DBG:" prefix and must be removed
  before the fix is final. Grep for the prefix to confirm.
- Never log secrets or full user records while instrumenting; redact to
  shape and length.

### Escalation honesty

- If evidence points outside the code you can see (third-party outage,
  data corruption, infra config), say so directly instead of changing
  application code to route around a mystery.
- If we have been debugging one bug for a long stretch with rising diff
  size and no confirmed root cause, recommend `git stash` or reset to the
  last known-good commit and a fresh start with a better reproduction.
  Recommending a reset is a valid and welcome answer.

WATCH OUT

Standing instructions are strong defaults, not guarantees. Agents still drift, especially deep into a long session when early instructions carry less weight. When you see the drift (a "this should fix it" without a run, a second change stacked on the first), don't argue, just paste the relevant prompt from the set above. The prompts are the enforcement layer.

NOTE

The stash trick in the yellow zone is criminally underused. git stash costs 5 seconds and answers the scariest question directly: is the original bug still there, or are you now debugging your own fixes? About half the time I run it in a messy session, the clean tree passes.

PAYOFF

A reset is not starting over. You keep the repro script, the trace, the ruled-out hypotheses, and the postmortem notes. Attempt two with that package usually lands in a fraction of the time attempt one burned. Commit working states often (every green moment) and "known-good" is never far away.

PAYOFF

The 60-second install: paste the recovery block into CLAUDE.md, drop debug-prompts.md into docs/, commit. Next time a bug survives two fix attempts, you run the loop instead of the spiral. That swap is worth hours the first week you use it.

Get the next drop

Every new Vault system ships to the list first. Twice a week, free.