diagnose
作者 mattpocockdiagnose 是一套结构化的调试工作流，适用于疑难 Bug、间歇性失败的测试以及性能回退。它会帮助你复现问题、缩小失败案例、一次只提出一个假设、加入埋点、修复根因，并通过回归测试把问题锁定下来。当“帮我调这个”还不够时，就用 diagnose 指南。
这个技能评分为 74/100，说明它很适合需要严谨 Bug 诊断流程的用户，但还算不上特别成熟、打磨完善的安装决策页面。仓库提供了足够具体的流程指导，能让 agent 比通用提示词更少靠猜，尤其是在构建确定性的反馈闭环和选择复现方法方面。
- 在 frontmatter 中明确界定了适用触发场景和范围：疑难 Bug、throwers/failures 以及性能回退。
- 操作指引很强：复现 → 缩小 → 提出假设 → 埋点 → 修复 → 回归测试，并给出了构建 pass/fail 闭环的具体方法。
- 包含可运行的 human-in-the-loop shell 模板，有助于在交互式复现流程中被 agent 触发和使用。
- 可见内容更偏向诊断方法论；摘录中没有展示完整的端到端工作流，因此安装用户可能还需要补一些执行细节。
- SKILL.md 中的实验性/测试信号以及缺少安装命令，可能会让它比更成熟的技能显得没那么开箱即用。
diagnose 技能概览
diagnose 是用来做什么的
diagnose 技能是一套结构化的调试工作流，适用于那种 bug 很难一眼定位、测试时好时坏，或者性能已经回退、你需要一种可靠方法来隔离根因的场景。它最适合 agent 和开发者，而不是只想得到一个泛泛的 debug this 提示的人：他们需要一条可重复的路径，从现象到复现，再到假设、埋点、修复和回归测试。
谁应该安装它
如果你经常在代码库里处理那种间歇性出现、依赖环境、或者只会在 UI 或接近生产的流程里暴露的问题，就应该安装 diagnose 技能。它尤其适合 Debugging 场景：当快速扫一遍代码还不够，你需要一种有纪律的方法，在动实现之前先建立一个明确的通过/失败信号。
它的不同之处
diagnose 技能的核心是先建立一个快速反馈闭环。这也是它最主要的差异点：它优先保证可复现性和可观测性，而不是过早改代码。它还会鼓励使用项目里的 glossary 和 ADRs，这样 agent 能对齐领域语言，而不是靠猜模块意图。
如何使用 diagnose 技能
安装 diagnose 技能
使用仓库里的技能安装路径，然后确认技能文件已经出现在你的本地 skills 目录中。对于这个 repo，文档中给出的安装命令是：
npx skills add mattpocock/skills --skill diagnose
安装完成后，先从 SKILL.md 开始，再查看那些塑造工作流的支持文件。最相关的仓库路径是 scripts/hitl-loop.template.sh，以及任何解释术语、架构或测试边界的项目特定文档。
把模糊的 bug 变成一个好的 diagnose 提示
diagnose 技能最有效的输入，应该包含具体症状、发生位置，以及“什么算成功”。一个弱提示会说“diagnose this”。更强的提示会说：
“Diagnose why the export button sometimes fails in staging. Reproduce it in the browser, minimize the steps, identify whether the issue is server-side or client-side, and add a regression test if possible.”
使用 diagnose 时，建议写明：
- 观察到的失败表现
- 发生问题的环境
- 已知正常或已知异常的例子
- 你是否可以运行测试、dev server，或者 browser harness
建议的工作流，以及先读哪些文件
先读 SKILL.md，理解整个闭环；如果 bug 需要 human-in-the-loop 复现，再读 scripts/hitl-loop.template.sh。当 agent 需要你跟着步骤点击、抓取错误，或者在它解析结果时帮忙确认行为，这个脚本尤其有用。
一个实用的工作流是：
- 找到最窄的失败场景
- 建立确定性的信号
- 一次只验证一个假设
- 只有在信号不清楚时才做埋点
- 用回归测试或可重放的 harness 把修复锁住
能显著提升输出质量的建议
如果你想让 diagnose 在 Debugging 场景里的结果更好，就要告诉 agent 允许使用哪些工具：单元测试、CLI 命令、HTTP 请求、浏览器自动化，或者重放已捕获的 trace。也要说明 bug 是确定性的、间歇性的，还是性能相关的，因为这会改变闭环应该怎么搭建。可观察信号越具体，agent 花在猜测上的时间就越少。
diagnose 技能 FAQ
diagnose 比普通的 debug 提示更好吗？
通常是的，尤其是在问题难以复现，或者涉及多层系统时。普通提示可能会直接跳到改代码；diagnose 的设计目标是先建立证据，这对 flaky bug 和回归问题更安全。
什么情况下不该用 diagnose？
对于很直接的语法错误、明显的 null 检查，或者那种已经完全解释清楚、只需要改一个小文件的修复，不要用 diagnose。在这些情况下，完整 diagnose 指南的额外开销可能大于你的实际需求。
diagnose 技能适合新手吗？
适合，只要你能清楚描述症状，并运行建议的检查。它在你不确定 bug 究竟藏在哪儿时尤其有帮助，因为它会给调查过程加上结构，而不是要求你事先具备很深的背景知识。
diagnose 适合所有技术栈吗？
它适合大多数能提供测试、脚本、浏览器检查，或者可重放输入的技术栈。对于那些没有确定性方式来观察成功或失败的系统，它的作用会弱一些，因为这个技能依赖可靠的反馈闭环。
如何改进 diagnose 技能
给技能更强的起始信号
最大的改进来自更好的复现细节。不要只说“应用坏了”，而要提供精确动作、数据形状，以及预期结果和实际结果。如果你有日志、失败的 URL、payload 样本，或者最小化 fixture，一开始就放出来。
在要求根因前先消除歧义
如果可能的失败有多个，先点名你要诊断的那个。比如，要把“按钮没反应”与“请求返回 500”以及“页面很慢”分开。diagnose 在初始问题陈述能映射到单一、可观察失败模式时，效果最好。
用第一轮输出决定下一次实验
拿到第一轮结果后，可以通过回答下面三个问题来改进 diagnose 技能的输出：复现是否已经变成确定性的了，假设是否已经缩小了搜索范围，还是你需要另一种信号？如果输出仍然很模糊，就去要一个更小的 harness、不同的测试切口，或者一个 browser/CLI 重放路径，而不是再要一遍宽泛的解释。