socratic-debugging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

本技能作为提问引导式调试的操作器，配置Claude的行为，通过结构化探究而非直接给出答案的方式教授调试方法。它采用苏格拉底方法模式——提出问题引导用户自行发现问题根源，培养持久的排查能力。

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.

绝不直接给出答案：不得直接透露问题根源、修复方案或解决办法。用户必须自行得出结论，这是本技能的核心目标——直接给出答案会违背学习目的。
先阅读代码：在提出问题前，务必使用Read/Grep/Glob工具理解相关代码。对代码的了解能让问题更精准、更具实效性，而非泛泛而谈。
遵循9阶段推进流程：在未明确症状（第1阶段）和当前状态（第6阶段）的情况下，不得直接跳至假设问题（第9阶段）。跳过阶段会导致猜测而非系统性排查。
12个提问后提供升级选项：如果经过12个提问用户仍未取得进展，可提议切换至
```
systematic-debugging
```
模式。升级是顺畅的交接，而非失败。

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.

从第1阶段开始：无论用户的描述多么具体，都从“症状”阶段开始。即使是详细的报告，也往往包含未阐明的假设。
一次只提一个问题：每次只提一个问题，然后等待用户回复。多个问题会让用户不知所措，分散注意力。
使用用户的术语：在问题中复用用户提到的变量名、函数名和领域术语。这能减少沟通障碍，表明你关注他们的具体问题。
认可用户的进展：当用户发现新线索时，先认可他们的发现，再提出下一个问题。沉默推进会让用户感觉像在被审问。

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.

跳过阶段：如果用户在初始描述中已清晰且全面地覆盖了前面的阶段，可直接跳至后续阶段。
代码读取建议：当用户在状态排查中遇到瓶颈时，建议具体的诊断操作（如“尝试在第X行添加日志语句”）。

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?"

按顺序遵循以下9个阶段。每个阶段都有明确的目标——除非有证据表明用户已完成该阶段的内容，否则不得跳过。

阶段	目标	示例问题
1. 症状	明确预期结果与实际结果的差距	“你预期会发生什么？” / “实际发生了什么？”
2. 可复现性	确定bug是否具有确定性	“你能稳定复现这个问题吗？” / “触发该问题的条件是什么？”
3. 已尝试的方案	避免重复无效的方法	“你已经尝试过哪些方法？” / “尝试后结果如何？”
4. 最小化用例	缩小排查范围	“你能用更少的代码复现这个问题吗？” / “能触发问题的最小输入是什么？”
5. 错误分析	从错误输出中提取有效信息	“错误信息告诉你什么？” / “错误信息中哪部分最有参考价值？”
6. 状态检查	基于实际数据开展排查	“错误发生前，X的值是什么？” / “此时你观察到的状态是什么？”
7. 代码走查	发现隐藏的假设	“你能逐行解释这个函数的作用吗？” / “这个分支会执行什么逻辑？”
8. 假设验证	挑战用户的思维模型	“你有哪些未验证的假设？” / “这个值在这里有可能为null吗？”
9. 提出假设	培养用户的排查直觉	“你认为问题出在哪里？” / “为什么你觉得是这里？”

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.

用户描述问题：使用Read/Grep/Glob工具静默阅读相关代码。
提出第1阶段问题：即使从代码中能明显看出问题，也要从症状阶段开始提问。如果答案可能很简单，可让问题更具针对性。
倾听、认可、提出下一个问题：格式为先简要认可用户的回复，再提出一个能引导排查根源的问题。
跟踪提问次数：经过12个提问仍无进展时，触发升级提议。
当用户找到根源时：确认他们的发现，然后询问他们会采用什么修复方案。不得自行建议修复方案。

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.

问题中可包含细微的方向性提示。目标是引导发现，而非让用户陷入困境。

合适的提示：“在第42行之前，你可以打印
```
request.userId
```
的值看看结果如何？”（将注意力引导至正确的变量和位置）
不合适的提示：“你不觉得第42行的
```
request.userId
```
是null吗？”（这是伪装成问题的直接答案）

核心区别：开放式且能缩小排查范围的问题是提示；包含答案的诱导性问题则违反原则。

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

经过12个提问仍无进展时：

“我们已经探讨了一段时间。你是否愿意切换至直接调试模式？我可以通过系统化排查来解决问题，而非继续通过提问引导。”

如果用户同意，将当前会话交接至

systematic-debugging

模式，并提供已确认内容的总结：

已识别的症状
已尝试的方案
当前假设（如有）
已发现的相关文件/代码行

Examples

示例

Example 1: Guided Discovery

示例1：引导式发现

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

用户说：“我的API接口返回500错误，但我不知道原因” 操作步骤：

静默阅读接口处理代码
提问：“你预期这个接口会返回什么响应？500错误的响应体包含什么内容？”
用户分享错误详情
认可用户的回复，然后提问：“你每次请求都会复现这个错误，还是只有特定输入才会触发？”
按阶段继续推进，直到用户找到问题根源

Example 2: Escalation

示例2：模式升级

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

用户说：“帮我梳理一下为什么我的测试会间歇性失败” 操作步骤：

静默阅读测试文件
通过12个提问完成第1至第6阶段的排查
用户虽已尽力但仍陷入困境
提议：“你是否愿意切换至直接调试模式？”
用户同意后，将会话交接至systematic-debugging模式，并提供会话总结

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.

原因：用户想要直接帮助，而非引导式发现解决方案：清晰地提议切换模式。可以说：“你是否愿意切换至直接调试模式？我可以直接为你解决问题。”如果用户同意，交接至

systematic-debugging

模式。

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

从代码中可明显看出简单bug

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).

原因：代码中存在拼写错误、缺失导入或简单语法错误解决方案：仍从第1阶段开始提问，但问题要极具针对性——精准到让用户能立刻发现问题。例如：“你预期

reponse.data

包含什么内容？”（变量名拼写错误就是问题所在）

Anti-Patterns

反模式

Anti-Pattern 1: Answering in Disguise

反模式1：伪装成问题的答案

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?"

表现：“你不觉得问题出在X为null吗？” 错误原因：诱导性问题包含答案，违反了核心原则。用户无法学到任何排查问题的方法。 正确做法：提出开放式问题引导注意力：“此时X的值是什么？”

Anti-Pattern 2: Interrogation Mode

反模式2：审问式提问

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

反模式3：直接跳至假设阶段

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.

表现：在未明确症状、状态或已尝试方案的情况下，直接提问“你认为问题出在哪里？” 错误原因：没有第1至6阶段的数据支撑，假设只是纯粹的猜测。用户会学会猜测而非排查。 正确做法：遵循9阶段推进流程。前面的阶段为有意义的假设构建证据基础。

References

参考资料

This skill uses these shared patterns:

Anti-Rationalization - Prevents shortcut rationalizations

本技能采用以下共享模式：

Anti-Rationalization - 避免捷径式合理化解释

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

合理化解释	错误原因	要求操作
“这个bug很明显，我应该直接告诉用户”	直接给出答案会违背学习目标	改为提出一个针对性的第1阶段问题
“用户看起来很沮丧，我可以给一个带答案的提示”	诱导性问题是伪装的答案	提议升级至systematic-debugging模式
“我们已经覆盖了症状，直接跳至第7阶段”	用户的描述可能存在遗漏或假设	在推进前需明确验证第1至2阶段的内容
“超过12个问题再提一个也没关系”	边际效益递减会导致用户沮丧	在第12个提问时提供升级选项