diagnosing-bugs

用途：面向难缠的 bug 和性能回退。当用户说“diagnose”“debug this”，或反馈某处坏了、抛错、失败、变慢时使用。何时使用：探索代码库时，若存在 GLOSSARY.md 先读取以建立相关模块的心智模型，并查看所触及区域的 ADR。若 bug 的线索穿过过去的 pi 会话（早前运行中出现过，或行为在两次运行间发生变化），用 pi-session-search 技能检索，而不是临时 grep/python，它 UTF-8 安全、了解 JSONL 结构并限制输出。核心能力与流程：第一阶段构建反馈循环——这是关键，其余都是机械工作。可用失败测试（单元、集成、e2e）、对运行中开发服务器的 curl/HTTP 脚本、带固定输入的 CLI 调用并与已知良好快照对比 stdout、无头浏览器脚本（Playwright/Puppeteer）驱动 UI 并断言 DOM/console/network、回放捕获的 trace、一次性最小 harness、属性/模糊循环、二分 harness、差分循环，最后才用人工介入的 bash 脚本 scripts/hitl-loop.template.sh，Windows 下用 Git Bash 或 WSL 运行。第二阶段复现并最小化。第三阶段提出 3–5 个排序的可证伪假设。第四阶段按预测埋点，一次只改一个变量，调试日志加唯一前缀如 [DEBUG-a4f2]，性能回退先建立基线测量再二分。第五阶段先写回归测试再修复。第六阶段清理调试痕迹。限制：没有可判红的命令就不进入第二阶段；无法构建循环时须明说并请求环境访问、脱敏产物或临时生产埋点许可。展示命令、输出与产物前必须脱敏，用 <REDACTED> 占位，凭据放环境变量。