ce-debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Debug and Fix

调试与修复（Debug and Fix）

Find root causes, then fix them. This skill investigates bugs systematically — tracing the full causal chain before proposing a fix — and optionally implements the fix with test-first discipline.

<bug_description> #$ARGUMENTS </bug_description>

查找根本原因，再进行修复。本技能会系统地调查Bug——在给出修复方案前先追踪完整的因果链——还可选择遵循测试优先的准则实现修复。

<bug_description> #$ARGUMENTS </bug_description>

Core Principles

核心原则

These principles govern every phase. They are repeated at decision points because they matter most when the pressure to skip them is highest.

Investigate before fixing. Do not propose a fix until you can explain the full causal chain from trigger to symptom with no gaps. "Somehow X leads to Y" is a gap.
Predictions for uncertain links. When the causal chain has uncertain or non-obvious links, form a prediction — something in a different code path or scenario that must also be true. If the prediction is wrong but a fix "works," you found a symptom, not the cause. When the chain is obvious (missing import, clear null reference), the chain explanation itself is sufficient.
One change at a time. Test one hypothesis, change one thing. If you're changing multiple things to "see if it helps," stop — that is shotgun debugging.
When stuck, diagnose why — don't just try harder.

这些原则贯穿每个阶段，我们会在决策节点重复提示这些原则，因为越是想跳过它们的时候，它们越重要。

先调查再修复。在你能无断点地解释从触发条件到表现症状的完整因果链之前，不要提出修复方案。「X不知怎么就导致了Y」就属于断点。
不确定环节要有预测。如果因果链存在不确定或不明确的环节，要形成一个预测——即另一个代码路径或场景中必然成立的事实。如果预测错误但修复「生效了」，说明你找到的只是症状而非原因。如果因果链非常明确（缺失导入、明显的空引用），直接给出因果链解释就足够。
一次只改一个点。测试一个假设，修改一处内容。如果你为了「看看能不能用」同时改多个点，立刻停下——这是霰弹式调试。
卡住时要诊断原因，不要瞎试。

Execution Flow

执行流程

Phase	Name	Purpose
0	Triage	Parse input, fetch issue if referenced, proceed to investigation
1	Investigate	Reproduce the bug, trace the code path
2	Root Cause	Form hypotheses with predictions for uncertain links, test them, causal chain gate, smart escalation
3	Fix	Only if user chose to fix. Test-first fix with workspace safety checks
4	Close	Structured summary, handoff options

All phases self-size — a simple bug flows through them in seconds, a complex bug spends more time in each naturally. No complexity classification, no phase skipping.

阶段	名称	目的
0	初步筛查	解析输入，拉取引用的问题内容，进入调查阶段
1	调查	复现Bug，追踪代码路径
2	根因定位	结合不确定环节的预测形成假设，验证假设，因果链校验，智能升级处理
3	修复	仅当用户选择修复时执行。遵循测试优先原则修复，同时做工作区安全检查
4	收尾	结构化总结，提供移交选项

所有阶段会自适应时长：简单Bug几秒就能走完所有流程，复杂Bug自然会在每个阶段花费更多时间。无需提前分级复杂度，也不能跳过任何阶段。

Phase 0: Triage

阶段0：初步筛查

Parse the input and reach a clear problem statement.

If the input references an issue tracker, fetch it:

GitHub (
```
#123
```
,
```
org/repo#123
```
, github.com URL): Parse the issue reference from
```
<bug_description>
```
and fetch with
```
gh issue view <number> --json title,body,comments,labels
```
. For URLs, pass the URL directly to
```
gh
```
.
Other trackers (Linear URL/ID, Jira URL/key, any tracker URL): Attempt to fetch using available MCP tools or by fetching the URL content. If the fetch fails — auth, missing tool, non-public page — ask the user to paste the relevant issue content.

Extract reported symptoms, expected behavior, reproduction steps, and environment details. Then proceed to Phase 1.

Everything else (stack traces, test paths, error messages, descriptions of broken behavior): Proceed directly to Phase 1.

