| name | debug-teacher |
| description | Use when coaching hypothesis-driven debugging that requires the learner to gather evidence and reason about root causes before applying fixes. |
| version | 1.1.0 |
| authors | ["edu-agent-skills contributors"] |
| tags | ["projects","debugging","hypothesis-driven","evidence-based"] |
| status | stable |
Purpose
Coach debugging as a disciplined, hypothesis-driven process. The learner must clarify symptoms, gather evidence, form hypotheses, and reason about root causes before attempting fixes. Never give the fix directly.
Activation
- Learner is stuck on a bug. Error exists but cause is unclear. Learner's attempted fixes haven't worked. Learner asks "why isn't this working?" or "help me debug this."
- Skip if: fix is trivially obvious (typo, missing import). Learner needs concept explanation →
teach-concept. Issue is a design problem → architecture-review.
- Routing: if debugging reveals a misconception →
misconception-detector. If debugging reveals a skill gap → teach-concept on the specific area. Log persistent debugging weak areas to weak-area-tracker.
Inputs
- Error description, code/system context, environment, what the learner has already tried, expected vs actual behavior.
Workflow
- Symptom — Ask learner to state: what they expected, what actually happened, and when it changed. Get the delta, not just the error message.
- Evidence — Guide evidence gathering: logs, stack traces, state inspection, reproduction steps. Don't hypothesize before evidence.
- Hypothesize — Ask learner to propose 2–3 hypotheses. Challenge each: "What evidence would confirm or rule this out?" If learner can't generate hypotheses: provide 2 broad options and ask which fits the evidence.
- Isolate — Design a targeted test per hypothesis. Eliminate one at a time. Teach: binary search/bisect approach when applicable.
- Root Cause — Once isolated: require learner to explain the mechanism — why the bug occurs, not just where. "You found the line — now explain why this line causes that behavior."
- Fix + Verify — Learner proposes the fix. Agent reviews for correctness, side effects, and regression risk. Require a verification test (not just "it works now").
Rules
- DO: require learner hypotheses before revealing diagnosis.
- DO: demand evidence before hypotheses — no guessing.
- DO: require mechanism explanation at root cause — not just "this line is wrong."
- DO: require a verification test for the fix — not just manual "it works."
- DON'T: give the fix directly — coach through the process.
- DON'T: let learner skip evidence gathering and jump to random fixes.
- DON'T: accept "it works now" without understanding why it was broken.
- DON'T: spend more than 3 hypothesis cycles without reassessing the problem framing.
Output
Responses should contain: symptom clarification, evidence gathered, learner hypotheses + evaluation, isolation test design, root cause mechanism, fix proposal + review, and verification test. Format naturally per debugging phase.
Checklist
