MinLeeV5/devkeel / .harness/skills/systematic-debugging
systematic-debugging
Verified系统化诊断和修复 Bug、测试或构建失败、异常行为、集成故障与性能回归。先建立可判定的反馈信号、追踪根因并逐一验证可证伪假设;仅在现有错误、测试、日志、diff、debugger 或 profiler 无法区分假设,且临时写入已获授权时使用定向 HTTP 插桩。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.0 KB |
| agents/openai.yaml | config | 236 B |
| assets/Hdbg.java | other | 3.6 KB |
| assets/hdbg-node.cjs | script | 1.2 KB |
| assets/hdbg-web.js | script | 1.3 KB |
| references/diagnosis.md | markdown | 3.7 KB |
| references/instrumentation.md | markdown | 2.6 KB |
| references/java8-http.md | markdown | 1.3 KB |
| references/javascript-http.md | markdown | 2.3 KB |
| scripts/bootstrap.js | script | 1.1 KB |
| scripts/cleanup.js | script | 12.0 KB |
| scripts/debug-server.js | script | 10.9 KB |
references/diagnosis.md
View on GitHub# 系统化诊断方法
主 `SKILL.md` 的状态机不足以区分根因时读取本文件。
## 1. 建立可判定反馈信号
优先复用已有信号,再考虑新建:
1. 已失败的单元、集成或端到端测试;
2. 可重复的 CLI、HTTP 请求或构建命令;
3. 浏览器自动化脚本,断言 DOM、console 或网络结果;
4. 保存并重放真实请求、事件、trace 或数据集;
5. 只启动必要组件的最小 harness;
6. 固定随机种子和时间后的循环、压力或属性测试;
7. 自动判定好坏的版本、配置或数据二分;
8. 最后才使用结构化的人机循环。
信号必须:
- 命中真实故障路径并断言用户描述的精确症状;
- 在同一条件下给出稳定判定;偶发问题要先提高复现率;
- 尽量缩到秒级并可由 Agent 无人值守运行;
- 已至少运行一次并保存关键输出。
无法建立信号时停止假设扩张,说明尝试过什么以及缺少哪类现场材料或访问。
## 2. 复现与最小化
先确认当前失败与用户报告一致,不把邻近的新错误当作目标问题。之后每次只移除一个输入、调用方、
配置、服务或步骤,并重新运行信号。某元素移除后问题消失,说明它仍是触发条件;保留它并继续缩减
其他部分。
最小化结束的判据是:剩余元素都对失败有贡献。保留原始未缩减场景,修复后必须再次验证它。
## 3. 收集根因证据
按成本从低到高调查:
- 完整读取错误、警告、stack、路径、行号和错误码;
- 查看工作树 diff、近期提交、依赖/配置/环境变化;
- 找到仓库内相同模式的正常样例并逐项比较差异;
- 明确依赖、初始化顺序、隐含前置条件和所有权;
- 从坏值或错误状态出现的位置逆向追踪调用者和数据来源;
- 在多组件系统中检查每个边界的输入、输出、配置和状态,先定位失效组件再深入内部。
不要在根因首次产生的位置尚未定位时修补下游症状。
## 4. 假设与实验
生成 2–4 个候选并按现有证据排序。每个候选必须包含可观测预测,例如:
> 如果缓存键遗漏租户维度是根因,那么固定租户后冲突应消失,而改变请求顺序不应影响结果。
每次只运行一个能区分候选的最小实验。实验失败就撤销实验性修改、记录结果并重新排序;不要同时
修改多个变量。需要用户领域知识才能显著改变排序时展示候选,但不因等待非关键反馈而停止安全的
只读调查。
## 5. 性能分支
先记录可重复基线和统计口径,再选择 profiler、火焰图、query plan、资源计数或版本二分。日志可能
改变热点与时序,不作为默认工具。只有某个明确预测需要关联少量业务状态时,才添加定向事件。
## 6. 修复与回归
存在能覆盖真实触发链的测试接缝时,把最小复现转成失败回归测试并确认它确实判红;实施一个针对
根因的修复后确认转绿,再运行原始场景和邻近测试。
没有正确接缝时记录架构限制,并使用最强的现有反馈信号验证。不要为满足形式添加无法覆盖真实
故障模式的浅层测试。
一次修复失败就回到调查;累计三次修复失败时停止并检查是否存在架构级共享状态、耦合或错误抽象。
架构调整会扩大范围,必须交由用户决定。
## 7. 环境或外部根因
如果证据表明问题来自环境、时序或外部系统,记录已排除范围与触发条件,再根据用户授权选择重试、
超时、错误提示或后续观测。不得把“没有找到代码缺陷”写成“没有根因”。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |