Back to Details

bug-hunt

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bug Hunt Skill

Bug Hunt Skill

Quick Ref: 4-phase investigation (Root Cause → Pattern → Hypothesis → Fix). Output: 
.agents/research/YYYY-MM-DD-bug-*.md
YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.
Systematic investigation to find root cause and design a complete fix.
Requires:
  • session-start.sh has executed (creates 
    .agents/
    directories for output)
  • bd CLI (beads) for issue tracking if creating follow-up issues
快速参考：四阶段调查（根本原因→模式分析→假设验证→问题修复）。输出路径：
.agents/research/YYYY-MM-DD-bug-*.md
你必须执行此工作流程，不能仅进行描述。
通过系统化调查找到问题根本原因并设计完整的修复方案。
前置要求：
  • 已执行session-start.sh（创建用于输出的
    .agents/
    目录）
  • 若需创建后续问题，需使用bd CLI（beads）进行问题跟踪

The 4-Phase Structure

四阶段结构

PhaseFocusOutput
1. Root CauseFind the actual bug locationfile:line, commit
2. PatternCompare against working examplesDifferences identified
3. HypothesisForm and test single hypothesisPass/fail for each
4. ImplementationFix at root, not symptomsVerified fix
For failure category taxonomy and the 3-failure rule, read 
skills/bug-hunt/references/failure-categories.md
.
阶段重点输出
1. 根本原因分析定位Bug的实际位置file:line, commit
2. 模式分析与可正常工作的示例进行对比识别出的差异点
3. 假设验证提出并测试单一假设每个假设的验证结果（通过/失败）
4. 修复实现从根本原因修复，而非仅解决表面症状已验证的修复方案
关于故障分类体系和三次故障规则，请阅读
skills/bug-hunt/references/failure-categories.md
。

Execution Steps

执行步骤

Given 
/bug-hunt <symptom>
:
当输入
/bug-hunt <symptom>
时：

Phase 1: Root Cause Investigation

阶段1：根本原因调查

Step 1.1: Confirm the Bug

步骤1.1：确认Bug存在

First, reproduce the issue:
  • What's the expected behavior?
  • What's the actual behavior?
  • Can you reproduce it consistently?
Read error messages carefully. Do not skip or skim them.
If the bug can't be reproduced, gather more information before proceeding.
首先，复现问题：
  • 预期行为是什么？
  • 实际发生的行为是什么？
  • 能否稳定复现该问题？
仔细阅读错误信息，不要跳过或略读。
如果无法复现Bug，需收集更多信息后再继续。

Step 1.2: Locate the Symptom

步骤1.2：定位症状出现位置

Find where the bug manifests:
bash
undefined
找到Bug表现出来的位置：
bash
undefined

Search for error messages

搜索错误信息

grep -r "<error-text>" . --include=".py" --include=".ts" --include="*.go" 2>/dev/null | head -10
grep -r "<error-text>" . --include=".py" --include=".ts" --include="*.go" 2>/dev/null | head -10

Search for function/variable names

搜索相关函数/变量名

grep -r "<relevant-name>" . --include=".py" --include=".ts" --include="*.go" 2>/dev/null | head -10
undefined
grep -r "<relevant-name>" . --include=".py" --include=".ts" --include="*.go" 2>/dev/null | head -10
undefined

Step 1.3: Git Archaeology

步骤1.3：Git考古法

Find when/how the bug was introduced:
bash
undefined
找出Bug何时、如何被引入：
bash
undefined

When was the file last changed?

文件最后一次修改是什么时候？

git log --oneline -10 -- <file>
git log --oneline -10 -- <file>

What changed recently?

最近有哪些变更？

git diff HEAD~10 -- <file>
git diff HEAD~10 -- <file>

Who changed it and why?

谁修改了该部分，原因是什么？

git blame <file> | grep -A2 -B2 "<suspicious-line>"
git blame <file> | grep -A2 -B2 "<suspicious-line>"

Search for related commits

搜索相关提交记录

git log --oneline --grep="<keyword>" | head -10
undefined
git log --oneline --grep="<keyword>" | head -10
undefined

Step 1.4: Trace the Execution Path

步骤1.4：追踪执行路径

USE THE TASK TOOL (subagent_type: "Explore") to trace the execution path:
  • Find the entry point where the bug manifests
  • Trace backward to find where bad data/state originates
  • Identify all functions in the path and recent changes to them
  • Return: execution path, likely root cause location, responsible changes
使用任务工具（subagent_type: "Explore"）追踪执行路径：
  • 找到Bug表现出来的入口点
  • 反向追踪不良数据/状态的来源
  • 识别路径中的所有函数及其近期变更
  • 返回结果：执行路径、可能的根本原因位置、相关变更记录

Step 1.5: Identify Root Cause

步骤1.5：确定根本原因

Based on tracing, identify:
  • What is wrong (the actual bug)
  • Where it is (file:line)
  • When it was introduced (commit)
  • Why it happens (the logic error)
