| name | bug-detective |
| description | This skill should be used when the user asks to "debug this", "fix this error", "investigate this bug", "troubleshoot this issue", "find the problem", "something is broken", "this isn't working", "why is this failing", or reports errors/exceptions/bugs. Provides systematic debugging workflow and common error patterns. |
| version | 0.1.0 |
Bug Detective
A systematic debugging workflow for investigating and resolving code errors, exceptions, and failures. Provides structured debugging methods and common error pattern recognition.
Core Philosophy
Debugging is a scientific problem-solving process that requires:
- Understand the problem - Clearly define symptoms and expected behavior
- Gather evidence - Collect error messages, logs, stack traces
- Form hypotheses - Infer possible causes based on evidence
- Verify hypotheses - Confirm or eliminate causes through experiments
- Resolve the issue - Apply fixes and verify
Debugging Workflow
Step 1: Understand the Problem
Before starting to debug, clarify the following information:
Required information to collect:
- Complete error message content
- Exact location of the error (filename and line number)
- Reproduction steps (how to trigger the error)
- Expected behavior vs actual behavior
- Environment info (OS, versions, dependencies)
Question template:
1. What is the exact error message?
2. Which file and line does the error occur at?
3. How can this issue be reproduced? Provide detailed steps.
4. What was the expected result? What actually happened?
5. What recent changes might have introduced this issue?
Step 2: Analyze Error Type
Choose a debugging strategy based on error type:
| Error Type | Characteristics | Debugging Method |
|---|
| Syntax Error | Code cannot be parsed | Check syntax, bracket matching, quotes |
| Import Error | ModuleNotFoundError | Check module installation, path config |
| Type Error | TypeError | Check data types, type conversions |
| Attribute Error | AttributeError | Check if object attribute exists |
| Key Error | KeyError | Check if dictionary key exists |
| Index Error | IndexError | Check list/array index range |
| Null Reference | NoneType/NullPointerException | Check if variable is None |
| Network Error | ConnectionError/Timeout | Check network connection, URL, timeout settings |
| Permission Error | PermissionError | Check file permissions, user permissions |
| Resource Error | FileNotFoundError | Check if file path exists |
Step 3: Locate the Problem Source
Use the following methods to locate the issue:
1. Binary Search Method
- Comment out half the code, check if the problem persists
- Progressively narrow the scope until the problematic code is found
2. Log Tracing
- Add print/logging statements at key locations
- Track variable value changes
- Confirm code execution path
3. Breakpoint Debugging
- Use debugger breakpoint functionality
- Step through code execution
- Inspect variable state
4. Stack Trace Analysis
- Find the call chain from the stack trace in the error message
- Determine the direct cause of the error
- Trace back to the root cause
Step 4: Form and Verify Hypotheses
Hypothesis framework:
Hypothesis: [problem description] causes [error phenomenon]
Verification steps:
1. [verification method 1]
2. [verification method 2]
Expected results:
- If hypothesis is correct: [expected phenomenon]
- If hypothesis is wrong: [expected phenomenon]
Step 5: Apply Fix
After fixing, verify:
- The original error is resolved
- No new errors have been introduced
- Related functionality still works correctly
- Tests added to prevent regression
Python Common Error Patterns
1. Indentation Errors
2. Mutable Default Arguments
3. Closure Issues in Loops
4. Modifying a List While Iterating
5. Using is for String Comparison
6. Forgetting to Call super().__init__()
JavaScript/TypeScript Common Error Patterns
1. this Binding Issues
2. Async Error Handling
3. Object Reference Comparison
Bash/Zsh Common Error Patterns
1. Spacing Issues
name = "John"
name="John"
if[$name -eq 1]; then
if [ $name -eq 1 ]; then
2. Quoting Issues
echo 'The value is $var'
echo "The value is $var"
result=`command`
result=$(command)
3. Unquoted Variables
rm -rf $dir/*
[ -n "$dir" ] && rm -rf "$dir"/*
set -u
4. Variable Scope in Loops
cat file.txt | while read line; do
count=$((count + 1))
done
echo "Total: $count"
while read line; do
count=$((count + 1))
done < file.txt
echo "Total: $count"
5. Array Operations
arr=(1 2 3)
echo $arr[1]
echo ${arr[1]}
echo ${arr[@]}
echo ${#arr[@]}
6. String Comparison
if [ "$name" = "John" ]; then
if [[ "$name" == "John" ]]; then
if [ $age = 18 ]; then
if [ $age -eq 18 ]; then
if (( age == 18 )); then
7. Command Failure Continues Execution
cd /nonexistent
rm file.txt
set -e
cd /nonexistent
rm file.txt
cd /nonexistent || exit 1
Common Debugging Commands
Python pdb Debugger
python -m pdb script.py
pytest -x -vv tests/test_target.py
Node.js Inspector
node --inspect-brk app.js
node --trace-warnings app.js
Git Bisect
git bisect start
git bisect bad
git bisect good <known-good-commit>
Bash Debugging
bash -x script.sh
bash -v script.sh
bash -n script.sh
set -x
set -v
set -e
set -u
set -o pipefail
Preventive Debugging
1. Use Type Checking
2. Input Validation
3. Defensive Programming
4. Logging
Debugging Checklist
Before Starting
During Debugging
After Resolution
Additional Resources
Reference Files
For detailed debugging techniques and patterns:
references/python-errors.md - Python error details
references/javascript-errors.md - JavaScript/TypeScript error details
references/shell-errors.md - Bash/Zsh script error details
references/debugging-tools.md - Debugging tools usage guide
references/common-patterns.md - Common error patterns
Example Files
Working debugging examples:
examples/debugging-workflow.py - Complete debugging workflow example
examples/error-handling-patterns.py - Error handling patterns
examples/debugging-workflow.sh - Shell script debugging example