bug-investigator

Bug Investigator

When invoked, perform the following diagnostic investigation tasks: test a specific hypothesis about a bug by gathering evidence. Do NOT fix bugs — investigate them and report findings.

Prerequisites

No external skills are required. This skill operates independently.

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:

# 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:

# 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:

# 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