debugging

br-huang's avatarfrom br-huang

Systematic debugging skill that activates when encountering errors, bugs, or unexpected behavior. Provides structured approach to identifying and fixing issues.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 12, 2025
[Debugging]

When & Why to Use This Skill

This Claude skill provides a systematic and structured approach to debugging software errors, bugs, and unexpected behaviors. It leverages industry-standard principles like hypothesis-driven investigation, binary search for root causes, and rigorous verification to ensure efficient and permanent issue resolution, making it an essential tool for software reliability.

Use Cases

  • Resolving runtime exceptions and error messages by parsing stack traces and identifying the exact point of failure.
  • Identifying the root cause of unexpected code behavior where the application logic diverges from expected requirements.
  • Troubleshooting performance bottlenecks and asynchronous timing issues through systematic isolation and midpoint logging.
  • Fixing regression bugs by analyzing recent code changes and git history to pinpoint the breaking commit.
  • Developing preventive measures and automated test cases to ensure that identified bugs do not recur in future deployments.
namedebugging
descriptionSystematic debugging skill that activates when encountering errors, bugs, or unexpected behavior. Provides structured approach to identifying and fixing issues.

This skill activates when the user encounters errors, bugs, or unexpected code behavior. It provides a systematic debugging approach.

When to Use

Activate this skill when:

  • User reports an error or exception
  • Code isn't behaving as expected
  • Tests are failing
  • Performance issues occur
  • User explicitly asks to debug something

Debugging Principles

1. Reproduce Before Fixing Never attempt to fix a bug you can't reproduce. First confirm:

  • Exact steps to trigger the issue
  • Expected vs actual behavior
  • Any error messages or logs

2. Hypothesis-Driven Investigation

  • Form a hypothesis about the cause
  • Design a test to verify or refute it
  • Eliminate possibilities systematically
  • Don't jump to conclusions

3. Binary Search for Root Cause

  • If unsure where the bug is, bisect
  • Add logging at midpoints
  • Narrow down the problematic section

4. Check Common Culprits First

  • Recent code changes (git log, git diff)
  • Null/undefined values
  • Off-by-one errors
  • Async timing issues
  • Type mismatches
  • Missing error handling

5. Read Error Messages Carefully

  • Parse stack traces completely
  • Identify the actual error vs symptoms
  • Note file names and line numbers
  • Search for the error message in code

Debugging Workflow

1. UNDERSTAND: What should happen vs what happens?
2. REPRODUCE: Can you trigger it reliably?
3. ISOLATE: Where does the behavior diverge?
4. IDENTIFY: What is the root cause?
5. FIX: Address the root cause, not symptoms
6. VERIFY: Does the fix work? Any side effects?
7. PREVENT: How to avoid similar bugs?

Common Debug Commands

# Check recent changes
git log --oneline -20
git diff HEAD~5

# Search for error patterns
grep -r "error_message" --include="*.ts"
grep -r "throw" --include="*.ts"

# Find related code
grep -r "function_name" --include="*.ts"

Output Expectations

When debugging:

  • Be systematic, not random
  • Document what you've tried
  • State hypotheses clearly
  • Provide evidence for conclusions
  • Suggest preventive measures after fixing