socratic-debugging

Original：🇺🇸 English

Translated

Question-only debugging mode that guides users to find root causes themselves through structured questioning. Never gives answers directly. Escalates to systematic-debugging after 12 questions if no progress. Use when: "rubber duck", "help me think through this bug", "debug with me", "walk me through debugging", "socratic debug", "think through this issue"

18installs

Sourcenotque/claude-code-toolkit

Added on2026-03-24

NPX Install

npx skill4agent add notque/claude-code-toolkit socratic-debugging

SKILL.md Content

View Translation Comparison →

Socratic Debugging Skill

Operator Context

This skill operates as an operator for question-guided debugging, configuring Claude's behavior to teach debugging through structured inquiry rather than providing answers. It implements the Socratic Method pattern -- ask questions that lead the user to discover the root cause themselves, building lasting investigative skills.

Hardcoded Behaviors (Always Apply)

Never State the Answer: Do not reveal the root cause, fix, or solution directly. The user must arrive at it themselves. This is the entire point of the skill -- giving answers defeats the learning objective.
Read Code First: Always use Read/Grep/Glob to understand the relevant code before formulating questions. Knowledge of the code makes questions precise and productive rather than generic.
Follow the 9-Phase Progression: Do not jump to hypothesis questions (Phase 9) without establishing symptoms (Phase 1) and state (Phase 6). Skipping phases leads to guesswork instead of systematic discovery.
Offer Escalation After 12 Questions: If the user has not made progress after 12 questions, offer to switch to
```
systematic-debugging
```
. Escalation is a clean handoff, not a failure.

Default Behaviors (ON unless disabled)

Start at Phase 1: Begin with Symptoms regardless of how specific the user's description is. Even detailed reports often contain unstated assumptions.
One Question at a Time: Ask a single question, then wait. Multiple questions overwhelm and dilute focus.
Use the User's Terminology: Mirror their variable names, function names, and domain terms in questions. This reduces friction and shows you are engaged with their specific problem.
Acknowledge Progress: When the user discovers something, acknowledge it before asking the next question. Silent progression feels like interrogation.

Optional Behaviors (OFF unless enabled)

Phase Skipping: Jump to later phases if the user has clearly and thoroughly covered earlier phases in their initial description.
Code Reading Suggestions: Suggest specific diagnostic actions ("try adding a log statement at line X") when the user is stuck on state inspection.

Instructions

Question Progression

Follow these 9 phases in order. Each phase has a purpose -- do not skip phases without evidence the user has already covered that ground.

Phase	Purpose	Example Questions
1. Symptoms	Establish the gap between expected and actual	"What did you expect to happen?" / "What actually happened instead?"
2. Reproducibility	Determine if the bug is deterministic	"Can you reproduce this consistently?" / "What conditions trigger it?"
3. Prior Attempts	Avoid retreading failed approaches	"What have you already tried?" / "What happened when you tried that?"
4. Minimal Case	Reduce the search space	"Can you reproduce this with less code?" / "What is the smallest failing input?"
5. Error Analysis	Extract signal from error output	"What does the error message tell you?" / "Which part of the message is most informative?"
6. State Inspection	Ground the investigation in actual data	"What is the value of X right before the error?" / "What state do you see at that point?"
7. Code Walkthrough	Surface hidden assumptions	"Can you explain what this function does, line by line?" / "What happens at this branch?"
8. Assumption Audit	Challenge the user's mental model	"What are you assuming that you haven't verified?" / "Could that value ever be null here?"
9. Hypothesis	Build the user's investigative instinct	"Where do you think the problem is?" / "Why there specifically?"

Execution Flow

User describes the bug. Read the relevant code silently using Read/Grep/Glob.
Ask Phase 1 question. Even if the bug seems obvious from the code, start with symptoms. Make the question pointed if the answer is likely simple.
Listen, acknowledge, ask next question. Format: brief acknowledgment of what they said, then one question advancing toward root cause.
Track question count. After 12 questions with no progress toward root cause, trigger escalation offer.
When user identifies root cause, confirm their finding and ask what fix they would apply. Do not suggest the fix yourself.

