用途
该技能适用于需要把一个具体失败转化为有边界、可重复的诊断循环的场景。它强调五步核心循环：用可测试的方式定义失败行为、构建或确认最经济可靠的复现步骤、隔离最窄的失败边界、针对每个假设只运行一次有区分度的检查、在相同条件下验证修复。
何时使用
- 某条命令、测试、请求或 UI 流程失败，用户需要根因排查流程时；
- 缺陷可复现或接近可复现，需要在修补前先缩小范围时；
- 回归问题存在可能的变更窗口或最后已知正常状态时；
- 偶发失败需要重复运行证据、隔离，并对一个具体案例进行稳定化时；
- 仅在 CI/预发/生产出现的行为已有足够证据去比较环境或配置差异时；
- 用户询问如何复现、隔离、二分、确认或验证缺陷修复时。
何时不使用
- 用户只有日志或堆栈，却仍需定位第一个可操作的失败 → 使用 log-analysis；
- 真正的任务是测试程序设计、偶发失败策略或覆盖率规划 → 使用 testing-strategies；
- 任务是审查 diff 或 PR 的正确性、风险或缺失证据 → 使用 code-review；
- 主要工作是遥测铺开、仪表盘或可观测性平台设计 → 使用 monitoring-observability；
- 主要工作是瓶颈测量与优化取舍 → 使用 performance-optimization。
使用方式（工作流步骤）
第 1 步：冻结失败定义。 用可重新测试的形式写下失败，记录预期行为、实际行为、确切触发条件/输入/状态、环境（本地/CI/预发/生产/浏览器/移动端/运行时）、确定性（确定性/偶发/未知），以及若可能为回归时的最后已知正常状态。报告中应包含预期、实际、触发条件、环境和置信度（高/中/低）。如果报告仍只是“某处失败了”并附带大量日志、没有缩小的症状，应先转向 log-analysis。
第 2 步：选择正确的首个证据来源。 选择能证伪或确认下一个假设的最经济路径：已知失败的命令/测试/请求/UI 流程 → 直接复现；有最后已知正常状态的回归 → 比较近期变更并考虑 git bisect；偶发或间歇性 → 先用重复运行测量频率；仅 CI/预发/生产出现 → 先比较环境/配置/运行时事实，而不是猜测代码；以工件为线索 → 检查第一个有意义的日志/追踪/截图，再缩小到一个可疑边界；仅性能抱怨 → 除非仍有具体破损行为需要诊断，否则转向 performance-optimization。
第 3 步：构建最小可靠复现。 优先选择仍然失败的最廉价复现方式，常见形式包括：一条 CLI 命令、一次 HTTP 请求或 API 调用、一段带确切步骤的 UI 流程、一个失败测试或夹具、一种存档/种子/载荷/配置组合、一个用于回归排查的提交范围。可用策略包括减少无关设置、尽可能冻结时间/随机性/网络、记录有差异的确切环境/配置值、让重复运行循环聚焦于单个可疑点。
第 4 步：在提出修复前隔离边界。 先从多个角度缩小问题：边界（UI vs API vs DB vs worker vs 配置 vs 依赖 vs 资产/运行时）、输入（单个载荷、记录、种子、场景或夹具）、历史（好坏之间发生了什么变更）、环境（本地 vs CI vs 预发 vs 生产）、时序（顺序、重试、缓存、时钟、异步等待、共享状态）。高价值问题包括：现在能否指名一个文件/模块/配置分支作为主要可疑点？失败与数据形状、状态转换、配置漂移、依赖行为还是代码路径有关？当前瓶颈仍是诊断，还是任务已转向审查/测试策略/优化工作？
第 5 步：每个假设运行一次有区分度的检查。 不要一次修补五处。对每个假设：说明它为何能解释该失败；先运行一次只读或可回滚的检查；记录结果；依据证据保留或否定该假设。好的首次检查包括：在缩小后的边界检查请求/载荷/配置、比较一个好状态和一个坏状态、只重跑一个目标测试而非整个套件、对比可疑提交范围、仅在缩小后的边界添加临时插桩。
第 6 步：使用正确的模式包。 一旦案例类型明确，按引用文档 references/mode-selection-and-fast-checks.md 中匹配的包执行：回归调试、偶发失败调试、环境/配置不匹配调试、日志/追踪/截图分诊后的工件主导调试、运行时/浏览器/游戏循环调试。
第 7 步：修复原因并证明。 好的调试结果应显示原因已被处理，而不只是症状被掩盖。验证清单：复现现在通过；附近的边界情况仍表现正确；在可行时存在回归防护；解释与观察到的失败一致；修复范围小于初始搜索空间。
第 8 步：证据不足时如实升级。 如果复现或隔离仍然失败：说明置信度低、只请求最小的缺失工件、避免假装已知根因、倾向再做一次有区分度的检查而非推测性修补。
输出格式
始终返回简洁的调试简报或调试计划，结构包括：失败定义（预期、实际、复现步骤、置信度）、隔离结果（缩小的边界、近期变更/环境差异/工件线索）、假设与检查（逐条列出假设、检查、结果）、可能根因（1-3 句基于证据）、修复方向、验证（复现重跑、回归防护）、交接（留在 debugging，或转至 diagnosing-bugs、log-analysis、testing-strategies、code-review、performance-optimization）。
示例
- 重构后的回归：保存不含头像上传的资料会清除已有头像，重构前正常。应在一个可复现的表单提交中定义预期与实际行为，比较重构前后的更新路径，检查缺失字段与显式 null 是否被同等对待，并用聚焦的回归测试验证。
- 偶发 CI 失败：结账测试本地通过、CI 约八次失败一次。应标记为偶发而非确定性，运行重复循环并比较时序/共享状态/环境差异，先只检查失败测试及附近夹具，若工作扩展到套件级偶发策略再转向 testing-strategies。
- 仅预发出现且带工件线索：作业只在预发失败，已有首个失败请求载荷和配置差异。应视为环境/配置不匹配调试，在修补代码前比较预发与本地/运行时事实，缩小到改变行为的某个开关/版本/密钥分支，并在修正配置下用同一载荷验证。
- 仅有症状的日志转储：500 行重试与堆栈。应先转向 log-analysis，说明首个可操作失败仍需缩小，不要假装此时能启动根因循环。
最佳实践
先复现再修补；先使用最廉价的证据来源（直接复现、重复运行、环境差异或工件线索）；显式选择模式，因为回归、偶发、环境/配置、工件主导和运行时案例需要不同的首次检查；把症状分诊与诊断分开，日志帮助开始而非结束；一次只改一处，调试是实验循环；以验证收尾，每个结果都应说明原因是如何被确认的。
限制
该技能的具体依赖文档、仓库结构、安装命令、是否收费、价格、平台支持或效果数据暂未提供。