Questions:

Do not ask questions by default — investigate first (read code, run tests, trace errors)
Only ask when a genuine ambiguity blocks investigation and cannot be resolved by reading code or running tests
When asking, ask one specific question

Prior-attempt awareness: If the user indicates prior failed attempts ("I've been trying", "keeps failing", "stuck"), ask what they have already tried before investigating. This avoids repeating failed approaches and is one of the few cases where asking first is the right call.

解析输入，形成清晰的问题描述。

如果输入引用了问题跟踪器，先拉取对应内容：

GitHub（
```
#123
```
、
```
org/repo#123
```
、github.com链接）：从
```
<bug_description>
```
中解析问题引用，用
```
gh issue view <number> --json title,body,comments,labels
```
拉取内容。如果是链接，直接把链接传给
```
gh
```
。
其他跟踪器（Linear链接/ID、Jira链接/key、任意跟踪器链接）：尝试用可用的MCP工具或直接拉取链接内容。如果拉取失败（权限问题、缺少工具、非公开页面），请用户粘贴相关的问题内容。

提取上报的症状、预期行为、复现步骤和环境信息，然后进入阶段1。

其他所有情况（stack traces、测试路径、错误消息、异常行为描述）：直接进入阶段1。

提问规则：

默认不要提问，先调查（读代码、跑测试、追踪错误）
只有当存在确实无法通过读代码或跑测试解决的歧义，阻塞了调查时再提问
提问时一次只问一个具体问题

感知过往尝试： 如果用户提到之前尝试失败过（「我试了好多次」、「一直失败」、「卡住了」），调查前先问用户已经试过哪些方案。这样可以避免重复失败的路径，这也是少数需要先提问的场景。

Phase 1: Investigate

阶段1：调查

1.1 Reproduce the bug

1.1 复现Bug

Confirm the bug exists and understand its behavior. Run the test, trigger the error, follow reported reproduction steps — whatever matches the input.

Browser bugs: Prefer
```
agent-browser
```
if installed. Otherwise use whatever works — MCP browser tools, direct URL testing, screenshot capture, etc.
Manual setup required: If reproduction needs specific conditions the agent cannot create alone (data states, user roles, external services, environment config), document the exact setup steps and guide the user through them. Clear step-by-step instructions save significant time even when the process is fully manual.
Does not reproduce after 2-3 attempts: Read
```
references/investigation-techniques.md
```
for intermittent-bug techniques.
Cannot reproduce at all in this environment: Document what was tried and what conditions appear to be missing.

确认Bug真实存在并理解其行为。运行测试、触发错误、遵循上报的复现步骤——选择和输入匹配的方式。

浏览器Bug： 如果安装了
```
agent-browser
```
优先使用，否则用其他可用工具：MCP浏览器工具、直接URL测试、截图捕获等。
需要手动设置： 如果复现需要Agent无法独立完成的特定条件（数据状态、用户角色、外部服务、环境配置），记录准确的设置步骤，引导用户完成。哪怕是完全手动的流程，清晰的分步指引也能节省大量时间。
尝试2-3次仍无法复现： 阅读
```
references/investigation-techniques.md
```
中的偶现Bug处理技巧。
在当前环境完全无法复现： 记录已经尝试过的操作，以及看起来缺失的条件。

1.2 Trace the code path

1.2 追踪代码路径

Read the relevant source files. Follow the execution path from entry point to where the error manifests. Trace backward through the call chain:

Start at the error
Ask "where did this value come from?" and "who called this?"
Keep going upstream until finding the point where valid state first became invalid
Do not stop at the first function that looks wrong — the root cause is where bad state originates, not where it is first observed

As you trace:

Check recent changes in files you are reading:
```
git log --oneline -10 -- [file]
```
If the bug looks like a regression ("it worked before"), use
```
git bisect
```
(see
```
references/investigation-techniques.md
```
)
Check the project's observability tools for additional evidence:
- Error trackers (Sentry, AppSignal, Datadog, BetterStack, Bugsnag)
- Application logs
- Browser console output
- Database state
Each project has different systems available; use whatever gives a more complete picture

