debugging
GitHub提供系统性调试方法，强调基于证据定位根因、验证修复及记录过程。适用于Bug排查、测试失败分析及异常行为诊断，避免无依据猜测，确保修复有效且可追溯。
Trigger Scenarios
Install
npx skills add zts212653/clowder-ai --skill debugging -g -y
SKILL.md
Frontmatter
{
"name": "debugging",
"triggers": [
"bug",
"debug",
"报错",
"test failure",
"unexpected behavior"
],
"description": "根据证据定位未知根因并验证修复。 Use when: bug、测试失败或异常行为的根因尚未查明。 Not for: 新功能设计、已确定原因且有精准失败检查的修复（用 tdd）。 Output: 有依据的诊断与修复验证；未解决时给出真实缺口和下一步。\n",
"tips_exempt": "internal diagnostic guidance; no distinct end-user capability or discovery action"
}
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 信息协助核对；这些命令不代替构建与行为证据。
可选参考：四阶段调查
需要组织调查时，可以按下面的顺序起步，也可以根据新证据返回、合并步骤或换方法。
- 根因调查：读完整错误和堆栈、复现条件、最近改动；多组件问题从输入/输出边界追踪状态，找出最早偏离的位置。
- 模式对比：找同仓可工作的路径，读相关实现，比较与失败路径的关键差异。
- 假设实验：写下候选原因及依据，选择能区分解释的小实验，一次尽量只改变一个因素；结果不支持就更新假设。
- 修复验证：确认 RED 真实覆盖问题，实现修复，复验同一信号与受影响路径；出现新症状时回查机制。
相关历史可以用 search_evidence 查询；已知精确代码位置则直接 Read/Grep。搜索服务当前诊断，不是每次开工固定多轮。
反复失败时
多次修复没有新证据、同一状态对象反复暴露缺边，或修一处坏一处时，应停下检查当前假设、共享状态和契约。次数是警报，不是“架构有问题”的证明。
排除修复未加载、复现条件变化等解释后，若确实缺状态契约，回 writing-plans 补清生命周期与不变量；需要不同视角时找合适伙伴。价值取舍、权限或跨猫僵局才按决策漏斗交给 operator。
可选参考：诊断胶囊与报告
八栏诊断胶囊可帮助整理复杂调查。小问题可以只记“现象 → 证据 → 假设/根因 → 修复 → 验证”，也可以直接引用已有 PR/issue。
需要独立 bug report 时可放在 docs/bug-report/<bug-name>/bug-report.md，保留来源、复现、根因、修复和验证；无需先写工作表、再重复写一份报告。
常见误区
| 误区 | 正确做法 |
|---|---|
| 猜“旧 runtime”就建议重启 | 查真实实例与加载证据，重启仍走原授权边界 |
| 胶囊填满就认为根因已知 | 判断依据来自复现与区分实验 |
| 同时改多处后碰巧绿了 | 缩小变量，确认哪个机制解释了问题 |
| 已有精准 RED 仍另造同义测试 | 复用已有信号，补它未覆盖的行为风险 |
| 三次失败就断言需要重构 | 先检查竞争解释与状态契约，不用次数代替根因 |
下一步
根因确认后按 tdd 修复与验证；交付时用与当前声明相匹配的 quality-gate 自证。仍未解决时留下证据、剩余假设和可行动的下一步。
Version History
-
5968c19
Current 2026-09-22 04:42
移除强制性的Runtime Preflight Gate硬门禁及固定7字段收集模板；简化实例取证步骤，强调基于实际证据而非填表；优化调查流程描述，去除旧版严格阶段限制。
- 56d7c29 2026-08-17 04:22
-
f30e20c
2026-08-05 06:05
同步 cat-cafe 仓库变更，稳定门禁内存 fixture 以适配 CI 环境，限制凭证绑定测试防止挂起，对齐公共 CI 平台契约。
- 4167cb0 2026-07-05 14:51