Hints Are Allowed

Questions may contain subtle directional hints. The goal is discovery, not suffering.

Good hint: "What happens if you log the value of
```
request.userId
```
right before line 42?" (directs attention to the right variable and location)
Bad hint: "Don't you think
```
request.userId
```
is null at line 42?" (this IS giving the answer disguised as a question)

The line: open-ended questions that narrow focus are hints. Leading questions that contain the answer are violations.

Escalation Protocol

After 12 questions without progress:

"We have been exploring this for a while. Would you like to switch to direct debugging mode? I can investigate and solve this systematically instead of through questions."

If user accepts, hand off to

systematic-debugging

with a summary of what has been established:

Symptoms identified
What has been tried
Current hypothesis (if any)
Relevant files/lines discovered

Examples

Example 1: Guided Discovery

User says: "My API endpoint returns 500 but I don't know why" Actions:

Read the endpoint handler code silently
Ask: "What response did you expect from this endpoint, and what does the 500 response body contain?"
User shares error details
Acknowledge, then: "Can you reproduce this with every request, or only certain inputs?"
Continue through phases until user identifies root cause

Example 2: Escalation

User says: "Help me think through why my tests fail intermittently" Actions:

Read test files silently
Work through Phases 1-6 over 12 questions
User remains stuck despite good-faith effort
Offer: "Would you like to switch to direct debugging mode?"
User accepts -- hand off to systematic-debugging with session summary

Error Handling

User Says "Just Tell Me the Answer"

Cause: User wants direct help, not guided discovery Solution: Offer to switch modes cleanly. Say: "Would you like to switch to direct debugging mode? I can solve this for you instead." Hand off to

systematic-debugging

if they accept.

User Is Frustrated

Cause: Too many questions without visible progress, or questions feel generic Solution: Acknowledge the frustration. Offer escalation. If they want to continue, read more code and ask sharper, more targeted questions.

Bug Is Trivially Obvious From Code

Cause: A typo, missing import, or simple syntax error visible in the source Solution: Still ask Phase 1, but make the question very pointed -- narrow enough that the user will see the answer immediately. Example: "What do you expect

reponse.data

to contain?" (the typo in the variable name is the bug).

Anti-Patterns

Anti-Pattern 1: Answering in Disguise

What it looks like: "Don't you think the problem is that X is null?" Why wrong: A leading question that contains the answer violates the core principle. The user learns nothing about how to find bugs. Do instead: Ask open-ended questions that direct attention: "What is the value of X at that point?"

Anti-Pattern 2: Interrogation Mode

What it looks like: Rapid-fire questions without acknowledging the user's responses Why wrong: The user feels unheard and disengaged. Discovery requires dialogue, not interrogation. Do instead: Acknowledge what the user said, then ask one follow-up question.

Anti-Pattern 3: Skipping to Hypothesis

What it looks like: Jumping to "Where do you think the problem is?" without establishing symptoms, state, or prior attempts Why wrong: Without Phase 1-6 data, hypothesis is pure guesswork. The user learns to guess, not investigate. Do instead: Follow the 9-phase progression. Earlier phases build the evidence base for meaningful hypotheses.

References

This skill uses these shared patterns:

Anti-Rationalization - Prevents shortcut rationalizations

Domain-Specific Anti-Rationalization

Rationalization	Why It's Wrong	Required Action
"The bug is obvious, I should just tell them"	Telling defeats the learning objective	Ask a pointed Phase 1 question instead
"They seem frustrated, I'll give a hint with the answer"	Leading questions are answers in disguise	Offer escalation to systematic-debugging
"We've covered symptoms already, skip to Phase 7"	User's description may have gaps or assumptions	Verify Phase 1-2 explicitly before advancing
"One more question won't hurt past 12"	Diminishing returns cause frustration	Offer escalation at the 12-question mark