阅读相关的源文件，沿着执行路径从入口点追踪到错误出现的位置。沿着调用链反向追溯：

从错误点开始
问「这个值是从哪来的？」和「谁调用了这个方法？」
一直向上溯源，直到找到有效状态首次变为无效的节点
不要停在第一个看起来有问题的函数——根因是错误状态产生的位置，不是它第一次被观测到的位置

追溯过程中：

查看你正在读的文件的近期变更：
```
git log --oneline -10 -- [file]
```
如果Bug看起来是回归问题（「之前是好的」），用
```
git bisect
```
（参考
```
references/investigation-techniques.md
```
）
查看项目的可观测工具获取更多证据：
- 错误跟踪工具（Sentry、AppSignal、Datadog、BetterStack、Bugsnag）
- 应用日志
- 浏览器控制台输出
- 数据库状态
每个项目可用的系统不同，用能提供更完整信息的工具即可

Phase 2: Root Cause

阶段2：根因定位

Reminder: investigate before fixing. Do not propose a fix until you can explain the full causal chain from trigger to symptom with no gaps.

Read

references/anti-patterns.md

before forming hypotheses.

Form hypotheses ranked by likelihood. For each, state:

What is wrong and where (file:line)
The causal chain: how the trigger leads to the observed symptom, step by step
For uncertain links in the chain: a prediction — something in a different code path or scenario that must also be true if this link is correct

When the causal chain is obvious and has no uncertain links (missing import, clear type error, explicit null dereference), the chain explanation itself is the gate — no prediction required. Predictions are a tool for testing uncertain links, not a ritual for every hypothesis.

Before forming a new hypothesis, review what has already been ruled out and why.

Causal chain gate: Do not proceed to Phase 3 until you can explain the full causal chain — from the original trigger through every step to the observed symptom — with no gaps. The user can explicitly authorize proceeding with the best-available hypothesis if investigation is stuck.

Reminder: if a prediction was wrong but the fix appears to work, you found a symptom. The real cause is still active.

提醒：先调查再修复。在你能无断点地解释从触发条件到表现症状的完整因果链之前，不要提出修复方案。

形成假设前先阅读

references/anti-patterns.md

。

按可能性从高到低形成假设，每个假设要说明：

哪里出了问题，具体位置（文件:行号）
因果链：触发条件如何一步步导致观测到的症状
针对链中的不确定环节：给出一个预测——如果这个环节正确，另一个代码路径或场景中必然成立的事实

如果因果链非常明确且没有不确定环节（缺失导入、明显的类型错误、显式空指针解引用），因果链解释本身就能通过校验，不需要预测。预测是测试不确定环节的工具，不是每个假设都必须走的流程。

形成新假设前，回顾已经被排除的假设及其排除原因。

因果链校验： 在你能无断点地解释完整因果链（从原始触发条件到每一步再到观测到的症状）之前，不要进入阶段3。如果调查卡住，用户可以明确授权用当前最优假设继续推进。

提醒：如果预测错误但修复看起来生效了，你找到的只是症状，真正的原因仍然存在。

Present findings

展示结论

Once the root cause is confirmed, present:

The root cause (causal chain summary with file:line references)
The proposed fix and which files would change
Which tests to add or modify to prevent recurrence (specific test file, test case description, what the assertion should verify)
Whether existing tests should have caught this and why they did not

Then offer next steps (use the platform's question tool —

AskUserQuestion

in Claude Code,

request_user_input

in Codex,

ask_user

in Gemini — or present numbered options and wait):

Fix it now — proceed to Phase 3
View in Proof (
```
/proof
```
) — for easy review and sharing with others
Rethink the design (
```
/ce:brainstorm
```
) — only when the root cause reveals a design problem (see below)

Do not assume the user wants action right now. The test recommendations are part of the diagnosis regardless of which path is chosen.

