用途:debugkit 面向“东西坏了但没人知道为什么”的场景,输入是症状而非计划或 diff,目标是把症状转化为可行动的原因。触发语包括“debug this”“why is this failing”“find the root cause”“this test is flaky”“it broke after the upgrade”等。
主要能力:单一流程,无模式分支。先要求补齐三项事实:预期、实际、发生位置;若“预期”其实是从未实现的行为,则判定为功能请求而非缺陷。随后依次执行复现、隔离、假设、证明、报告五步。复现要求一条任何人可运行、连续三次失败的命令;隔离阶段强制确定性并沿提交、输入、配置、依赖版本等轴二分;假设阶段先写下带可证伪预测的候选原因,优先测试能排除最多候选的探针;证明阶段采用开关测试:原因存在则失败、移除则通过、恢复则再次失败,三步缺一不可。
使用方式:通过 /debugkit 或自然语言触发。诊断期间可自由修改仓库做探针,但所有改动都会回滚,唯一保留的是失败复现(红测试)和文字描述的修复方案。提交二分须在临时 worktree 中进行:git worktree add --detach <scratch-path> <known-good-ref>,结束后 git worktree remove <scratch-path>。回滚探针使用 patch -R -s <path> < <ledger>/probe-NN/<name>.patch,禁止使用 git checkout -- <path>。
适用场景:生产环境缺陷、升级后回归、间歇性失败、性能退化(“以前很快”)等已有可对比变化的问题。不适用于代码审查、测试计划、原型验证、功能请求和纯优化(“让它更快”)。
限制:三种终态为已证明原因、已复现未解释、插桩计划;未经验证的理论即使正确也算失败。无法复现时不得静默降级,须明确说明并转入插桩计划。统计形式的开关测试要求 N 至少 20、移除原因组零失败、存在与恢复组各至少 5 次失败,且 N 须事先声明。探针账本需在首次探针前建立基线,快照不覆盖未跟踪文件,需单独复制。回滚冲突时停止并报告,不得强制恢复。