diagnosing-bugs

技能简介

diagnosing-bugs 是一套针对疑难 bug 与性能回退（performance regression）的系统化排查方法论。它把“调试”拆成明确的阶段流程，核心观点是：先构建一个能稳定复现 bug 的反馈循环，再谈修复——没有可复现的信号，一切猜测都是浪费。

使用场景

• 用户报告“某些功能坏了 / 报错 / 失败 / 变慢”
• 用户明确要求“diagnose”或“debug this”
• 处理难以复现的偶发 bug（flaky bug）或性能回退
• 定位跨模块、跨版本行为差异导致的回归问题
• 需要系统化排查而非凭感觉猜根因的复杂问题

使用方法

安装与触发

本技能为 Agent 技能（Skill），适用于支持 SKILL.md 的 Agent 环境。将本技能按其 name: diagnosing-bugs 安装配置后，当用户说 “diagnose” / “debug this”，或报告某些东西损坏 / 报错 / 失败 / 缓慢时，Agent 即会按此流程执行。

诊断流程概览

Phase 1：构建反馈循环（核心）

没有关键方法，只有一条铁律：先想办法让 bug 稳定暴露。按优先级尝试以下手段构建一个紧密（tight）的 pass/fail 信号：

1. 写一个能复现 bug 的失败测试（单元 / 集成 / e2e）
2. 用 curl 或 HTTP 脚本打运行中的 dev server
3. 用 CLI 命令 + fixture 输入，对比 stdout 与已知正确快照
4. 用 Playwright / Puppeteer 无头浏览器驱动 UI
5. 重放真实抓包记录 / 请求日志
6. 搭一个最小的一次性 harness，单函数调用触发 bug 路径
7. 对“偶尔输出错误”类 bug，用 property / fuzz 循环跑大量随机输入
8. 用 git bisect run 自动化定位引入 bug 的提交
9. 差分对比旧版本遍历同一输入的输出
10. 最后手段：用 scripts/hitl-loop.template.sh 驱动人类手动点击

Phase 2：复现并最小化

得到红色信号后，确认复现的是用户描述的现象（不是另一个无关 bug），然后逐步删除非必需的输入/配置/步骤，直到最小复现集——去掉任一元素就不复现。

Phase 3：生成假设

先列出 3-5 个排名假设，再逐一验证。避免只凭第一个想法就锚定方向。

注意事项

• 先脱敏再展示：所有命令输出和抓取结果必须先替换密钥、token 等敏感信息为 <REDACTED>，引用抓包内容时只摘录关键行。
• 没有反馈循环就不要猜：如果尝试了各种方法仍无法构建循环，明确告诉用户，并请求用户提供可复现环境、脱敏后的抓包文件（HAR / 日志 / 录屏），或授权加临时生产观测代码——而不是硬着头皮凭空猜。
• 每阶段完成后才算完成：Phase 1 需要有“已实际运行过一次且能稳定变红”的循环；Phase 2 要完成最小化复现。跳过阶段必须给出明确理由。