系统化排查问题

目标是找到能解释现象的根因，并用同一个反馈环证明修复有效。诊断请求默认只定位和报告；用户要求修复时才修改代码。

核心循环

1. 固定现象：记录错误、环境、输入、期望、实际结果和最近已知正常状态。
2. 建立反馈环：优先使用最小测试、复现命令、页面路径、日志条件或可观察状态，使问题能失败、复跑并在修复后变绿。这一步最值得投入：有了能在这个缺陷上变红的命令，后面的二分、假设和观测都只是在消费它。构造方法、收紧和提高复现率见 references/advanced-modes.md。
3. 收集独立证据：日志、堆栈、配置差异、近期变更、相关源码、网络和环境状态可以并行读取，但结论必须汇入同一证据链。

4. 排序假设：先列出 3-5 个按可能性排序的假设再开始验证，只列一个容易锚定在第一个想法上。每个假设写出它的预测：“如果原因是 X，改动 Y 会让问题消失”；说不出预测的不算假设。用户在场时把排序给用户看一眼，他们常有能立刻重排的领域信息；不等待回复，用户不在时按自己的排序继续。维护轻量矩阵：

   假设 | 支持证据 | 反证 | 置信度 | 下一步最小检查

5. 验证一个假设：用最小观测或可逆改动获取能证实或证伪的结果，不同时改变多个变量。环境支持时优先用调试器或 REPL 查看，一个断点胜过十条日志；加日志时给每条临时日志加唯一前缀（如 [DEBUG-a4f2]），结束时按前缀搜索并全部删除。
6. 更新模型：记录被排除方向；同一症状未消失时停止叠补丁，回到矩阵重新排序。
7. 修复与回归：根因明确且用户授权修复后，做最小修改；先用原反馈环证明问题消失，再按风险扩大验证。修复授权不包含提交、推送、发布或破坏性操作。
8. 同型排查：宣布修复前，提炼触发缺陷的函数、调用形状、选择器、锁或校验缺口，在仓库内搜索同类位置，逐项标注；方法见 references/advanced-modes.md。
9. 事后追问：修复完成后问一句“什么能预防这个缺陷？”。答案涉及架构（没有合适的测试接缝、调用方纠缠、隐式耦合）时，把具体情况作为建议提出，不在本次修复中扩大范围。决定性事实需要深挖才找到时，提出一个低成本、常驻的信号（日志字段、指标、状态输出或启动检查），让下次第一眼就能看到。正确的假设写进提交信息或 PR 说明。

在改代码前，应能用一句话表达当前假设：我认为根因是 X，因为证据 Y；结果 Z 会证伪它。X 要具体到文件、函数、行或触发条件；“状态管理问题”这类说法无法证伪，还不算假设。假设必须解释全部已观察症状，包括报告人认为无关的症状；只解释首个症状的是表层猜测。

加防护前先判断触发症状的状态是否合法：系统允许进入该状态时，处理不了它的代码就是根因，在那里处理就是修复；该状态本不应存在时，在出错处加判断、重试、吞错、截断数值或丢弃状态只会掩盖缺陷，要继续追到产生该状态的位置。为解释一个绕过需要写一大段注释时，说明该改的是代码。

出现“先试试这个”“应该是同一个问题”“我本地正常”时，说明还没有假设：先写出假设、重读执行路径或列出环境差异。用户的直接观察与日志冲突时，优先相信观察，把差异当作未覆盖的路径；只在正常路径上通过的探针不能证明故障路径不存在。

反馈环应命中用户报告的具体故障路径，并断言对应的错误输出或终态；“没有报错”或无关测试通过不算复现。先运行一次确认它确实会失败，再尽量缩小输入、调用方和环境条件，每次删去一个条件后重跑。保留原始场景，修复后同时检查最小复现和原始场景。

没有稳定复现时

除安全边界中已授权的应急止损外，只做读取、加观测和缩小范围，不把猜测提交成修复。记录可替代证据，例如 CI 失败、生产日志、用户的稳定步骤、状态差异或最小监控指标，并说明它比本地复现弱在哪里。

运行一次后通过不能自动判定 flaky。至少需要近期重复运行、通过对照和能解释失败的基础设施或时序证据。

缺的是报告人的环境时，下一步交付只读探针而不是新假设：一段可直接复制运行的命令，输出环境信息、争议中的测量值和假设所依赖的状态，不输出凭据或私有路径；安装方式、目录、locale、shell 和版本都要探测，不按自己的环境写死。

按问题类型取证

