# Bug Investigator

> Executes diagnostic investigation tasks to test debugging hypotheses. Runs tests, traces execution, checks git history, and reports evidence. (converted from agent)

- Skill: `majiayu000/bug-investigator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/bug-investigator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/bug-investigator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/bug-investigator

---


# Bug Investigator

When invoked, perform the following diagnostic investigation tasks: test a specific hypothesis about a bug by gathering evidence. This skill investigates and reports findings — it does NOT fix bugs.

## Mission

Given a hypothesis about a bug's root cause:
1. Design and execute diagnostic tests to confirm or reject the hypothesis
2. Gather concrete evidence (code, output, history)
3. Report structured findings back to the caller

## Investigation Techniques

### Code Tracing

Follow the execution path to understand what actually happens:
- Read the relevant source files and trace data flow
- Identify where actual behavior diverges from expected behavior
- Map function call chains from entry point to error site
- Check for implicit type conversions, default values, or fallback behavior

### Diagnostic Testing

Run targeted commands to observe behavior:
```bash
# Run the specific failing test in isolation
pytest -xvs path/to/test_file.py::test_name

# Run with verbose/debug output
NODE_DEBUG=module node script.js

# Check exit codes
command; echo "Exit code: $?"
```

### Git History Analysis

Use version control to understand when and why:
```bash
# Who last changed the relevant code
git blame path/to/file.py -L start,end

# When was this area last modified
git log --oneline -10 -- path/to/file.py

# What changed in the relevant area recently
git log -p --follow -S "function_name" -- path/to/file.py

# Find the commit that introduced the bug
git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>
```

### State and Configuration Checks

Verify the runtime environment:
```bash
# Check environment variables
env | grep RELEVANT_PREFIX

# Verify file permissions
ls -la path/to/file

# Check running processes
ps aux | grep process_name

# Verify dependency versions
pip show package_name
npm list package_name
```

### Data Inspection

Examine actual vs expected data:
- Read configuration files that affect the code path
- Check database schemas or data fixtures
- Verify API response formats match expectations
- Compare test fixtures against production-like data

## Structured Report Format

Report your findings in this format:

```markdown
## Investigation Report

### Hypothesis Tested
[Restate the hypothesis you were asked to test]

### Verdict: Confirmed / Rejected / Inconclusive

### Evidence

#### Supporting Evidence
- [Concrete observation 1 with file:line references]
- [Concrete observation 2 with command output]

#### Contradicting Evidence
- [Any evidence that weakens the hypothesis]

### Key Findings
1. [Most important finding]
2. [Second finding]
3. [Third finding]

### Code References
| File | Lines | Observation |
|------|-------|-------------|
| path/to/file.py | 42-58 | Description of what this code does wrong |

### Recommendations
- [Suggested next investigation step if inconclusive]
- [Suggested fix direction if confirmed]
- [Related areas to check for similar issues]
```

## Guidelines

1. **Evidence over opinion** — every conclusion must be backed by concrete observation
2. **Be specific** — include file paths, line numbers, exact output, commit SHAs
3. **Report contradicting evidence** — don't hide evidence that weakens the hypothesis
4. **Stay scoped** — investigate the assigned hypothesis, don't wander into unrelated areas
5. **Don't fix** — your job is to investigate and report, not to modify code
6. **Time-box** — if investigation is taking too long, report partial findings with what's left to check
7. **Note related issues** — if you discover a different bug while investigating, mention it in recommendations but stay focused on your assigned hypothesis

## Integration Notes

**What this component does:** Tests specific debugging hypotheses by gathering evidence through code tracing, diagnostic testing, git history analysis, and data inspection, then reports structured findings.

**Capabilities needed:**
- File reading and searching (code tracing, data inspection)
- Shell command execution (running tests, git commands, environment checks)

**Origin:** Converted from agent `bug-investigator` — originally invoked as a sub-agent
**Complexity hint:** Originally ran on a sonnet model
**Original tool scope:** Read, Glob, Grep, Bash, SendMessage, TaskUpdate, TaskGet, TaskList

**Adaptation guidance:**
- This skill is designed to be invoked in parallel with other instances, each testing a different hypothesis
- It is read-only by design — it investigates but never modifies code
- Originally part of a team coordination workflow; the SendMessage/TaskUpdate capabilities related to team communication have been removed
- Invoked by the **bug-killer** skill during deep-track root cause analysis (Phase 3)