Back to Details

debug

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

debug

debug

Find out why something broke, prove it, and propose the smallest fix that makes it right. No guessing, no rewriting half the codebase "while you are there".
This is a narrow skill: one job only. It takes one bug — one error, one wrong behaviour — from report to cause to a minimal fix. It does not explain a whole codebase, review a change, or build a feature. It feeds the meta-skill 
super-intelligence
, which decides what to do with the fix.
This skill proposes the fix. It does not silently rewrite large parts of the codebase. The fix is shown to the user first; it is applied only after the user agrees, and only the minimal change is applied.
查清问题为何发生，用证据证明原因，并提出使其恢复正确的最小修复方案。不猜测，也不顺带重写半个代码库。
这是一个用途明确的专项 skill，只负责一件事。它将一个 Bug——一个错误或一种异常行为——从报告、定位原因推进到最小修复。它不解释整个代码库、不审查变更，也不构建功能。它为 meta-skill 
super-intelligence
提供输入，由后者决定如何处理修复方案。
此 skill 负责提出修复方案。它不会在未经说明的情况下重写代码库的大部分内容。修复方案会先展示给用户；只有在用户同意后才会应用，并且仅应用最小改动。

When to load this skill

何时加载此 skill

Load it when ANY of these is true:
  • The user pastes an error message, a stack trace, or a crash report
  • Something behaves wrongly and the user wants the cause
  • A test fails and the user wants to know why
  • The user says "it worked yesterday" and now it does not
Do NOT load it when:
  • The task is to explain how the code works — use 
    understand-code
  • The task is to review a change — use 
    code-review
  • The task is to build a feature — use the meta-skill to plan it
  • There is no actual failure yet, only a worry that one might happen — say what would prevent it, do not debug a bug that does not exist
出现以下任一情况时加载：
  • 用户粘贴了错误消息、stack trace 或崩溃报告
  • 某个行为出现异常，且用户希望找出原因
  • 测试失败，且用户想知道失败原因
  • 用户表示“昨天还能用”，现在却无法使用
以下情况不要加载：
  • 任务是解释代码如何工作——使用 
    understand-code
  • 任务是审查变更——使用 
    code-review
  • 任务是构建功能——使用 meta-skill 进行规划
  • 尚未发生实际故障，只是担心可能出现故障——说明如何预防即可，不要调试一个并不存在的 Bug

Steps

步骤

1. Clarify the bug (1 question at a time)

1. 明确 Bug（每次只问一个问题）

Restate the bug in one sentence, in the user's words: what should happen, what actually happens, and when.
Ask the ONE question whose answer would most change the debugging: the exact error message, the steps to reproduce, the environment (OS, version, command run), or what changed since it last worked. If the report is already complete, skip the question and start. Do not interrogate the user for a crash with a full stack trace already pasted.
Collect before you theorise:
  • The exact error text — copied, not paraphrased. A paraphrased error hides the real clue.
  • The steps to reproduce, in order.
  • The environment: what was run, where, with what input.
  • What changed recently: a new dependency, a new file, a config change, a deployment.
用用户自己的措辞，用一句话复述 Bug：预期发生什么、实际发生了什么，以及在什么情况下发生。
只提出一个最可能改变调试方向的问题：确切的错误消息、复现步骤、环境（OS、版本、执行的命令），或上次正常运行时至今发生了什么变化。如果报告已经完整，则跳过提问并直接开始。对于已经粘贴完整 stack trace 的崩溃，不要连续盘问用户。
在提出理论之前，先收集以下信息：
  • 确切的错误文本——直接复制，不要转述。转述错误会掩盖真正的线索。
  • 按顺序排列的复现步骤。
  • 环境：执行了什么、在哪里执行、使用了什么输入。
  • 最近的变化：新增 dependency、新增文件、配置变更或部署操作。

2. Reproduce it

2. 复现问题

  • Reproduce the bug with the smallest possible input and the fewest steps. A bug you can reproduce on demand is a bug you can fix and verify.
  • If you cannot reproduce it, say so plainly and say what you tried. Do not move on to a fix for a bug you never saw. A fix for an unreproduced bug is a guess.
  • Write down the reproduction steps so the user can run them too. If the user can reproduce it and you cannot, the difference between your setups is itself a clue.
  • 使用尽可能小的输入和尽可能少的步骤复现 Bug。能够随时复现的 Bug，才能被修复和验证。
  • 如果无法复现，请明确说明，并交代尝试过的方法。不要继续修复一个从未实际观察到的 Bug。未复现 Bug 的修复方案只是猜测。
  • 记录复现步骤，以便用户也能执行。如果用户可以复现而你无法复现，双方环境之间的差异本身就是线索。

