该技能用于处理较难定位的 Bug 和性能回归，核心是一套分阶段的诊断纪律：除非有明确理由，否则不跳过阶段。
用途与适用场景：当用户说“诊断”“调试这个”，或报告某处损坏、抛出异常、失败、变慢时使用。开始探索代码库时，建议先阅读 GLOSSARY.md（或旧版 CONTEXT.md，如存在）以建立相关模块的心智模型，并检查所触及区域的 ADR。
敏感信息处理：该技能会要求展示命令、输出和捕获的产物。展示前必须脱敏，把每个秘密替换为 <REDACTED>。应基于环境变量构建回路，让凭据留在环境中而非展示内容里；捕获产物可能带认证头，只引用承载信号的行。若脱敏后的输出不足以诊断，应明确说明并向用户求助。
阶段 1：构建反馈回路。这是技能的核心，其余步骤都是机械性的。需要为 Bug 建立紧凑的通过/失败信号，使其在该 Bug 上变红。构建方式按大致顺序包括：在能触及 Bug 的接缝处写失败测试（单元、功能、端到端，如 Laravel 仓库中的 Pest 测试）；对运行中的开发服务器写 Curl/HTTP 脚本；用固定输入调用 CLI 并对比 stdout 与已知良好快照；无头浏览器脚本（Pest 浏览器测试、Playwright、Puppeteer）驱动 UI 并对 DOM/控制台/网络断言；回放捕获的 trace；搭建一次性最小测试台；属性/模糊测试循环；二分查找测试台；差分回路（旧版本 vs 新版本或两种配置）；最后手段是 HITL bash 脚本，用 scripts/hitl-loop.template.sh 驱动人工点击并捕获输出。回路建立后应继续收紧：更快、信号更锐利、更确定性。对非确定性 Bug，目标不是干净复现而是更高复现率，可通过循环触发 100 次、并行、加压、缩小时间窗口、注入休眠等方式提高到可调试水平。若确实无法构建回路，应停止并明确说明，列出尝试过的方法，向用户请求可复现环境访问、脱敏捕获产物（HAR、日志转储、核心转储、带时间戳录屏）或添加临时生产插桩的许可；没有回路不要进入假设阶段。阶段 1 完成标准是：已至少运行过一次、能命名的一条命令，且该命令具备红能力（驱动真实 Bug 代码路径并断言用户的确切症状）、确定性、快速（秒级）、可由代理无人值守运行。
阶段 2：复现与最小化。运行回路并观察其变红，确认失败模式与用户描述一致、可多次复现（非确定性 Bug 达到足够高复现率）、捕获确切症状。随后逐步削减输入、调用方、配置、数据和步骤，每次削减后重跑回路，直到剩余每个元素都是承重的：移除任一项都会让回路变绿。未复现并最小化前不要继续。
阶段 3：假设。在测试前生成 3–5 个排序假设，避免锚定第一个想法。每个假设必须可证伪，格式为“若 X 是原因，则 Y 会使 Bug 消失/恶化”。无法陈述预测的假设应丢弃或锐化。测试前向用户展示排序列表，用户可能凭领域知识快速重排或排除；用户不在时可继续。
阶段 4：插桩。每个探针必须对应阶段 3 的具体预测，一次只改一个变量。优先使用调试器/REPL 检查；其次在能区分假设的边界加定向日志；不要“记录一切再 grep”。每条调试日志加唯一前缀如 [DEBUG-a4f2]，结束时一次 grep 清理。需要运行服务器或读日志时，可在 Monitor 下后台启动开发服务器或 tail -f 应用日志，并用 grep --line-buffered 过滤标签和错误签名；否则将输出写入文件，每次运行后 grep 标签和错误签名。性能分支：性能回归通常不应依赖日志，而应先建立基线测量（计时测试台、microtime(true)、分析器、查询日志、EXPLAIN 计划），再二分，先测量后修复。
阶段 5：修复与回归测试。仅在存在正确接缝时先写回归测试：正确接缝能复现调用点真实 Bug 模式；若接缝过浅（单调用方测试而 Bug 需要多调用方，或单元测试无法复现触发链），回归测试会带来虚假信心，此时应将其本身视为发现并记录，说明代码库架构阻碍锁定 Bug。存在正确接缝时：将最小复现转为该接缝的失败测试，观察失败，应用修复，观察通过，再对原始未最小化场景重跑阶段 1 回路。
阶段 6：清理与复盘。宣告完成前必须：原始复现不再出现（重跑阶段 1 回路）；回归测试通过（或记录缺乏接缝）；所有 [DEBUG-...] 插桩已移除（grep 前缀）；一次性原型已删除或移至明确标记的调试位置；在提交/PR 消息中陈述最终正确的假设。随后思考什么能预防此 Bug：若答案涉及架构变更（无良好测试接缝、调用方纠缠、隐藏耦合），应写出细节并在修复完成后建议用户使用 improve-codebase-architecture；若答案涉及代理环境（本可捕获的检查、无法读取的日志或服务、标准评审遗漏），建议用户在清除会话前使用 /retro。