Diagnosing Bugs 是一个用于处理难以定位的缺陷和性能回归的诊断流程型技能。它的核心主张是：拿到一个能对该缺陷变红（失败）的紧凑 pass/fail 信号，比盯着代码找原因更有效；后续的二分、假设检验和插桩都只是在这个信号上做消耗。因此，除非有明确理由，否则不应跳过任何一个阶段。
【用途】 当用户明确表示“诊断”“调试这个”，或报告某功能损坏、抛错、失败、变慢时使用。它面向“硬骨头”式的缺陷，强调纪律性流程，而非凭直觉猜测。
【前置动作】 在浏览代码库时，读取 CONTEXT.md（若存在）以建立对相关模块的清晰心智模型，并查看所触及区域的 ADR。
【脱敏要求】 该技能会要求展示命令、输出和捕获的产物，因此必须先对每项密钥脱敏，用 <REDACTED> 替换。应基于环境变量构建回路，让凭据留在环境中，而不是出现在展示内容里。捕获的产物若带有认证头，只引用携带信号的行。如果脱敏后输出不足以诊断缺陷，应当说明并询问用户。
【阶段一：构建反馈回路】 这是整个技能的关键，其余都是机械操作。构建回路的方式大致按顺序包括：能触及缺陷的失败测试（单元、集成、e2e）；针对运行中的开发服务器写 curl/HTTP 脚本；带固定输入的 CLI 调用并与已知良好的快照做 diff；驱动 UI 并对 DOM/console/network 做断言的 headless 浏览器脚本（Playwright/Puppeteer）；重放已捕获的 trace，把真实网络请求/载荷/事件日志存盘后隔离重放；一次性最小化 harness，只启动系统的一个子集来执行缺陷代码路径；属性/模糊测试回路，用大量随机输入寻找失败模式；二分 harness，在已知两个状态之间自动“在状态 X 启动—检查—重复”，以便用 git bisect run；差分回路，把同一输入跑过旧版与新版（或两种配置）并 diff 输出；HITL bash 脚本（最后手段），用 scripts/hitl-loop.template.sh 驱动人工点击，保持回路结构化。回路建成后还要收紧它：能否更快（缓存初始化、跳过无关初始化、缩小测试范围）；能否让信号更锐利（断言具体症状而非“没崩”）；能否更确定（固定时间、设定 RNG 种子、隔离文件系统、冻结网络）。非确定性缺陷的目标不是干净复现，而是提高复现率：循环触发 100 次、并行化、加压、收窄时间窗口、注入 sleep。阶段一完成的判据是：回路紧凑、能在该缺陷上变红、确定、快速（秒级而非分钟级）、可无人运行（人工介入仅经脚本）。如果最终无法构建回路，应停下来明确说明，列出已尝试的内容，并向用户请求：(a) 能复现的环境访问权限，(b) 脱敏后的捕获产物（HAR、日志、core dump、带时间戳的录屏），或 (c) 添加临时生产插桩的许可；在没有回路前不要进入假设阶段。
【阶段二：复现与最小化】 运行回路，观察其变红。确认：回路产生的是用户所描述的症状，不是旁边恰好发生的另一种失败；失败可跨多次运行复现（非确定性缺陷需足够高的复现率）；已捕获确切症状，供后续阶段验证修复。变红后缩小复现范围到仍能变红的最小场景：逐一切掉输入、调用方、配置、数据和步骤，每次切完重跑回路，只保留对失败起承载作用的元素。完成后每个剩余元素都是承载元素——去掉任何一个回路就变绿。未复现并最小化前不要继续。
【阶段三：假设】 在测试任何假设之前，先提出 3–5 个排序过的假设，避免锚定在第一个看似合理的想法上。每个假设必须可证伪，并写出其预测，格式为“如果 X 是原因，那么 Y 会使缺陷消失 / Z 会使它更糟”。若说不出预测，就是直觉，丢弃或锐化。在测试前把排序列表展示给用户，他们常能用领域知识立刻重排，或告知已排除的假设；这是低成本的检查点，但不阻塞——用户不在时按自己的排序继续。
【阶段四：插桩】 每个探针都要对应阶段三的某个具体预测，一次只改一个变量。工具偏好：环境支持时用调试器/REPL 检查，一个断点胜过十条日志；在能区分假设的边界打定向日志；绝不“全都打日志再 grep”。每条调试日志加唯一前缀（如 [DEBUG-a4f2]），便于最终用一次 grep 清理——有标记的日志会被清掉，没标记的会存活。性能分支：对性能回归，日志通常不对，应先在计时 harness、performance.now()、profiler 或查询计划上建立基线测量，再做二分；先测量，后修复。
【阶段五：修复与回归测试】 仅当存在正确的接缝时，才在修复前写回归测试。所谓正确接缝，是指测试能按缺陷在调用点的真实发生方式去执行它；如果唯一可用的接缝太浅（缺陷需要多个调用方却只做单调用方测试，或单元测试复现不了触发缺陷的链路），那里的回归测试只会带来虚假信心。若不存在正确接缝，这本身就是发现，应记录下来——代码库架构在阻碍缺陷被锁定，并在下一阶段标出。若有正确接缝：把最小化复现变成该接缝处的失败测试，看它失败，应用修复，看它通过，再针对原始的（未最小化的）场景重跑阶段一的反馈回路。
【阶段六：清理】 声明完成前必须做到：原始复现不再复现（重跑阶段一回回路）；回归测试通过（或记录接缝缺失）；所有 [DEBUG-...] 插桩已移除（grep 前缀）；一次性原型已删除（或移到明确的调试位置）；把最终正确的假设写进 commit/PR 消息，让下一个调试者能从中学习。
【适用场景与限制】 适用于难以定位的缺陷与性能回归，要求使用者遵循分阶段纪律并在阶段间设置完成判据。限制在于：必须能构建反馈回路，否则流程会停并要求获取环境、捕获产物或临时插桩许可；展示任何命令与产物前必须脱敏；非确定性缺陷只能追求足够高的复现率而非干净复现；若缺少正确的回归测试接缝，则不强行补测试而是记录为架构发现。关于作者、许可、安装方式、依赖与运行环境等具体信息暂未提供。