# 异常调试协议

规范路径：`comet-classic/reference/debug-gate.md`

本协议由 build、hotfix、tweak 等会直接修改代码的 comet 子 skill 共享。当运行程序、测试、构建或手动验证时出现崩溃、异常行为、测试失败或构建失败，必须进入异常调试协议。

## 核心规则

例外：已核对失败原因、确实因尚未实现目标行为而失败的 TDD RED 属于正常开发证据，继续 RED-GREEN-REFACTOR，不加载调试技能。环境错误、测试加载失败、无关回归或原因不明的 RED 不属于此例外。

- `build_mode: autonomous` 直接按下述步骤调查、修复并验证，不强制加载外部 Skill；其他策略立即使用 Skill 工具加载 Superpowers `systematic-debugging`
- 在完成根因调查前，不得提出或实施源码修复

## 四阶段流程

1. 先复现并定位根因，读取完整错误、检查近期变更、追踪数据流
2. 若根因指向源码 bug，先补充能复现该崩溃/异常的最小失败测试，再修改源码
3. 修复后运行该失败测试、相关测试和项目构建/验证命令，确认全部通过
4. 测试、源码修复和 tasks.md 的完成记录都保留在当前 change 内；必须在当前 change 中完成修复和验证，不能另外创建一个“写测试用例”的 change 来代替

## 多个检查失败时如何调查和修复

同时出现多个失败时，先检查它们是否可能有相同根因、是否共享状态、是否涉及相同文件，再结合调查成本决定串行还是并发。失败数量不决定调度方式。尚不能确认问题彼此独立时，先做必要调查，不直接并发修改。

- 相关失败、共享状态或修改范围重叠：集中调查与整合，避免重复定位同一根因。
- 已确认问题彼此独立，而且并发节省的时间足以抵消任务分配和结果整合的成本：可以并发调查。autonomous 直接分配范围明确的调查任务；其他策略需要并发方法时，加载 Superpowers `dispatching-parallel-agents`。

向每个调查子代理说明具体失败、错误证据、允许调查的范围，以及需要返回哪些信息。调查子代理只返回根因和证据，**不直接提交修复**。主会话核对结论和实际依赖后，再安排修复。

修复时遵循已选 build_mode、各子代理的文件修改范围，以及 `comet-classic/reference/subagent-dispatch.md`。涉及共享状态或相同修改范围的修复，按顺序实施和整合。autonomous 只有确认任务独立、修改范围互斥且能分别验收时才可并发实施。其他执行方式保持已选方法，不能因为调试就擅自切换策略。根因未明前不得动源码；每项修复仍须在当前 change 中完成测试、审查和验收。