systematic-debugging v1.0.2A

Immutable. This exact content is served forever at /api/v1/blob/c7717dfb4bc234ff.

---
name: systematic-debugging
description: 系统化诊断和修复 Bug、测试或构建失败、异常行为、集成故障与性能回归。先建立可判定的反馈信号、追踪根因并逐一验证可证伪假设；仅在现有错误、测试、日志、diff、debugger 或 profiler 无法区分假设，且临时写入已获授权时使用定向 HTTP 插桩。
metadata:
  author: "devkeel"
  version: "1.0.2"
---

# Systematic Debugging

以证据闭环解决问题。插桩是遇到运行时观测缺口后的升级手段，不是默认入口。

## 权限边界

- 用户只要求分析、诊断或解释时保持只读；可以复现、检查和运行非破坏性诊断，但不得修复或向
  源码写入临时探针。
- 用户明确要求修复时，只修改已授权目标。临时插桩同样是源码写入，必须处于该授权范围内。
- 无法从当前环境复现时，列出已尝试的方法，并请求最小必要的日志、trace、请求、录屏或环境访问；
  不用猜测代替证据。

## 调试状态机

按顺序推进，但让简单问题走快速路径：

1. **定义症状**：写清输入、期望、实际行为和首次已知异常位置。
2. **建立反馈信号**：找到一条能命中真实路径、对该症状判红/判绿、可由 Agent 重复运行的命令或
   现场证据。已有失败测试或确定性错误就是现成信号，不另造 harness。
3. **复现并最小化**：确认是用户报告的同一个问题；逐项减少输入、配置、调用方和环境差异。
4. **追踪根因**：完整读取错误与 stack，检查近期变化、正常样例、依赖和数据来源，向上追到错误
   状态首次产生的位置。
5. **形成假设**：生成少量有排序、可证伪的候选；每个候选写出若成立应观察到什么。一次只测试
   一个假设和一个变量。
6. **修复与验证**：只有根因得到证据支持且用户已授权修复时，才在正确接缝添加回归测试并实施
   单一修复；重新运行最小复现、原始反馈信号和邻近测试。

简单问题可以快速完成这些步骤，但不能省略症状、证据、根因和验证。需要更完整的反馈循环、
最小化、数据回溯、性能分支或失败升级策略时，读取 `references/diagnosis.md`。

## 插桩升级门禁

只有以下条件全部满足时才读取 `references/instrumentation.md` 并启动 collector：

1. 已捕获精确症状，且有可重复反馈信号或可靠现场材料；
2. 剩余不确定性来自不可见的运行时状态、时序或跨边界数据流；
3. stack、测试缩小、diff/bisect、现有日志、debugger/REPL 或 profiler 仍不能区分假设；
4. 每个计划探针对应一个明确预测，并且临时代码写入已获授权。

禁止“记录一切再搜索”。性能回归默认使用基线、profiler、query plan 或 bisect；只有需要验证某个
具体运行时预测时才插桩。

## 停止与回退

- 一个假设被否定后记录新证据，回到根因追踪，不在失败改动上叠加下一次试修。
- 连续三次修复尝试失败，停止尝试第四次，检查共享状态、耦合和测试接缝是否暴露架构问题，并让
  用户决定是否扩大到架构调整。
- 插桩改变了竞态、复现率或控制流时，撤销该探针并选择更低扰动的观测点。
- 无正确回归测试接缝时明确记录，不写一个无法覆盖真实触发链的浅层测试制造假信心。

## 完成条件

诊断完成时报告：反馈信号、关键证据、已排除假设、根因与置信边界。

修复完成还必须同时满足：

- 原始反馈信号已转绿，且用户报告的症状不再出现；
- 回归测试通过，或已说明不存在正确测试接缝；
- 邻近验证通过，没有把症状转移到其他路径；
- 若使用插桩，指定 session 的探针、helper、manifest 和 collector 已清理并通过残留检查。

进度输出保持证据优先：`症状/反馈信号 → 假设与预测 → 证据 → 根因 → 修复与验证 → 清理`。