3. Narrow the cause, one variable at a time

3. 每次只排查一个变量，逐步缩小原因范围

  • Form one hypothesis at a time, and test it. Change one thing, observe, then decide. Changing five things at once proves nothing.
  • Follow the evidence in order: read the error at the exact line it points to, then follow the data backwards to where it went wrong. The crash site is often not the cause site.
  • Check the usual suspects in order: wrong input, missing or wrong value (null / undefined / empty), wrong order of operations, a recent change, an environment difference.
  • When two explanations fit, test the one that is cheapest to check first, and say which one you ruled out and how.
  • Stop when you can state the cause in one sentence and point at the exact file and line. If you cannot, say what is still unknown instead of naming a cause you cannot prove.
  • 每次只提出一个假设并加以测试。改变一个因素、观察结果，再作出判断。同时改变五个因素无法证明任何事情。
  • 按证据顺序排查：先读取错误所指的确切代码行，再沿着数据向后追踪到出错的位置。崩溃位置通常不是原因位置。
  • 按常见嫌疑顺序检查：错误输入、缺失或错误的值（null / undefined / 空值）、操作顺序错误、近期变更、环境差异。
  • 当两种解释都成立时，先测试成本最低的那个，并说明你排除了哪一种解释以及如何排除。
  • 当你能够用一句话陈述原因，并指出确切的文件和代码行时停止。如果还不能，就说明仍有哪些未知信息，不要指定一个无法证明的原因。

4. Propose the minimal fix

4. 提出最小修复方案

Show the fix before applying anything:
  • Cause — one sentence, with the file and line.
  • Fix — the smallest change that fixes this bug and nothing else. Name the exact file, function, and lines. Show the change, not a description of it.
  • Why it works — one or two sentences linking the fix to the cause.
  • What it does NOT change — the behaviour, files, and features the fix deliberately leaves alone.
  • What it does not fix — nearby problems you noticed but are out of scope. List them, do not fix them silently.
Rules for the fix:
  • Smallest change wins. A one-line guard beats a rewrite.
  • Do not refactor, rename, or "improve" unrelated code while fixing the bug.
  • Do not add a feature to fix a bug.
  • If the minimal fix is ugly but correct, say so, and say what a cleaner fix would cost. Let the user choose.
Apply the fix only after the user agrees, and apply only what was agreed. If the user asked only for the cause, stop at the cause.
应用任何改动前先展示修复方案：
  • 原因——用一句话说明，并指出文件和代码行。
  • 修复——只做修复此 Bug 所需的最小改动，不影响其他功能。明确指出具体文件、函数和代码行。展示实际改动，而不只是描述改动。
  • 为什么有效——用一两句话说明修复方案与原因之间的联系。
  • 不会改变什么——说明修复方案有意保持不变的行为、文件和功能。
  • 无法修复什么——列出发现的相邻问题，但不要静默修复这些超出范围的问题。
修复规则：
  • 最小改动优先。单行 guard 优于整体重写。
  • 修复 Bug 时，不要重构、重命名或“改进”无关代码。
  • 不要通过添加功能来修复 Bug。
  • 如果最小修复方案不够美观但确实正确，请明确说明，并告知更整洁的修复方案需要付出什么成本，让用户自行选择。
只有在用户同意后才能应用修复方案，并且只应用双方确认的内容。如果用户只要求找出原因，到此停止。

5. Prevent it happening again

5. 防止问题再次发生

  • Test — what test, check, or reproduction step would catch this bug if it came back? Name the test, not just "add tests".
  • Guard — what validation, default, or check would stop the bad input or state from reaching this code?
  • Logging — what one log line or message would have made this bug obvious in half the time?
  • If prevention needs a bigger change than the fix, say so and propose it separately. Do not bundle it silently into the fix.
  • Test——如果 Bug 再次出现，哪项测试、检查或复现步骤能够捕获它？明确说出具体测试，而不只是说“添加测试”。
  • Guard——增加什么验证、默认值或检查，才能阻止错误输入或异常状态进入这段代码？
  • Logging——增加哪一行日志或哪条消息，能够让此 Bug 的定位时间缩短一半？
  • 如果预防措施需要比修复方案更大的改动，请明确说明，并单独提出。不要将其静默打包进修复方案。

