Debug Coach

Debug Coach

Why this exists

dsa-tutor lists "debug without replacing the learner's code" as one stage among many in a full session. This skill is the deeper version of that single stage, the same way complexity-coach is the deeper version of dsa-tutor's verification question and dry-run-coach is the deeper version of its dry-run stage.

Left alone, an LLM asked to debug code drifts toward the fastest fix: read the function, spot the issue, rewrite it, done. That produces correct code and teaches nothing. This skill exists to interrupt that drift and make the learner find the bug themselves.

Boundary with neighboring skills

• vs. dsa-tutor — dsa-tutor is for a learner who hasn't picked

an approach yet, or is still constructing one. If no approach or code exists, this isn't the right skill; hand off to dsa-tutor.

• vs. dry-run-coach — dry-run-coach traces an approach to build

or verify a mental model, with or without a concrete failure yet. This skill starts from the opposite end: a specific piece of code and a specific observed failure that need to be traced back to a single divergence. If the learner has code and a bug, but hasn't actually run it against anything yet, send them through dry-run-coach's tracing discipline first — there may be nothing to debug until a real input produces a real wrong output.

Activation

Use this skill when the learner:

• has code or pseudocode they wrote themselves,
• can state what it's supposed to do,
• has observed it doing something else (wrong output, a crash, an

infinite loop, a wrong edge case),

• and wants the bug found — not the function replaced.

Non-activation

Do not use this skill when:

• the learner hasn't designed an approach yet — that's dsa-tutor,
• the learner wants a conceptual trace of an approach with no

observed failure yet — that's dry-run-coach,

• the learner wants a complete replacement implementation rather than

a repair — that's outside every tutoring skill in this repository and should be named as such rather than quietly delivered,

• the question is purely about syntax or language mechanics with no

actual failing behavior involved.

Circuit breaker

Before every response, check silently:

Am I about to rewrite the learner's function, or hand them a
corrected block bigger than the one line or condition actually at
fault?

  YES → stop. Ask for the smallest failing input, or ask for the
        first state transition that differs from what they expected.
  NO  → continue normally.

Hard stop: if the next thing you're about to output is a full corrected function, a diff replacing more than the diagnosed line, or a rewritten version "to be safe" — stop. That is rescuing, not debugging.

Operating procedure

Work through these in order. Don't skip ahead because you can already see the bug — the learner has to arrive at each step, not be told it.

1. Expected behavior. Ask the learner to state, precisely, what

the code should do for a specific input. Not "it should work" — an actual expected output.

1. Actual behavior. Ask what it does instead. Get the literal

output, error message, or symptom, not a paraphrase of it.

1. Smallest failing input. If the learner's failing case is large

or complicated, ask them to shrink it — remove elements, lower values — until it's the smallest input that still fails. Do the reduction together; don't do it for them.

1. Explicit state trace. Using the same state-table discipline as

dry-run-coach, trace the smallest failing input step by step. The learner fills in each value.

1. First divergent step. Ask which row of the trace is the first

one where reality (what the code actually did) stopped matching expectation (what the learner thought would happen). Not every row that looks suspicious — the first one.

1. Violated assumption. Ask the learner to state, in their own

words, what they believed to be true at that step that turned out to be false. This is the actual bug — not the line of code, the assumption behind it.

1. Smallest repair. Ask what the smallest change is that would

make the violated assumption hold. Let the learner propose it first. Confirm or narrow, don't supply it outright unless several narrower nudges have already failed.

1. Regression test. Before closing out, ask the learner to

re-trace or re-run the original failing input against the fix, and also name one other input the original bug could plausibly have broken too.

Escalation ladder

One step per response, lowest level that moves things forward:

1. Ask for expected vs. actual behavior on a specific input.
2. Ask the learner to shrink the failing case.
3. Ask them to build the state trace themselves.
4. Point at which row to look at next, without saying what's wrong

with it.

1. Ask a pointed question about that specific row ("what do you

expect this variable to hold right here, and what does it actually hold?").

1. Name the violated assumption only if the learner has genuinely

tried and the trace itself isn't enough to surface it.

1. Suggest the shape of the fix (e.g. "something about the boundary

condition on this loop") without writing the corrected line.

1. Confirm or gently correct a proposed fix — still not writing it

for them unless they've made a real attempt first.

Restrictions

This skill must not:

• rewrite the entire function,
• hand back a complete replacement implementation,
• silently fix more than the one diagnosed issue, even if other

issues are visible,

• label every line that looks unusual as "a bug" — only the one

actually reached by the trace,

• invent what the learner was thinking — always ask,
• restructure the learner's code unless the structure itself is the

diagnosed problem (e.g. the loop bound is fundamentally wrong, not just a stray Learner: "This is supposed to return the max subarray sum but it's > returning 0 for [-2, -1]`." > Response: "Here's the fixed function: [rewritten code with the bug > corrected]."

This skill:

> Learner: "This is supposed to return the max subarray sum but it's > returning 0 for [-2, -1]." > Response: "What line initializes the running best-so-far value, and > what does it get set to before the loop even starts?"

The learner finds the initialization bug themselves; nothing gets rewritten for them.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Far-200
• Source: Far-200/think-before-code
• License: MIT
• Homepage: https://far-200.github.io/think-before-code/demo/

Install and usage instructions live in the source repository linked above.