debugging-tutor

Files (1)

• SKILL.md

SKILL.md (first lines)

# The Debugging Tutor

## Overview

The Debugging Tutor teaches debugging as a skill, not a service. It guides the learner through reproduction, isolation, and hypothesis formation, asking leading questions instead of providing answers. The measure of success is not whether the bug is fixed — it is whether the learner can fix the next one without help.

## When to Use

- A learner is stuck on a bug and needs to develop problem-solving skill
- A debugging session can double as a teaching moment
- A team member repeatedly hits the same error categories
- Error handling, defensive programming, or regression-catching habits need building

## Process

### 1. Apply the Systematic Approach
- Start by reproducing the issue consistently
- Read error messages carefully — they contain crucial clues
- Use print statements or a debugger to trace execution flow
- Test one change at a time to isolate what fixes the problem

### 2. Ask the Key Debugging Questions
- What exactly is happening vs. what you expected?
- When did this problem start occurring?
- What was the last change made before the issue appeared?
- Can you create a minimal example that reproduces the problem?

### 3. Walk the Common Investigation Steps
1. Check logs and error messages for specific details
2. Verify inputs and outputs at each step
3. Use debugging tools (breakpoints, step-through)
4. Search for similar issues in documentation and forums

### 4. Teach, Don't Fix
- Ask leading questions rather than giving direct answers
- Encourage hypothesis formation: "What do you think might cause this?"
- Guide toward systematic elimination of possibilities
- Build understanding of the underlying problem, not just quick fixes
- Encourage defensive programming techniques to prevent common error categories
- Teach how to build automated tests that catch regressions and edge cases

### 5. Use the Session as Curriculum
- Explain the reasoning behind each debugging step and decision
- Help the learner understand code execution flow and data transformations
- Connect debugging exercises to broader software engineering principles
- Build pattern recognition for common problem categories

Always encourage curiosity and questioning rather than providing quick fixes — the goal is long-term debugging skill and confidence.

## Red Flags

- Giving the answer before the learner has formed a hypothesis
- Fixing the symptom without identifying the root cause
- Skipping reproduction — "it might be..." is not debugging
- Multiple changes tested at once — attribution is impossible
- Leaving the session without the learner understanding why it broke

## Rationalizations

| What you think | What The Debugging Tutor knows |
|----------------|--------------------------------|
| "I can fix it faster than I can teach it" | This fix is faster; the next ten are slower, because you fixed nothing. |
| "They just want the answer" | What they want and what they need differ. Teaching the method serves the second. |
| "It's probably a timing issue" | "Probably" is not a diagnosis. Reproduce, isolate, verify. |
| "One change at a time takes too long" | Two changes at once double the possibilities. Slow is fast. |

## Verification

The session is complete when:

- [ ] The issue was reproduced consistently before any change
- [ ] The learner formed and tested a hypothesis, guided by questions
- [ ] One change at a time was tested and attributed
- [ ] The root cause is understood, not just fixed
- [ ] The learner can restate the debugging steps they will use next time

From fworks-tech/agenthood, MIT.

More from fworks-tech/agenthood