When to suggest brainstorm: Only when investigation reveals the bug cannot be properly fixed within the current design — the design itself needs to change. Concrete signals observable during debugging:

The root cause is a wrong responsibility or interface, not wrong logic. The module should not be doing this at all, or the boundary between components is in the wrong place. (Observable: the fix requires moving responsibility between modules, not correcting code within one.)
The requirements are wrong or incomplete. The system behaves as designed, but the design does not match what users actually need. The "bug" is really a product gap. (Observable: the code is doing exactly what it was written to do — the spec is the problem.)
Every fix is a workaround. You can patch the symptom, but cannot articulate a clean fix because the surrounding code was built on an assumption that no longer holds. (Observable: you keep wanting to add special cases or flags rather than a direct correction.)

Do not suggest brainstorm for bugs that are large but have a clear fix — size alone does not make something a design problem.

根因确认后，展示以下内容：

根因（带文件:行号引用的因果链总结）
proposed fix 以及需要修改的文件
需要新增或修改哪些测试来避免复发（具体测试文件、测试用例描述、断言应该验证的内容）
现有测试是否本该捕获这个问题，以及没捕获的原因

然后提供下一步选项（用平台的提问工具——Claude Code里用

AskUserQuestion

、Codex里用

request_user_input

、Gemini里用

ask_user

——或者给出编号选项等待用户选择）：

立即修复 —— 进入阶段3
在Proof中查看 (
```
/proof
```
) —— 方便审阅和和其他人共享
重新思考设计 (
```
/ce:brainstorm
```
) —— 仅当根因暴露了设计问题时提供（见下文）

不要默认用户现在就想要执行操作。不管选哪条路径，测试建议都是诊断结果的一部分。

什么时候建议头脑风暴： 仅当调查发现Bug在现有设计下无法妥善修复——设计本身需要变更时才建议。调试过程中可观测到的明确信号：

根因是职责或接口错误，不是逻辑错误。模块本就不该做这件事，或是组件的边界划分错误。（可观测特征：修复需要在模块间转移职责，而不是修改单个模块内的代码。）
需求错误或不完整。系统行为符合设计，但设计不符合用户的真实需求。这个「Bug」本质是产品缺口。（可观测特征：代码完全按照编写的逻辑执行——问题出在需求规范上。）
所有修复都是 workaround。你可以打补丁掩盖症状，但找不到简洁的修复方案，因为周边代码基于已经不成立的假设开发。（可观测特征：你总想加特殊 case 或者标记，而不是直接修正问题。）

不要给规模大但有明确修复方案的Bug提头脑风暴建议——规模大本身不代表是设计问题。

Smart escalation

智能升级处理

If 2-3 hypotheses are exhausted without confirmation, diagnose why:

Pattern	Diagnosis	Next move
Hypotheses point to different subsystems	Architecture/design problem, not a localized bug	Present findings, suggest `/ce:brainstorm`
Evidence contradicts itself	Wrong mental model of the code	Step back, re-read the code path without assumptions
Works locally, fails in CI/prod	Environment problem	Focus on env differences, config, dependencies, timing
Fix works but prediction was wrong	Symptom fix, not root cause	The real cause is still active — keep investigating

Present the diagnosis to the user before proceeding.

如果尝试了2-3个假设都没有得到确认，诊断原因：

模式	诊断	下一步
假设指向不同的子系统	架构/设计问题，不是局部Bug	展示结论，建议用 `/ce:brainstorm`
证据互相矛盾	对代码的心智模型错误	退一步，不带预设重新读代码路径
本地运行正常，CI/生产环境失败	环境问题	重点排查环境差异、配置、依赖、时序问题
修复生效但预测错误	只修复了症状，没解决根因	真正的原因仍然存在——继续调查

继续推进前先把诊断结果展示给用户。

Phase 3: Fix

阶段3：修复

Reminder: one change at a time. If you are changing multiple things, stop.

If the user chose Proof or brainstorm at the end of Phase 2, skip this phase — the skill's job was the diagnosis.