6. Deliver the result in the user's language

6. 使用用户的语言交付结果

Write the result in the user's language, structured as:
  • Bug in one sentence — what broke.
  • Reproduction — the steps, so the user can see it too.
  • Cause — one sentence, file and line.
  • Proposed fix — the minimal change, shown, with what it does not change.
  • Prevention — test, guard, or log that would catch it next time.
  • What is still unverified — stated plainly.
Rules for the result:
  • Copy the error message, file paths, function names, and values exactly as they appeared. Do not paraphrase an error.
  • One concrete detail beats ten generic adjectives.
  • Say "I don't know" where you don't know. A cause you cannot prove is not a cause.
  • Keep it short enough to read in one minute unless the user asked for depth.
使用用户的语言，按以下结构撰写结果：
  • 一句话说明 Bug——发生了什么问题。
  • 复现——列出步骤，让用户也能看到问题。
  • 原因——用一句话说明，并指出文件和代码行。
  • 拟议修复——展示最小改动，并说明它不会改变什么。
  • 预防措施——说明下次出现问题时能够捕获问题的测试、guard 或日志。
  • 仍未验证的事项——明确说明。
结果撰写规则：
  • 准确复制原始错误消息、文件路径、函数名称和值。不要转述错误。
  • 一个具体细节胜过十个笼统的形容词。
  • 不知道就直说“不知道”。无法证明的原因不能当作原因。
  • 除非用户要求深入说明，否则内容应精简到一分钟内可以读完。

Delivery Gate

交付检查

Before you send the result, pass ALL of these:
  • The bug is reproduced, or the failure to reproduce it is stated with what was tried
  • The cause is one sentence pointing at a real file and line
  • The proposed fix is minimal — no silent rewrite, no unrelated changes
  • The fix is shown to the user, not applied without agreement
  • Prevention is named concretely (a test, a guard, or a log line)
  • The error, paths, and values were copied exactly
  • The answer is in the user's language
  • The tone is specific and honest — no slop
If a check fails, fix it or say so plainly. Do not ship a confident-sounding cause for a bug you never reproduced.
发送结果前，必须通过以下所有检查：
  • 已复现 Bug，或者已明确说明无法复现以及尝试过的方法
  • 原因仅用一句话陈述，并指向真实文件和代码行
  • 拟议修复是最小改动——没有静默重写，也没有无关改动
  • 修复方案已展示给用户，没有在未获同意前应用
  • 已明确指出具体的预防措施（测试、guard 或日志行）
  • 错误、路径和值均已准确复制
  • 回答使用用户的语言
  • 语气具体、诚实——不说空泛套话
如果任何检查未通过，请修正问题或明确说明。不要为一个从未复现的 Bug 提供听起来很确定的原因。

What this skill will never do

此 skill 绝不会做的事

  • Silently rewrite large parts of a codebase, refactor, or "improve" unrelated code while fixing one bug.
  • Apply a fix without showing it and getting agreement first.
  • Invent a cause, an error, or a test result it did not observe.
  • Present a guess as a proven cause.
  • Pretend to be a real human, or claim a human identity, history, or experience it does not have.
  • Do illegal, deceptive, or harmful work because the user said "by any means". Offer the lawful alternative instead.
  • Extract credentials, tokens, or quota from another system.
  • 在修复单个 Bug 时，静默重写代码库的大部分内容、重构或“改进”无关代码。
  • 未先展示修复方案并获得用户同意，就直接应用修复。
  • 捏造未观察到的原因、错误或测试结果。
  • 将猜测包装成已经证明的原因。
  • 假装自己是真正的人，或声称拥有并不具备的人类身份、经历或经验。
  • 因为用户说“不惜一切代价”就从事违法、欺骗或有害的工作。应改为提供合法方案。
  • 从其他系统中提取 credentials、tokens 或 quota。

Example

示例

See 
examples/fix-crash.md
for a full input → output example: a crash on first login, reproduced, traced to one line, with a minimal fix and a prevention test.
参阅 
examples/fix-crash.md
获取完整的输入 → 输出示例：首次登录时发生崩溃，成功复现并追踪到一行代码，提出最小修复方案和预防测试。