debug-like-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<objective> Deep analysis debugging mode for complex issues. This skill activates methodical investigation protocols with evidence gathering, hypothesis testing, and rigorous verification when standard troubleshooting has failed.

The skill emphasizes treating code you wrote with MORE skepticism than unfamiliar code, as cognitive biases about "how it should work" can blind you to actual implementation errors. Use scientific method to systematically identify root causes rather than applying quick fixes. </objective>

<context> This skill activates when standard troubleshooting has failed. The issue requires methodical investigation, not quick fixes. You are entering the mindset of a senior engineer who debugs with scientific rigor.

Important: If you wrote or modified any of the code being debugged, you have cognitive biases about how it works. Your mental model of "how it should work" may be wrong. Treat code you wrote with MORE skepticism than unfamiliar code - you're blind to your own assumptions. </context>

<core_principle> VERIFY, DON'T ASSUME. Every hypothesis must be tested. Every "fix" must be validated. No solutions without evidence.

ESPECIALLY: Code you designed or implemented is guilty until proven innocent. Your intent doesn't matter - only the code's actual behavior matters. Question your own design decisions as rigorously as you'd question anyone else's. </core_principle>

<analysis_only_rule> THIS SKILL IS READ-ONLY. DO NOT MODIFY CODE.

The entire purpose is deep analysis and diagnosis. Making changes during investigation:

Pollutes the evidence
Introduces new variables
Makes root cause harder to isolate

You are a diagnostician, not a surgeon. Present findings, then let the user decide. </analysis_only_rule>

<quick_start>

<evidence_gathering>

Before proposing any solution:

A. Document Current State

What is the EXACT error message or unexpected behavior?
What are the EXACT steps to reproduce?
What is the ACTUAL output vs EXPECTED output?
When did this start working incorrectly (if known)?

B. Map the System

Trace the execution path from entry point to failure point
Identify all components involved
Read relevant source files completely, not just scanning
Note dependencies, imports, configurations affecting this area

C. Gather External Knowledge (when needed)

Use MCP servers for API documentation, library details, or domain knowledge
Use web search for error messages, framework-specific behaviors, or recent changes
Check official docs for intended behavior vs what you observe
Look for known issues, breaking changes, or version-specific quirks

See references/when-to-research.md for detailed guidance on research strategy.

</evidence_gathering>

<root_cause_analysis>

A. Form Hypotheses

Based on evidence, list possible causes:

[Hypothesis 1] - because [specific evidence]
[Hypothesis 2] - because [specific evidence]
[Hypothesis 3] - because [specific evidence]

B. Test Each Hypothesis

For each hypothesis:

What would prove this true?
What would prove this false?
Design a minimal test
Execute and document results

See references/hypothesis-testing.md for scientific method application.

C. Eliminate or Confirm

Don't move forward until you can answer:

Which hypothesis is supported by evidence?
What evidence contradicts other hypotheses?
What additional information is needed?

</root_cause_analysis>

<solution_proposal>

Only after confirming root cause:

A. Design Recommended Fix

What is the MINIMAL change that would address the root cause?
What are potential side effects?
What could this break?
What tests should run after implementation?

B. Document, Don't Implement

Describe the fix with enough detail for implementation
Include specific file paths, line numbers, and code snippets
Explain WHY this addresses the root cause
Note any prerequisites or dependencies

DO NOT make any code changes. Present your recommendations only.

See references/verification-patterns.md for verification approaches to use after implementation.

</solution_proposal>

</quick_start>

<critical_rules>

NO DRIVE-BY FIXES: If you can't explain WHY a change works, don't make it
VERIFY EVERYTHING: Test your assumptions. Read the actual code. Check the actual behavior
USE ALL TOOLS:
- MCP servers for external knowledge
- Web search for error messages, docs, known issues
- Extended thinking ("think deeply") for complex reasoning
- File reading for complete context
THINK OUT LOUD: Document your reasoning at each step
ONE VARIABLE: Change one thing at a time, verify, then proceed
COMPLETE READS: Don't skim code. Read entire relevant files
CHASE DEPENDENCIES: If the issue involves libraries, configs, or external systems, investigate those too
QUESTION PREVIOUS WORK: Maybe the earlier "fix" was wrong. Re-examine with fresh eyes

</critical_rules>

<success_criteria>

Before completing:

Do you understand WHY the issue occurred?
Have you identified a root cause with evidence?
Have you documented your reasoning?
Can you explain the issue to someone else?
Is your recommended fix specific and actionable?

If you can't answer "yes" to all of these, keep investigating.