基于追踪结果，明确：
  • 问题是什么（实际的Bug）
  • 位置在哪里（文件:行号）
  • 何时被引入（提交记录）
  • 为什么会发生（逻辑错误）

Phase 2: Pattern Analysis

阶段2：模式分析

Step 2.1: Find Working Examples

步骤2.1：寻找可正常工作的示例

Search the codebase for similar functionality that WORKS:
bash
undefined
在代码库中搜索功能相似且可正常运行的示例：
bash
undefined

Find similar patterns

搜索相似模式

grep -r "<working-pattern>" . --include=".py" --include=".ts" --include="*.go" 2>/dev/null | head -10
undefined
grep -r "<working-pattern>" . --include=".py" --include=".ts" --include="*.go" 2>/dev/null | head -10
undefined

Step 2.2: Compare Against Reference

步骤2.2：与参考示例对比

Identify ALL differences between:
  • The broken code
  • The working reference
Document each difference.
识别所有差异点：
  • 存在问题的代码
  • 可正常工作的参考代码
记录每个差异点。

Phase 3: Hypothesis and Testing

阶段3：假设验证

Step 3.1: Form Single Hypothesis

步骤3.1：提出单一假设

State your hypothesis clearly:
"I think X is wrong because Y"
One hypothesis at a time. Do not combine multiple guesses.
清晰地陈述你的假设：
"我认为X存在问题，因为Y"
一次仅提出一个假设，不要将多个猜测合并。

Step 3.2: Test with Smallest Change

步骤3.2：通过最小变更进行测试

Make the SMALLEST possible change to test the hypothesis:
  • If it works → proceed to Phase 4
  • If it fails → record failure, form NEW hypothesis
做出最小的变更以验证假设：
  • 如果验证通过→进入阶段4
  • 如果验证失败→记录失败结果，提出新的假设

Step 3.3: Check Failure Counter

步骤3.3：检查故障计数器

Check failure count per 
skills/bug-hunt/references/failure-categories.md
. After 3 countable failures, escalate to architecture review.
根据
skills/bug-hunt/references/failure-categories.md
检查故障次数。若出现3次可计数的故障，需升级至架构评审。

Phase 4: Implementation

阶段4：修复实现

Step 4.1: Design the Fix

步骤4.1：设计修复方案

Before writing code, design the fix:
  • What needs to change?
  • What are the edge cases?
  • Will this fix break anything else?
  • Are there tests to update?
在编写代码前，先设计修复方案：
  • 需要修改哪些内容？
  • 有哪些边缘情况？
  • 该修复是否会影响其他功能？
  • 是否需要更新测试用例？

Step 4.2: Create Failing Test (if possible)

步骤4.2：编写失败测试用例（若可行）

Write a test that demonstrates the bug BEFORE fixing it.
在修复前，先编写一个能复现Bug的测试用例。

Step 4.3: Implement Single Fix

步骤4.3：实现单一修复方案

Fix at the ROOT CAUSE, not at symptoms.
从根本原因进行修复，而非仅解决表面症状。

Step 4.4: Verify Fix

步骤4.4：验证修复效果

Run the failing test - it should now pass.
运行之前的失败测试用例→现在应该可以通过。

Step 5: Write Bug Report

步骤5：编写Bug报告

For bug report template, read 
skills/bug-hunt/references/bug-report-template.md
.
Bug报告模板请参考
skills/bug-hunt/references/bug-report-template.md
。

Step 6: Report to User

步骤6：向用户汇报

Tell the user:
  1. Root cause identified (or not yet)
  2. Location of the bug (file:line)
  3. Proposed fix
  4. Location of bug report
  5. Failure count and types encountered
  6. Next step: implement fix or gather more info
告知用户以下信息：
  1. 是否已定位根本原因（或尚未定位）
  2. Bug的位置（文件:行号）
  3. 建议的修复方案
  4. Bug报告的位置
  5. 遇到的故障次数及类型
  6. 下一步计划：实现修复或收集更多信息

Key Rules

核心规则

  • Reproduce first - confirm the bug exists
  • Use git archaeology - understand history
  • Trace systematically - follow the execution path
  • Identify root cause - not just symptoms
  • Design before fixing - think through the solution
  • Document findings - write the bug report
  • 先复现：确认Bug确实存在
  • 使用Git考古法：了解代码历史
  • 系统化追踪：跟随执行路径
  • 定位根本原因：而非仅解决表面症状
  • 先设计再修复：全面思考解决方案
  • 记录发现：编写Bug报告

Quick Checks

快速检查项

Common bug patterns to check:
  • Off-by-one errors
  • Null/undefined handling
  • Race conditions
  • Type mismatches
  • Missing error handling
  • State not reset
  • Cache issues
需要检查的常见Bug模式：
  • 差一错误
  • Null/未定义值处理问题
  • 竞态条件
  • 类型不匹配
  • 缺失错误处理
  • 状态未重置
  • 缓存问题