diagnose

诊断

用于系统性调查 Bug 的六阶段循环。关键在于：在阶段 1 投入不成比例的精力。有了可靠的反馈循环后，阶段 2–6 就会变成机械流程。

何时使用此技能

• 难以快速修复的疑难 Bug
• 根本原因不明的性能回退
• 需要通过重复运行收集证据的不稳定故障
• 之前的修复尝试均未成功的故障

何时不使用此技能

• 根本原因明确、可快速定点修复的问题 → 使用 debugging
• 从症状入手的日志分诊 → 使用 log-analysis
• 广泛的测试策略设计 → 使用 testing-strategies

六个阶段

阶段 1 — 建立反馈循环（优先投入精力）

为该 Bug 创建快速、确定且自动化的通过／失败信号。

Goal: < 10 second feedback cycle
Signal: automated pass/fail, not manual inspection
Determinism: same input → same result every time

问问自己：“我能否运行一条命令，并在 10 秒内知道 Bug 是否存在？”

• 如果还没有失败测试，就编写一个
• 创建最小复现脚本
• 将触发条件缩减到尽可能小的输入
• 让故障明显且可观察

在反馈循环可靠之前，不要进入阶段 2。

阶段 2 — 复现

在受控条件下确认故障可复现。

• 多次运行反馈循环，确认结果具有确定性
• 记录确切的输入、环境和步骤
• 判断这是新出现的行为（回归），还是一直存在的问题

阶段 3 — 提出假设

按可能性排序，提出有关根本原因的假设。

• 列出 2–4 个候选原因，按可能性排序
• 每个假设都必须可证伪
• 从最可能的原因入手，而不是最有趣的原因

H1 (most likely): [specific cause]
H2: [alternative cause]
H3: [edge case cause]

阶段 4 — 添加检测手段

针对每个假设，运行一项有区分力的检查。

• 在最精确且有用的位置添加日志、断言或断点
• 使用反馈循环快速测试每个假设
• 记录证据：已确认／已证伪／无法确定
• 如果某个假设被证伪，就转向下一个假设

阶段 5 — 修复并测试

应用修复并验证问题已解决。

• 如果可能，先于修复编写回归测试
• 应用能够解决根本原因的最小改动
• 运行完整测试套件，而不只是目标测试
• 确认反馈循环现已通过

阶段 6 — 清理与事后复盘

• 移除用于诊断的检测代码
• 记录根本原因，以及它为何出人意料
• 查找代码库中的其他类似模式
• 考虑添加预防性检查（Lint 规则、测试、断言），以自动捕获此类 Bug

快速参考

# Phase 1: make the feedback loop
# Write a failing test or minimal repro script

# Phase 4: instrument at the narrowest point
console.error('[diagnose] value at boundary:', value)

# Phase 5: verify fix closes the loop
npm test -- --testPathPattern=failing-test

说明

1. 确定任务触发条件和预期输出。
2. 从上到下遵循此技能中的工作流步骤。
3. 验证输出后再进入下一步。
4. 如果任何步骤失败，记录阻碍因素和备用方案。

示例

• 示例：先在小范围内应用此技能，验证通过后再扩展到完整范围。

最佳实践

• 确保输出具有确定性且可审计。
• 优先进行小型、可逆的改动，避免大范围、高风险的编辑。
• 明确记录假设。

参考资料

• 项目规范：.agent-skills/skill-standardization/SKILL.md
• 验证脚本：.agent-skills/skill-standardization/scripts/validate_skill.sh