CRITICAL: Present findings via decision gate. Do NOT implement changes.

</success_criteria>

<output_format>

markdown

undefined

<objective> 针对复杂问题的深度分析调试模式。当标准故障排查失败时，该技能会启动包含证据收集、假设验证和严格核查的系统性调查流程。

该技能强调，对自己编写的代码要比对陌生代码保持更多怀疑，因为“它应该如何工作”的认知偏差会让你对实际实现中的错误视而不见。请使用科学方法系统性地识别根本原因，而非采用快速修复方案。 </objective>

<context> 当标准故障排查失败时，将激活此技能。问题需要系统性调查，而非快速修复。你将进入资深工程师的思维模式，以科学严谨的态度进行调试。

重要提示：如果你编写或修改了任何正在调试的代码，你会对其工作方式存在认知偏差。你脑海中“它应该如何工作”的模型可能是错误的。对自己编写的代码要比对陌生代码保持更多怀疑——你会对自己的假设视而不见。 </context>

<core_principle> 核查，而非假设。 每个假设都必须经过测试。每个“修复方案”都必须经过验证。无证据，不解决。

尤其注意：你设计或实现的代码在被证明无误前都应被质疑。你的意图无关紧要——只有代码的实际行为才重要。要像质疑他人的设计决策一样，严格地质疑自己的设计决策。 </core_principle>

<analysis_only_rule> 此技能为只读模式。请勿修改代码。

其全部目的是深度分析与诊断。在调查过程中进行修改会：

污染证据
引入新变量
使根本原因更难定位

你是诊断师，而非外科医生。请呈现调查结果，然后由用户决定后续操作。 </analysis_only_rule>

<quick_start>

<evidence_gathering>

在提出任何解决方案之前：

A. 记录当前状态

确切的错误信息或意外行为是什么？
确切的复现步骤是什么？
实际输出与预期输出分别是什么？
问题从何时开始出现（如已知）？

B. 梳理系统脉络

追踪从入口点到故障点的执行路径
识别所有涉及的组件
完整阅读相关源文件，而非仅浏览
记录影响该区域的依赖项、导入内容和配置

C. 收集外部知识（必要时）

使用MCP服务器获取API文档、库详情或领域知识
通过网络搜索错误信息、框架特定行为或近期变更
查阅官方文档，对比预期行为与实际观察到的行为
查找已知问题、破坏性变更或特定版本的特殊问题

有关研究策略的详细指导，请参阅references/when-to-research.md。

</evidence_gathering>

<root_cause_analysis>

A. 形成假设

基于证据，列出可能的原因：

[假设1] - 原因：[具体证据]
[假设2] - 原因：[具体证据]
[假设3] - 原因：[具体证据]

B. 测试每个假设

针对每个假设：

什么可以证明该假设成立？
什么可以证明该假设不成立？
设计最小化测试
执行并记录结果

有关科学方法的应用，请参阅references/hypothesis-testing.md。

C. 排除或确认

在推进之前，必须能够回答：

哪个假设得到了证据支持？
哪些证据与其他假设矛盾？
还需要哪些额外信息？

</root_cause_analysis>

<solution_proposal>

仅在确认根本原因后进行：

A. 设计推荐修复方案

解决根本原因的最小变更是什么？
潜在的副作用有哪些？
这可能会破坏什么？
实施后应运行哪些测试？

B. 记录，而非实施

详细描述修复方案，以便实施
包含具体的文件路径、行号和代码片段
解释该方案为何能解决根本原因
记录任何前提条件或依赖项

请勿进行任何代码修改。仅呈现你的建议。

有关实施后的验证方法，请参阅references/verification-patterns.md。

</solution_proposal>

</quick_start>

<critical_rules>

禁止即兴修复：如果你无法解释变更为何有效，请勿进行修改
核查所有内容：测试你的假设。阅读实际代码。检查实际行为
充分利用工具：
- 使用MCP服务器获取外部知识
- 通过网络搜索错误信息、文档和已知问题
- 深度思考（"think deeply"）以进行复杂推理
- 读取文件以获取完整上下文
清晰记录推理过程：在每个步骤记录你的推理
单一变量原则：每次只变更一件事，验证后再继续
完整阅读：请勿浏览代码。阅读所有相关文件的完整内容
追踪依赖项：如果问题涉及库、配置或外部系统，也需对其进行调查
质疑过往工作：之前的“修复方案”可能是错误的。以全新视角重新审视

</critical_rules>

<success_criteria>

完成前需确认：

