ce-debug

系统地查找根本原因——在提出任何修复建议之前追踪完整的因果链，拒绝症状级别的补丁，在遇到困难时升级。

ce-debug 是调查第一调试技巧。在能够毫无间隙地解释从触发因素到症状的完整因果链之前，它拒绝提出解决方案。对于该链中的不确定链接，它需要预测 - 如果链接正确，则不同代码路径或场景中的某些内容也必须为真。 当预测错误但修复似乎有效时，该技能会对其进行标记：您发现的是症状，而不是原因。

它尺寸合适。琐碎的错误（打字错误、缺少导入、明显的一行修复）在第 0 阶段采取明确的快速路径 - 修复它，留下一行注释，停止。其他任何事情都会流经整个框架，复杂的错误自然会在每个阶段花费更多的时间。该修复是可选的——仅进行诊断是一流的结果。

复合工程构思链是/ce-ideate → /ce-brainstorm → /ce-plan → /ce-work。 ce-debug 是 /ce-work 的 bug 形兄弟 - 当输入是损坏的行为而不是要构建的功能时，此技能将接管。当调查显示该错误并非真正的错误时，它也可能升级为 /ce-brainstorm ；这是一个设计问题。

TL;DR

＃＃ 问题

常见的调试反模式：

• 霰弹枪修复 — 一次更改三件事“看看是否有帮助”；如果有什么办法有效，你不知道为什么
• 症状级补丁 - 更改后错误不再显现，但根本原因仍然存在，并在几周后在其他地方出现
• 错误假设固定 - 假设是正确的，但您正在根据一个不正确的假设（框架的行为方式如此，此函数返回其名称所暗示的内容）来测试它
• “再试一件事”循环 - 连续三个失败的修复意味着诊断是错误的；更加努力会让事情变得更糟
• 修复第一个看起来错误的地方 - 根本原因是不良状态的起源，而不是第一次观察到它的地方

解决方案

ce-debug 将调查作为具有显式门的结构化过程来运行：

• 因果链门 - 在对链进行端到端无间隙解释之前，不建议进行修复
• 对不确定链接的预测 - 如果链接正确，不同代码路径中的某些内容也必须为真
• 假设审核 — 列出您的理解所依赖的“这一定是真的”信念，标记每个已验证或假设的内容
• 一次改变 — 反霰弹枪纪律
• 卡住时智能升级 — 诊断为什么假设已用尽，而不仅仅是更加努力
• 测试优先修复 — 编写失败的测试，验证其失败的正确原因，然后实施；绝不会同时两者兼而有之

是什么让它如此新颖

1. 因果链门——在解释该链之前无法修复

ce-debug 不会提出修复方案，除非它能够毫无间隙地解释从触发因素到症状的完整因果链。 “不知何故X导致Y”是一个差距。修复门是结构性的：有一个明确的相变需要链解释才能通过。

2. 不确定链接的预测 — anti-symptom-fix

对于因果链中的每个不确定链接，该技能都会给出一个预测：如果该链接正确，则不同代码路径或场景中的某些内容也必须为真。 如果预测错误，但修复似乎有效，那么您发现的是症状，而不是原因。 对于明显的链接（缺少导入、清除空取消引用）不需要预测；它们是检验不确定性的工具，而不是每个假设的仪式。

3. 假设审计——捕获正确假设错误假设

在形成假设之前，该技能会枚举您的理解所依赖的“这一定是真的”信念 - 框架在这里以这种方式运行，该函数返回其名称所暗示的内容，配置在运行之前加载，数据库处于测试所暗示的状态。每个都被标记为已验证（您阅读代码、检查状态或运行它）或假设。许多“错误假设”实际上是针对错误假设进行检验的正确假设。

4.卡住时智能升级——诊断，不要再努力

在 2-3 个假设在没有确认的情况下用尽后，技能会诊断您陷入困境的“原因”：

• 假设指向不同的子系统 → 可能的架构问题；建议/ce-brainstorm
• 证据自相矛盾 → 代码的思维模式错误；退后一步，重新阅读，不要做任何假设
• 本地工作，CI/prod 失败 → 环境问题；关注环境、配置、依赖项、时间
• 修复有效但预测错误→症状修复；真正的原因仍然活跃

5. 问题跟踪器集成 — 读取完整线程

当输入引用问题（#123、GitHub URL、线性 URL、Jira 密钥）时，该技能会获取完整的对话，包括所有评论，而不仅仅是原始描述。评论经常包含更新的再现步骤、缩小的范围、之前失败的尝试以及转向不同的可疑根本原因。将开篇文章视为整体往往会使调查走向错误的方向。

6. 测试优先修复原则

如果您选择修复（而不是“仅诊断”），该技能会编写一个失败的测试来捕获错误，验证其失败的正确原因（根本原因，而不是不相关的设置），实现最小修复，并验证测试是否通过。明确不允许在同一步骤中进行测试和修复的快捷方式。

7.有条件纵深防御

当根本原因模式出现在 3 个以上的其他文件中，或者该错误在生产中可能是灾难性的时，该技能会考虑四个防御层（条目验证、不变检查、环境防护、诊断面包屑）并应用适合的内容。对于没有实际复发的一次性错误，将跳过深度防御。

