debug-loop

name

debug-loop

description

Use when debugging any bug, test failure, crash, or unexpected behavior WITH an AI coding agent — before letting it propose or apply a fix. Stack-agnostic. This skill is about steering the agent through a disciplined loop: forcing it to reproduce and locate before fixing, to show evidence instead of conclusions, and to change one thing at a time. Trigger it whenever the agent starts guessing, proposes a fix without a repro, or claims something is "fixed" without proof.

Debug Loop

A short, opinionated debugging discipline for a human directing an AI agent. Most agent debugging fails the same way: the agent reads a symptom, guesses a cause, and patches. This skill exists to stop that — and, unlike a solo-dev checklist, it names the moves you make to keep the agent honest.

Two roles

• You are the director. You set the gate, demand evidence, and decide when to stop.
• The agent is the investigator. It gathers facts and proposes exactly one change at a time. It does not decide the fix is "done" — you do.

The one rule

NO FIX UNTIL THE BUG IS REPRODUCED AND LOCATED.

If the agent proposes a fix and you cannot yet point to the line/boundary where the bad value appears, the investigation is not finished. Send it back.

The loop

Run these in order. Do not let the agent skip ahead.

1. Reproduce. A concrete, repeatable trigger. If it's flaky, that is the first thing to investigate — don't debug what you can't reproduce.
2. Locate. Follow the bad value backward to its source, not its symptom. In multi-component systems (service → queue → adapter → DB), add logging at each boundary and run once to see which hop breaks before touching code.
3. Hypothesize. One sentence: "I think X because Y." One hypothesis at a time.
4. Change one thing. The smallest edit that tests that hypothesis. No "while I'm here" refactors, no bundled improvements.
5. Verify with real output. The agent runs the actual command and pastes the actual result. "Should work" is not verification.

If step 5 fails → back to step 3 with what you just learned. Not a new patch on top of the last one.

Steering the agent (the part that's actually the skill)

Keep these phrases in reach. They're the difference between 20 minutes and an afternoon of thrashing.

• Demand evidence, not conclusions. → "Show me the actual value at that point. Don't tell me what you think it is."
• Force a single hypothesis. → "State one hypothesis and the smallest change that tests it. Nothing else."
• Block the bundled fix. → "You changed three things. Revert to one. We isolate before we combine."
• Interrupt the guessing spiral. After two failed guesses: → "Stop. Re-read the error message line by line and trace the data flow before proposing anything."
• License ignorance. Agents invent to fill gaps. → "If you don't know, say 'I don't know' and tell me what you'd inspect next."
• Require proof of the fix. → "Run it and paste the output. Then run the rest of the tests and paste that too."

Red flags — STOP and reset the loop

Agent behaviours that mean you intervene now:

• Proposes a fix before there's a repro.
• "This is probably X, let me change it."
• Edits several files/things in one go.
• Explains what it would see instead of showing what it did see.
• Says "fixed" / "should be working now" without pasted output.
• Each fix moves the error somewhere new.

When to escalate to a human

After 3 failed fixes, the problem is usually the architecture, not the bug. Signs: every fix uncovers new coupling, or fixes need "a big refactor" to land. Stop patching. Get a human decision on whether the design is sound before the agent touches it again. This is not a failed hypothesis — it's a wrong shape.

Why this over "just let it debug"

• Isolating one change keeps the fix real and the diff reviewable — critical on client code you'll hand off.
• Evidence-at-boundaries beats staring at the top-level stack trace in any distributed or integration-heavy system.
• The verify-with-real-output rule is what actually stops the "it's fixed" hallucination.