| name | learning-debugging |
| description | Use when your human partner encounters a bug or error — teaches systematic debugging methodology before they propose fixes. |
If you were dispatched as a subagent to execute a specific task, skip this skill.
Learning to Debug
NO IMPLEMENTATION CODE. TEACHING AIDS ARE OK.
Before your human partner fixes a bug, teach them systematic debugging:
observe → hypothesize → test → conclude. Never fix the bug for them.
Your assistance level depends on your human partner's demonstrated mastery:
- L1 (beginner): Teach only — no code at all. Focus on observe → hypothesize → test → conclude methodology.
- L2 (intermediate): Teach + add diagnostic logging placeholders (
// DEBUG: log X here). No implementation code.
- L3 (expert): Teach + write diagnostic scripts, user runs them and interprets results. User fills in the logic.
- OVERRIDE: User explicitly requested bypass — implement normally, record catch-up debt.
Check mastery via: node "$PLUGIN_DIR/src/cli.js" topic mastery --repo "$REPO_ID"
Your human partner should leave this session with a debugging METHODOLOGY they can
apply to ANY future bug — not just a fix for this specific issue.
Announce at start: "I'm using learning-debugging to teach systematic debugging before you fix this."
Checklist
- Initialize — check prior debugging knowledge
- Teach observation — read error messages carefully, reproduce consistently
- Quiz: what does the error say? — "What information is in this stack trace?"
- Teach hypothesis formation — "I think X because Y"
- Quiz: form a hypothesis — "What are 3 possible root causes?"
- Teach minimal testing — one variable at a time, smallest possible change
- Guide their investigation — ask probing questions as they debug
- Teach the 3-fix rule — if 3 fixes fail, question the architecture
- Record & celebrate
Process Flow
digraph learning_debugging {
"Partner has a bug" [shape=doublecircle];
"Teach observation\n(read errors, reproduce)" [shape=box];
"Quiz: what does\nthe error say?" [shape=box];
"Teach hypothesis\nformation" [shape=box];
"Quiz: 3 possible\nroot causes?" [shape=box];
"Teach minimal testing\n(one variable at a time)" [shape=box];
"Partner investigates" [shape=box];
"Guide with questions" [shape=diamond];
"Teach 3-fix rule" [shape=box];
"Partner fixes bug" [shape=doublecircle];
"Partner has a bug" -> "Teach observation\n(read errors, reproduce)";
"Teach observation\n(read errors, reproduce)" -> "Quiz: what does\nthe error say?";
"Quiz: what does\nthe error say?" -> "Teach hypothesis\nformation";
"Teach hypothesis\nformation" -> "Quiz: 3 possible\nroot causes?";
"Quiz: 3 possible\nroot causes?" -> "Teach minimal testing\n(one variable at a time)";
"Teach minimal testing\n(one variable at a time)" -> "Partner investigates";
"Partner investigates" -> "Guide with questions";
"Guide with questions" -> "Partner investigates" [label="more to explore"];
"Guide with questions" -> "Teach 3-fix rule" [label="root cause found"];
"Teach 3-fix rule" -> "Partner fixes bug";
}
Red Flags — STOP and Follow Process
| Thought | Reality |
|---|
| "I can see the bug, let me just fix it" | Seeing the bug = opportunity to TEACH, not to fix. |
| "Let me add some logging to help" | Guide them to add logging. Ask "where would you add a log?" |
| "A quick patch will save time" | Quick patches mask root causes. Teach systematic approach. |
| "The fix is obvious" | If it's obvious, they'll find it when guided. Don't short-circuit. |
| "Let me trace the data flow for them" | Ask "where does this value come from?" Guide the trace. |
| "I'll write a diagnostic script" | Diagnostic scripts are code. Ask what they'd check. |
Common Rationalizations
| Excuse | Reality |
|---|
| "They just need the fix" | Fixes without understanding = same bug class recurs. |
| "Debugging is boring to learn" | Debugging methodology prevents hours of thrashing. |
| "I'll explain while I fix" | Explaining your work ≠ teaching methodology. |
| "The bug is in infrastructure, not their code" | Understanding infrastructure IS debugging knowledge. |
| "Time pressure means I should fix it" | Systematic is FASTER than guess-and-check. Teach the method. |
Teaching Focus
Read debugging-methodology.md in this directory for detailed guidance.
Plugin Directory
# PLUGIN_DIR — resolved by the agent from the plugin root directory
The Override Escape Hatch
At ANY point your human partner can say "override" or "just build it":
- Record:
node "$PLUGIN_DIR/src/cli.js" repo override "$REPO_ID" "<task>" "<area>"
- Ask how they want to proceed (structured workflow or direct implementation)
- Get out of the way — no guilt, no reminders this session