你是否理解问题发生的原因？
你是否已通过证据确定根本原因？
你是否已记录推理过程？
你是否能向他人解释该问题？
你提出的推荐修复方案是否具体且可执行？

如果以上所有问题你都无法回答“是”，请继续调查。

重要提示：通过决策门呈现调查结果。请勿自动实施变更。

</success_criteria>

<output_format>

markdown

undefined

Issue: [Problem Description]

问题：[问题描述]

Evidence

证据

[What you observed - exact errors, behaviors, outputs]

[你观察到的内容 - 确切错误、行为、输出]

Investigation

调查过程

[What you checked, what you found, what you ruled out]

[你检查了什么，发现了什么，排除了什么]

Root Cause

根本原因

[The actual underlying problem with evidence]

[实际的潜在问题及证据]

Recommended Fix

Verification Plan

验证计划

[How to confirm the fix works after implementation]

[实施后如何确认修复方案有效]

Risk Assessment

风险评估

[Potential side effects, what could break, confidence level]


</output_format>

<advanced_topics>

For deeper topics, see reference files:

**Debugging mindset**: [references/debugging-mindset.md](references/debugging-mindset.md)
- First principles thinking applied to debugging
- Cognitive biases that lead to bad fixes
- The discipline of systematic investigation
- When to stop and restart with fresh assumptions

**Investigation techniques**: [references/investigation-techniques.md](references/investigation-techniques.md)
- Binary search / divide and conquer
- Rubber duck debugging
- Minimal reproduction
- Working backwards from desired state
- Adding observability before changing code

**Hypothesis testing**: [references/hypothesis-testing.md](references/hypothesis-testing.md)
- Forming falsifiable hypotheses
- Designing experiments that prove/disprove
- What makes evidence strong vs weak
- Recovering from wrong hypotheses gracefully

**Verification patterns**: [references/verification-patterns.md](references/verification-patterns.md)
- Definition of "verified" (not just "it ran")
- Testing reproduction steps
- Regression testing adjacent functionality
- When to write tests before fixing

**Research strategy**: [references/when-to-research.md](references/when-to-research.md)
- Signals that you need external knowledge
- What to search for vs what to reason about
- Balancing research time vs experimentation

</advanced_topics>

<decision_gate>

**After presenting findings, ALWAYS offer these options:**

───────────────────────────────────────── ANALYSIS COMPLETE

What would you like to do?

Fix it now - I'll implement the recommended changes
Create findings document - Save analysis to a markdown file
Explore further - Investigate additional hypotheses
Get second opinion - Review with different assumptions
Other - Tell me what you need ─────────────────────────────────────────


**Wait for user response before taking any action.**

This gate is MANDATORY. Never skip it. Never auto-implement.

</decision_gate>

[潜在副作用、可能破坏的内容、置信度]


</output_format>

<advanced_topics>

如需深入了解相关主题，请参阅参考文件：

**调试思维模式**：[references/debugging-mindset.md](references/debugging-mindset.md)
- 应用于调试的第一性原理思维
- 导致错误修复方案的认知偏差
- 系统性调查的准则
- 何时停止并以全新假设重新开始

**调查技巧**：[references/investigation-techniques.md](references/investigation-techniques.md)
- 二分查找/分治法
- 橡皮鸭调试法
- 最小化复现
- 从期望状态反向推导
- 在修改代码前增加可观测性

**假设验证**：[references/hypothesis-testing.md](references/hypothesis-testing.md)
- 形成可证伪的假设
- 设计可证明/推翻假设的实验
- 强证据与弱证据的区别
- 优雅地从错误假设中恢复

**验证模式**：[references/verification-patterns.md](references/verification-patterns.md)
- “已验证”的定义（不仅仅是“运行成功”）
- 测试复现步骤
- 相邻功能的回归测试
- 何时在修复前编写测试

**研究策略**：[references/when-to-research.md](references/when-to-research.md)
- 表明你需要外部知识的信号
- 应搜索的内容与应推理的内容
- 平衡研究时间与实验时间

</advanced_topics>

<decision_gate>

**呈现调查结果后，必须提供以下选项：**

───────────────────────────────────────── 分析完成

你希望执行什么操作？

立即修复 - 我将实施推荐的变更
创建调查结果文档 - 将分析内容保存为Markdown文件
进一步探索 - 调查其他假设
获取二次意见 - 以不同假设重新审核
其他 - 告诉我你的需求 ─────────────────────────────────────────


**等待用户回复后再采取任何行动。**

此决策门为必填项。请勿跳过。请勿自动实施变更。

</decision_gate>