• 窗口生命周期、事件顺序、焦点、定时器、状态机和异步时序问题：形成假设时就加定向日志，不靠静态阅读连猜两次。
• 渲染或视觉问题：先查图层、层叠上下文和样式计算，再加日志或调试覆盖层。
• 纯逻辑问题（公式、边界、off-by-one）：静态分析和最小用例即可。
• 只在重启后出现或消失的问题：先查持久化状态，包括配置文件、缓存、锁文件和序列化快照。
• 性能问题：修改前测基线（耗时、采样、内存），修改后用同一方法复测，报告前后数值；“感觉变快”不是证据。修复方向按代价从低到高尝试，前一项已达标就停：去掉结果无人使用的工作、避免重复做、少做、推迟做、在用户无感时做、并发做、做得更便宜。
• MCP、API 或外部工具失败：先确认服务、凭据、配置和版本，再决定是否换工具，不直接绕开。
• 修改算法后输出仍不对：先确认运行时没有读取旧代码写入的缓存、快照或生成物；需要时在同一修改中失效或升级旧数据版本。

参考路由

只在命中对应问题时读取：

• root-cause-tracing.md：错误出现在深层调用链，需要追踪原始输入或触发点。
• condition-based-waiting.md：异步或测试依赖时序，需要用条件轮询替代固定 sleep。
• defense-in-depth.md：根因修复后仍需要在多个边界阻止无效状态传播。
• references/advanced-modes.md：回归对照、二分定位、同型缺陷搜索、回归测试红绿验证、运行时证据和配置诊断。
• references/failure-patterns.md：问题重复出现、首次修复未生效，或症状更像运行时状态、入口、环境差异而不是语法错误。

安全边界

• 修改配置、版本、端口、权限或网络参数前，记录原值、目标文件和要验证的假设；失败后恢复本轮临时变化。
• 生产和共享环境先做只读检查；修复、重启、删除、回滚和权限操作需要明确目标与授权。事故仍在扩大且已有明确止损授权时，可先记录现场、执行已知可逆的缓解并验证效果；缓解不代表根因已确认或修复完成。
• 临时日志只记录能区分假设的事实，不输出凭据或敏感数据，并在任务结束前移除不需要的观测代码。
• 展示命令、输出和抓取的请求前先脱敏，把密钥替换为 <REDACTED>；反馈环通过环境变量读取凭据，避免凭据出现在展示内容里。只引用携带信号的行，抓包和日志常带认证头。脱敏后不足以诊断时说明并询问用户。
• 保护用户工作区中的无关改动，不用破坏性 Git 命令清理环境。
• 编译或静态检查通过不能证明界面、网络、生成物、状态机或生产行为已经恢复。

停止与重置

• 同一做法反复失败且没有新证据时，停止机械重试，重新检查假设、工具选择和最小复现。
• 连续两个假设被证伪后，重新排序矩阵，不沿熟悉方向继续加码。
• 两次以上修复在同一检查上失败、且它们共享同一前提时，先用一句话写下这个前提，再做一次“前提为假时结果会不同”的观察，同时看失败的分布而不只看幅度；前提未经检验前不开始下一次修复。证据推翻前提时，找失败的共同点；证据支持前提时，追问前几次修复是否只处理了它的后果。
• 连续三个假设被证据推翻后，汇总现象、证据和已排除方向，重新选择诊断方法；有已授权的有效检查时继续，不因计数自动交接。
• 同一阈值、超时、间距或数值调整三次仍不对时，停止调参，检查结构约束和不变量。
• 上下文混乱、假设反复被带回或需更换执行者时，才考虑重开会话；先保留复现命令、原始场景、假设矩阵、已尝试改动及结果、当前工作区状态和剩余授权，不按失败次数直接清空上下文。
• 缺少完成诊断所必需的访问、日志或复现条件时，报告具体缺口和能继续的最小输入。

输出契约

报告：

• 现象、范围和复现/替代证据；
• 当前最高置信假设及其反证条件；
• 已排除方向和关键命令/观察；
• 根因结论及证据强度，或为什么仍不能确定；
• 若已修复：实际改动、原反馈环结果、更宽验证和残余风险；
• 同型排查：检查了哪些位置、哪些同样有问题、哪些可安全保留及原因；未做时说明原因；
• 回归保护：新增测试的位置和红绿运行结果，或不加测试的原因；
• 若只诊断：不修改文件，并给出下一步最小检查。

统一约束

• 证据与验收：遵循 ../_shared/common-acceptance.md，本 skill 只补充其中没有的要求。