Skip to content

MinLeeV5/devkeel / .harness/skills/systematic-debugging

systematic-debugging

Verified

系统化诊断和修复 Bug、测试或构建失败、异常行为、集成故障与性能回归。先建立可判定的反馈信号、追踪根因并逐一验证可证伪假设;仅在现有错误、测试、日志、diff、debugger 或 profiler 无法区分假设,且临时写入已获授权时使用定向 HTTP 插桩。

FileKindSize
SKILL.mdskill md4.0 KB
agents/openai.yamlconfig236 B
assets/Hdbg.javaother3.6 KB
assets/hdbg-node.cjsscript1.2 KB
assets/hdbg-web.jsscript1.3 KB
references/diagnosis.mdmarkdown3.7 KB
references/instrumentation.mdmarkdown2.6 KB
references/java8-http.mdmarkdown1.3 KB
references/javascript-http.mdmarkdown2.3 KB
scripts/bootstrap.jsscript1.1 KB
scripts/cleanup.jsscript12.0 KB
scripts/debug-server.jsscript10.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. 环境或外部根因

如果证据表明问题来自环境、时序或外部系统,记录已排除范围与触发条件,再根据用户授权选择重试、
超时、错误提示或后续观测。不得把“没有找到代码缺陷”写成“没有根因”。
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall