系统化调试

针对本地 Bug、测试/构建失败、性能异常、集成问题和非预期行为排查根因。以下步骤按证据缺口选择，不是固定流水线；当前证据已确认根因时直接进入最小修复与复验。

项目有 .aitasks/ 时，先从当前可发现的 Skill 中定位可选的 aitasks-maintenance，存在才读取其目录内的 references/query.md，不加载维护流程或假定相邻安装。未安装或不支持只读查询时，用本 Skill 自带的只读查询脚本：python3 -B "<skill-dir>/scripts/query_aitasks.py" --project-root "<project-root>" context --query "模块 符号 错误码"，按返回 ID 用 get-record --kind lesson --id …（todo 用 --kind todo）取必要正文，由脚本处理状态与围栏边界。Python 不可用时只取少量标题及所属元数据定位线索，无法核实的正文与适用性标为未验证，依据当前代码取证，不临时编写经验解析器。经验须与当前失败证据核对。

流程

1. 读取失败证据：先收集相关完整异常链和必要日志上下文、版本、输入与环境；证据不足再扩大范围，不默认读取全部历史日志。
2. 稳定复现：用现有测试或最小脚本构造可重复场景；不能稳定复现时记录条件、频率和已尝试方式。
3. 比较差异：检查近期提交、配置、依赖、系统、资源和外部服务，优先核对与问题时间吻合的变化。
4. 跟踪数据流：从入口沿调用链核对实际实现；已知目标文件和局部关系直接检索、读取，尚不明确的结构或跨模块关系在已接入 CodeGraph 时优先用图谱定位，再核对实际文件。记录关键输入输出，定位第一个偏离预期的环节。
5. 提出假设：可保留多个有证据支持的候选原因，分别说明预期现象；每次实验只检验一个关键假设，不把尚未排除的候选提前当作唯一根因。
6. 最小实验：选择能区分候选原因的最小实验，控制关键变量并记录结果及排除理由；没有新证据时不换命令重复同一实验，先指出缺失的输入、观测或访问条件，重估调查方向。缺口无法补齐时说明限制，停止无效循环。
7. 回归保护：复用已有失败测试，缺少有效保护时再添加修复前失败、修复后通过的测试；无法稳定自动化或回归价值低时记录原因与替代验证。预期失败属于验证证据。
8. 最小修复与复验：只改根因范围，选择覆盖原问题与受影响风险的验证，保持既有输入输出边界。定向运行与完整发现覆盖相同测试时只执行一种；需要扩大覆盖范围，或支撑结论的代码、输入、依赖、配置、环境变化时再补充验证，不因进入收尾重跑等价检查。

边界

只读诊断不写测试或修改文件，输出根因证据和建议后停止；用户已要求修复时继续授权内的最小修复。复用已完成的复现、风格基线和验证，仅补剩余缺口。未知共享行为或契约影响才需要额外分析；由入口调度时返回缺口，不递归加载专项。独立使用无需加载其他 Skill，无法确认的行为标记未验证。