bug-hunt

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

四阶段结构

Phase	Focus	Output
1. Root Cause	Find the actual bug location	file:line, commit
2. Pattern	Compare against working examples	Differences identified
3. Hypothesis	Form and test single hypothesis	Pass/fail for each
4. Implementation	Fix at root, not symptoms	Verified 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

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>

What changed recently?

Who changed it and why?

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

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:

Root cause identified (or not yet)
Location of the bug (file:line)
Proposed fix
Location of bug report
Failure count and types encountered
Next step: implement fix or gather more info

告知用户以下信息：

是否已定位根本原因（或尚未定位）
Bug的位置（文件:行号）
建议的修复方案
Bug报告的位置
遇到的故障次数及类型
下一步计划：实现修复或收集更多信息

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/未定义值处理问题
竞态条件
类型不匹配
缺失错误处理
状态未重置
缓存问题

bug-hunt

Original

Translation

Bug Hunt Skill

Bug Hunt Skill

The 4-Phase Structure

四阶段结构

Execution Steps

执行步骤

Phase 1: Root Cause Investigation

阶段1：根本原因调查

Step 1.1: Confirm the Bug

步骤1.1：确认Bug存在

Step 1.2: Locate the Symptom

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

Search for error messages

搜索错误信息

Search for function/variable names

搜索相关函数/变量名

Step 1.3: Git Archaeology

步骤1.3：Git考古法

When was the file last changed?

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

What changed recently?

最近有哪些变更？

Who changed it and why?

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

Search for related commits

搜索相关提交记录

Step 1.4: Trace the Execution Path

步骤1.4：追踪执行路径

Step 1.5: Identify Root Cause

步骤1.5：确定根本原因

Phase 2: Pattern Analysis

阶段2：模式分析

Step 2.1: Find Working Examples

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

Find similar patterns

搜索相似模式

Step 2.2: Compare Against Reference

步骤2.2：与参考示例对比

Phase 3: Hypothesis and Testing

阶段3：假设验证

Step 3.1: Form Single Hypothesis

步骤3.1：提出单一假设

Step 3.2: Test with Smallest Change

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

Step 3.3: Check Failure Counter

步骤3.3：检查故障计数器

Phase 4: Implementation

阶段4：修复实现

Step 4.1: Design the Fix

步骤4.1：设计修复方案

Step 4.2: Create Failing Test (if possible)

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

Step 4.3: Implement Single Fix

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

Step 4.4: Verify Fix

步骤4.4：验证修复效果

Step 5: Write Bug Report

步骤5：编写Bug报告

Step 6: Report to User

步骤6：向用户汇报

Key Rules

核心规则

Quick Checks

快速检查项