8. 当 bug 暴露设计问题时集思广益升级

具体信号会触发 /ce-brainstorm 建议而不是修复：根本原因是错误的责任或接口；要求错误或不完整；每个修复都是一个解决方法。尺寸本身并不会使某些东西成为设计问题——明确修复但大的错误仍然是错误。

简单示例

您粘贴堆栈跟踪或 GitHub 问题 URL。该技能获取完整的问题线程（包括带有最新再现详细信息的注释），在本地再现错误，并验证环境健全性（正确的分支、安装的依赖项、存在的环境变量）。

它跟踪从错误返回上游的代码路径，询问“这个值来自哪里？”直到到达有效状态首次变为无效的点。它执行假设审核并将一个信念标记为未经验证。

它形成两个假设，按可能性排名。第一个是可以直接测试的；第二个有一个不确定的链接，因此它生成一个预测：如果这个链接是正确的，那么在不同条件下调用同一函数的不同代码路径也应该失败。它测试了预测。

预测成立。该技能通过 file:line 引用、建议的修复以及应添加的特定测试（带有断言指导）来呈现根本原因。它询问：立即修复它，仅进行诊断，还是重新考虑设计？

您选择“立即修复”。它创建一个功能分支，编写失败的测试，验证其失败的正确原因，实现最小修复，运行测试，然后移交给 /ce-commit-push-pr。

何时去实现它

在以下情况下使用 ce-debug：

• 测试失败，您需要知道原因
• 您有错误消息、堆栈跟踪或意外行为
• 出现了回归，你需要找到它何时崩溃
• 您有 GitHub、Linear 或 Jira 问题参考
• 经过几次失败的修复尝试后，您陷入了一个问题
• 您怀疑错误表面比一种症状更广泛（纵深防御领域）

在以下情况下跳过 ce-debug：

• 您已经知道根本原因，并且修复方法很明显 - 只需修复它（或使用 /ce-work 进行小更改）
• “bug”实际上是变相的功能决定 → /ce-brainstorm
• 这项工作是实施新的东西，而不是调查损坏的东西 → /ce-work

用作工作流程的一部分

ce-debug 通过三种方式与链的其余部分互锁：

• 从 /ce-plan 调用 — 当规划提示呈 bug 状时（错误消息，“修复 X 处的 bug”，回归），ce-plan 在进行结构规划之前将 ce-debug 表面为路由选项
• 升级到 /ce-brainstorm - 当调查发现设计问题而不是逻辑错误时，该技能建议在实施之前重新考虑
• 移交给 /ce-commit-push-pr — 在技能创建的分支上成功修复后，该技能默认为提交和 PR，而无需进一步提示（如果您的存储库的 AGENTS.md 另有说明，则使用显式覆盖路径）

PR 打开后，该技能可以选择提供 /ce-compound 来捕获学习内容 - 但前提是 bug 可概括（3+ 重复出现，关于共享依赖项的错误假设）。本地化的机械修复会默默地跳过，以避免一次性条目使 docs/solutions/ 混乱。

使用独立版

ce-debug 是大多数错误工作的独立入口点：

• 测试失败 — /ce-debug spec/models/notification_subscription_spec.rb
• 错误消息粘贴 — /ce-debug 后跟堆栈跟踪
• GitHub 问题 — /ce-debug #1234 或 /ce-debug https://github.com/.../issues/1234
• 线性票 — /ce-debug ABC-456 或粘贴 URL
• 卡在某物上 — /ce-debug "why is X returning undefined when Y"

当您只需要诊断（您将自己处理修复）时，请在第 2 阶段交接时选择“仅诊断 - 我将从这里获取”。摘要仍然产生；无论如何，测试建议都是诊断的一部分。

＃＃ 参考

＃＃ 常问问题

为什么要在修复之前进行调查？ 与明确因果链无关的修复通常只能解决症状而不是原因。该错误不再显现，但真正的问题仍然存在，并在几周后在其他地方出现。因果链门是针对这种情况的结构性防御。

假设和预测有什么区别？ 一个假设说“我认为这就是原因”。预测说“如果我的假设是正确的，那么这件事也一定是真的。”预测根据独立证据来检验假设——如果预测是错误的，但修复有效，那么你就发现了一种症状。

技能什么时候应该建议/ce-brainstorm？ 仅当错误无法在当前设计中正确修复时 - 错误的责任、错误的接口、需求差距或每个修复都是一种解决方法。尺寸本身并不构成设计问题。

如果我只想修复它而不需要所有这些过程怎么办？ 跳过技能 - 直接进入 /ce-work 或直接编辑文件。 ce-debug 适用于根本原因不明显或修复未能坚持的情况。

它适用于非软件错误吗？ 事实并非如此——该技能需要代码、测试和跟踪器。调查学科（因果链、预测、假设审计）是概括性的，但技能的机制（测试优先修复、深度防御、公关移交）是软件形式的。

另请参阅

• ce-plan — 当您开始规划时在此处路由 bug 形状的提示
• ce-brainstorm — 当错误揭示设计问题时的升级目标
• ce-work — 功能工作的兄弟技能；当输入不是 bug 形状时使用此选项
• ce-commit-push-pr — 处理修复后的最终提交 + PR
• ce-compound — 当错误可泛化时捕获可重用的学习