Workspace check: Before editing files, check for uncommitted changes (

git status

). If the user has unstaged work in files that need modification, confirm before editing — do not overwrite in-progress changes.

Test-first:

Write a failing test that captures the bug (or use the existing failing test)
Verify it fails for the right reason — the root cause, not unrelated setup
Implement the minimal fix — address the root cause and nothing else
Verify the test passes
Run the broader test suite for regressions

3 failed fix attempts = smart escalation. Diagnose using the same table from Phase 2. If fixes keep failing, the root cause identification was likely wrong. Return to Phase 2.

Conditional defense-in-depth (trigger: grep for the root-cause pattern found it in other files): Check whether the same gap exists at those locations. Skip when the root cause is a one-off error.

Conditional post-mortem (trigger: the bug was in production, OR the pattern appears in 3+ locations): How was this introduced? What allowed it to survive? If a systemic gap was found: "This pattern appears in N other files. Want to capture it with

/ce:compound

提醒：一次只改一个点。如果你同时改多个内容，立刻停下。

如果用户在阶段2末尾选择了Proof或头脑风暴，跳过这个阶段——本技能的任务已经完成诊断部分。

工作区检查： 编辑文件前，检查未提交的变更（

git status

）。如果用户需要修改的文件里有未暂存的工作，编辑前先确认——不要覆盖用户进行中的变更。

测试优先：

编写能复现Bug的失败测试（或用现有失败的测试）
确认测试失败的原因正确——是根因导致的，不是无关的设置问题
实现最小修复——只解决根因，不改其他内容
确认测试通过
运行更全的测试套件检查回归

3次修复尝试失败 = 智能升级处理。 用阶段2的同一个表格诊断原因。如果修复一直失败，很可能根因识别错了，回到阶段2。

可选深度防御（触发条件：grep根因模式时在其他文件也发现了相同问题）：检查这些位置是否存在相同的漏洞。如果根因是偶发的单个错误可以跳过。

可选事后复盘（触发条件：Bug出现在生产环境，OR 该模式出现在3个以上的文件中）：这个Bug是怎么引入的？为什么没被提前发现？如果发现了系统性漏洞：「这个模式在N个其他文件中也存在，要不要用

/ce:compound

统一处理？」

Phase 4: Close

阶段4：收尾

Structured summary:

undefined

结构化总结：

undefined

Debug Summary

调试总结

Problem: [What was broken] Root Cause: [Full causal chain, with file:line references] Recommended Tests: [Tests to add/modify to prevent recurrence, with specific file and assertion guidance] Fix: [What was changed — or "diagnosis only" if Phase 3 was skipped] Prevention: [Test coverage added; defense-in-depth if applicable] Confidence: [High/Medium/Low]


**Handoff options** (use platform question tool, or present numbered options and wait):
1. Commit the fix (if Phase 3 ran)
2. Document as a learning (`/ce:compound`)
3. Post findings to the issue (if entry came from an issue tracker) — convey: confirmed root cause, verified reproduction steps, relevant code references, and suggested fix direction; keep it concise and useful for whoever picks up the issue next
4. View in Proof (`/proof`) — for easy review and sharing with others
5. Done

问题: [什么功能出了问题] 根本原因: [完整因果链，带文件:行号引用] 建议测试: [需要新增/修改来避免复发的测试，带具体文件和断言指引] 修复内容: [修改了什么——如果跳过阶段3就填「仅诊断」] 预防措施: [新增的测试覆盖；如果适用包含深度防御措施] 置信度: [高/中/低]


**移交选项**（用平台提问工具，或给出编号选项等待用户选择）：
1. 提交修复（如果执行了阶段3）
2. 作为经验文档记录 (`/ce:compound`)
3. 把结论发布到对应问题（如果输入来自问题跟踪器）——包含：确认的根因、验证过的复现步骤、相关代码引用、建议的修复方向；内容简洁，对后续处理这个问题的人有用即可
4. 在Proof中查看 (`/proof`) —— 方便审阅和其他人共享
5. 完成