用途
debug-systematic 是一个系统化调试技能，适用于用户要求调试问题、调查缺陷、排查故障或查找根因的场景。它通过结构化的四阶段工作流，帮助开发者系统性地找到并修复缺陷，避免“散弹式调试”（随机改动代码直到问题看似消失）以及只修复表面症状而忽略真正根因的做法。
主要能力
该技能围绕四个阶段展开：
阶段一：复现（Reproduce） 在修复任何东西之前，先确认缺陷存在并记录精确条件。需要从报告和对话上下文中提取：预期行为、实际行为、复现步骤、发生环境（浏览器、操作系统、Node 版本等）以及复现的一致性（总是、间歇性、仅在高负载下）。同时读取项目上下文，检查 .chalk/docs/engineering/ 中的架构文档、已知问题或调试指南、测试基础设施。尝试触发缺陷：若已有测试覆盖该场景，检查其通过或失败；若无测试覆盖，编写一个能演示缺陷的失败测试（该测试将成为回归测试）。记录精确复现步骤、错误信息或错误输出、预期正确行为以及是否编写了失败测试。退出标准：能可靠触发缺陷，或已记录间歇性条件，并拥有失败测试或手动复现流程。
阶段二：隔离（Isolate） 将问题空间缩小到尽可能小的代码区域。根据错误或行为识别子系统：读取堆栈跟踪以定位失败函数和调用链；若无堆栈跟踪，则从输入追踪数据流到错误输出出现的位置；使用 Grep 查找相关代码路径。通过二分查找系统性地缩小范围：按时间使用 git log 和 git bisect 找到引入缺陷的提交；按代码路径在中间点添加日志或断言；按数据找出触发缺陷的最小输入；按组件检查各层边界（API -> Service -> DB）。缩小到具体函数后，完整阅读函数及其调用者和被调用者、相关测试、近期变更以及注释中记录的边界情况。退出标准：知道缺陷发生的具体函数，能指出涉及的精确代码行。
阶段三：根因分析（Root-cause） 区分症状与真正原因，应用“5 个为什么”。从症状开始反复问“为什么”，通常 3-5 次迭代即可到达根因，当到达可以修复的层面时停止。验证是否为根因而非症状：修复后缺陷会永久消失还是会在不同条件下重现？这是该模式唯一存在的地方还是别处也有同样错误？代码曾经正常工作过吗？如果正常过，发生了什么变化？使用 Grep 搜索导致缺陷的相同编码模式、可能有相同问题的类似函数以及同一底层函数的其他调用者，并记录发现的额外实例。退出标准：能清楚解释根因（不仅是“这行错了”，而是为什么错），并已检查别处是否有相同模式。
阶段四：验证（Verify） 修复缺陷并确认修复正确且完整。修复根因而非症状：若根因在函数 A 但症状出现在函数 B，则修复函数 A；若别处存在相同模式，修复所有实例（或创建共享抽象防止该模式）；保持修复最小化，不在同一变更中重构无关代码。用阶段一的复现测试验证：运行复现缺陷的特定测试，若仍失败则修复不完整，回到阶段三；若通过则运行完整测试套件检查回归。编写回归测试：测试必须在无修复时失败、有修复时通过，应测试根因而非仅症状，并包含调试中发现的边界情况。检查附带损害：运行完整测试套件，若修复改变了共享函数则检查所有调用者，若改变了数据处理则用不同数据形态验证。最后记录调试会话：缺陷是什么（症状）、根因是什么、修复是什么、发现并修复了哪些同类模式、添加了什么回归测试。
使用方式
该技能以工作流指南的形式提供，包含调试策略决策树：有错误信息或堆栈跟踪时，自底向上阅读堆栈跟踪，识别自己代码中的第一帧，阅读该函数及其输入，判断错误在自身代码还是库调用方式；无错误信息（静默错误行为）时，可添加日志追踪数据流或使用调试器断点，判断是否曾经正常工作过（是则用 git bisect 找破坏性提交，否则是设计问题而非回归），判断是否间歇性（是则检查竞态条件、时序假设、数据假设）。
技能还提供常见根因分类表，涵盖 off-by-one、空值/未定义访问、竞态条件、类型强制转换、状态过期、缺少错误处理、环境差异、数据假设等类别，每类列出症状和调查方法。
git bisect 快速参考提供命令示例：
# 开始 bisect
git bisect start
# 将当前（损坏）提交标记为 bad
git bisect bad
# 将已知良好提交（如上次发布标签）标记为 good
git bisect good v1.2.0
# Git 检出中间提交。测试它。
# 如果此提交存在缺陷：
git bisect bad
# 如果此提交不存在缺陷：
git bisect good
# 重复直到 git 识别出第一个坏提交
# 完成后：
git bisect reset
自动化 bisect 配合测试脚本：
git bisect start HEAD v1.2.0
git bisect run npm test -- --filter="test-that-reproduces-bug"
适用场景
适用于需要系统性定位和修复软件缺陷的开发场景，包括：有明确错误信息或堆栈跟踪的缺陷、静默错误行为、间歇性故障、环境特定问题、数据相关缺陷，以及需要查找回归引入提交的情况。
限制
该技能为调试方法论指南，不提供自动化调试工具或运行时环境。其效果取决于开发者是否严格遵循四个阶段。技能中提到的 .chalk/docs/engineering/ 路径和 $ARGUMENTS 变量属于特定项目约定，在其他项目中可能不适用。技能未提供具体的编程语言或框架绑定，需开发者自行适配。