Debugging（系统性调试）

家里的真实教训是猜根因、反复补症状，以及无证据把问题归咎于 runtime 没更新。诊断要回答发生了什么、为什么、修复是否有效；方法与记录格式可以按现场选择。

必须做到

• 明确预期与实际差异，拿到复现、错误输出或其他能定位问题的观察证据；不能稳定复现时，说明已知条件和剩余缺口。
• 根因判断有能区分候选解释的证据。可以提出假设和小实验，但不能把猜测说成已查明，也不能只凭一次偶然成功宣称修复。
• 修复针对已查到的机制。按 tdd 保留可信 RED → GREEN：已有精准失败检查可复用；缺少行为保护时补回归测试。相关回归检查与影响面匹配。
• 无法稳定自动化复现时，保留可复核的手工步骤、观察结果与限制；验证未完成就如实报告。
• 诊断、修复与验证信息留在可追溯的 issue、PR、thread 或 bug report。已有记录足够时不用再抄一份。
• 实例、权限和数据隔离仍服从家规；方法选择不改变实际运行边界。

下面的方法和模板是可选参考，可以直接使用、改造或替换。无需按模型资格决定能否换方法；自检看诊断与结果是否有依据，不检查模板是否填满。

Runtime 状态断言：先核实对象

声称“没更新 / 没编译 / 没重启 / 还是旧代码”时，必须有对应运行证据。怀疑验证对象、版本或配置错配时，先核对实际实例，再归因。

• 未合入改动的验证使用当前 feature worktree；已合入改动按 Alpha 通道验收。3003/3004 默认是 runtime，不能冒充开发实例。
• 仓库 HEAD、进程启动时间、日志行数各自只是线索，不能单独证明进程已加载目标构建。结合构建/版本标识、实例日志与目标行为确认。
• 纯函数失败、明确堆栈等已经提供有效诊断路径时，可以沿证据调查，不为填表先查无关 API PID。尚未做版本核验，不妨碍说明其他已经查实的现象。

来源：2026-04-05 runtime 状态误判教训；边界见 ../.cat-cafe-shared-refs/shared-rules.md §12、§16a。

可选参考：实例取证

需要排除错实例时，可从这些线索入手。端口与路径从实际启动配置取得，不套用默认值：

实例：目标 URL / API 端口 / worktree
进程：监听 PID 与启动时间
构建：实际加载的版本或构建标识，是否包含目标变更
行为：本次请求对应的日志、输出或复现结果

可用 lsof -nP -iTCP:<实际端口> -sTCP:LISTEN、ps -p <PID> -o lstart= 和目标仓库的 Git 信息协助核对；这些命令不代替构建与行为证据。

可选参考：四阶段调查

需要组织调查时，可以按下面的顺序起步，也可以根据新证据返回、合并步骤或换方法。

1. 根因调查：读完整错误和堆栈、复现条件、最近改动；多组件问题从输入/输出边界追踪状态，找出最早偏离的位置。
2. 模式对比：找同仓可工作的路径，读相关实现，比较与失败路径的关键差异。
3. 假设实验：写下候选原因及依据，选择能区分解释的小实验，一次尽量只改变一个因素；结果不支持就更新假设。
4. 修复验证：确认 RED 真实覆盖问题，实现修复，复验同一信号与受影响路径；出现新症状时回查机制。

相关历史可以用 search_evidence 查询；已知精确代码位置则直接 Read/Grep。搜索服务当前诊断，不是每次开工固定多轮。

反复失败时

多次修复没有新证据、同一状态对象反复暴露缺边，或修一处坏一处时，应停下检查当前假设、共享状态和契约。次数是警报，不是“架构有问题”的证明。

排除修复未加载、复现条件变化等解释后，若确实缺状态契约，回 writing-plans 补清生命周期与不变量；需要不同视角时找合适伙伴。价值取舍、权限或跨猫僵局才按决策漏斗交给 operator。

可选参考：诊断胶囊与报告

八栏诊断胶囊可帮助整理复杂调查。小问题可以只记“现象 → 证据 → 假设/根因 → 修复 → 验证”，也可以直接引用已有 PR/issue。

需要独立 bug report 时可放在 docs/bug-report/<bug-name>/bug-report.md，保留来源、复现、根因、修复和验证；无需先写工作表、再重复写一份报告。

常见误区

下一步

根因确认后按 tdd 修复与验证；交付时用与当前声明相匹配的 quality-gate 自证。仍未解决时留下证据、剩余假设和可行动的下一步。