Systematic Debugging 是一个面向调试场景的分步骤工作流技能，用于处理 bug、错误、异常或崩溃的调查。当出现“不工作”但原因不明、测试失败但原因不明显，或任何语言、框架中出现意外行为需要排查时，都可以使用它。
核心工作流 该技能要求按顺序执行五个阶段，不要在完成隔离和追踪之前跳到修复环节。
阶段 1：复现 在做任何其他事情之前，先建立可靠触发该 bug 的方式。需要阅读完整的错误消息、堆栈跟踪和日志，记录确切的文本、行号和错误码；创建一个能稳定触发问题的最小复现案例；记录导致失败的确切步骤、输入和环境。检查点：能否按需触发该 bug？如果是间歇性的，先收集更多数据再继续。
阶段 2：隔离 缩小失败来源的范围。使用二分查找定位故障组件，通过禁用或桩掉系统的一半来排查；用 git log --oneline -20 检查近期变更，并与最后一个已知良好状态做 git diff；添加有针对性的日志或使用调试器观察关键边界处的状态。资料中给出了使用 git bisect 定位引入 bug 的提交的示例命令：
git bisect start git bisect bad HEAD git bisect good <last-known-good-commit>
Git 会检出中间点，逐个测试并标记 good/bad。检查点：bug 已被追踪到具体的函数、模块或数据流。
阶段 3：追踪根本原因 理解失败为什么发生，而不仅仅是发生在哪里。需要从入口点完整阅读到失败位置的代码路径；检查假设：每个函数期望什么、实际收到什么；反向追踪数据流，找出坏值来自哪里；用证据验证：添加断言或打印语句确认假设。资料中给出了验证传入数据假设的示例：
def process_order(order): assert order.status == "pending", f"Expected pending, got {order.status}" assert order.items, "Order has no items" # ... rest of processing
检查点：从触发到症状的因果链已得到解释，并有日志、断言或调试器输出等证据支持。
阶段 4：在根本原因处修复 实施针对实际原因而非仅针对症状的修复。要修复根本原因，而不是下游影响；保持修复最小化，只改必要之处；避免掩盖底层问题的“创可贴”式修复，例如在崩溃处加 try/except 却不修复崩溃原因。
阶段 5：验证 确认修复有效且未引入回归。运行阶段 1 的复现案例，确认 bug 已消失；运行完整测试套件检查回归；测试与修复相关的边界情况；如果该 bug 缺少测试，补一个本可捕获它的测试。检查点：复现案例通过、测试套件全绿，并且新增了覆盖该 bug 的测试。
应避免的关键反模式 包括：散弹式调试（随机修改碰运气）、修复后祈祷（不理解原因就应用修复）、跳过复现（未确认能触发 bug 就改代码）、只治标（用 try/catch 包裹错误而不修复产生错误的原因）。完整目录见 anti-patterns.md。
相关技能 root-cause-tracing：深度调用栈追踪技术，在阶段 2 之后、bug 位于深层执行链时使用；verification-before-completion：强制验证关卡，在声称修复完成前强化阶段 5。
深入参考 workflow.md 提供带决策树的逐阶段详细说明；examples.md 提供跨语言的调试实例；troubleshooting.md 提供常见调试场景与解决方案；anti-patterns.md 列出应避免的模式及识别方法。