debugging

dralgorhythm's avatarfrom dralgorhythm

Troubleshoot and fix bugs systematically. Use when errors occur, tests fail, or unexpected behavior is observed. Covers root cause analysis and debugging strategies.

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

When & Why to Use This Skill

This Claude skill provides a systematic framework for troubleshooting and fixing software bugs across the full stack. By leveraging advanced code tracing with Serena and frontend inspection via Chrome DevTools, it enables developers to perform deep root cause analysis, reproduce complex issues, and implement verified fixes efficiently.

Use Cases

  • Backend Logic Tracing: Using Serena to map call chains and find referencing symbols to locate the exact source of failure in complex codebases.
  • Frontend Error Resolution: Utilizing Chrome DevTools integration to capture console errors, inspect network failures, and debug UI state in real-time.
  • Root Cause Analysis: Systematically isolating minimal reproducible code examples and testing hypotheses to resolve intermittent or 'heisenbug' behaviors.
  • Log Analysis & Pattern Matching: Employing Bash and Grep tools to scan system logs for error patterns and context surrounding application crashes.
  • Regression Prevention: Following a post-fix checklist to ensure root causes are documented and regression tests are added to prevent bug recurrence.
namedebugging
descriptionTroubleshoot and fix bugs systematically. Use when errors occur, tests fail, or unexpected behavior is observed. Covers root cause analysis and debugging strategies.
allowed-toolsRead, Bash, Glob, Grep, mcp__serena__*, mcp__chrome-devtools__*

Debugging and Troubleshooting

MCP Tools

Serena (code tracing):

  • find_referencing_symbols — Trace call chains to failure point
  • find_symbol — Locate function definitions quickly
  • get_symbols_overview — Understand module structure

Chrome DevTools (frontend debugging):

  • Capture console errors and network failures
  • Set breakpoints and inspect state
  • Profile performance bottlenecks
  • Capture screenshots of error states

Workflows

  • Reproduce: Can you reliably reproduce the issue?
  • Isolate: What is the minimal code that exhibits the bug?
  • Trace: Use Serena to follow the call chain
  • Hypothesize: What could cause this behavior?
  • Test: Verify or disprove your hypothesis
  • Fix: Implement the solution
  • Verify: Confirm the fix and add regression test

Debugging Strategy

1. Gather Information

  • Read error messages and stack traces carefully
  • Check logs for context around the error
  • Identify when the issue started (recent changes?)
  • Use Serena to understand code structure around error

2. Trace the Flow

  • Use find_referencing_symbols to trace data flow
  • Map the call chain from entry point to error
  • Identify where data transforms unexpectedly

3. Reproduce Consistently

  • Create a minimal test case
  • Document exact steps to reproduce
  • For frontend bugs, use Chrome DevTools to record network/console

4. Common Causes

  • Null/undefined: Check for missing null checks
  • Off-by-one: Verify loop boundaries and array indices
  • Async timing: Check race conditions and await usage
  • State mutation: Look for unexpected side effects
  • Type coercion: Verify type handling (especially in JS/TS)

Tools

# Check logs
tail -f /var/log/app.log

# Search for error patterns
grep -r "ERROR" ./logs/

# Debug Node.js
node --inspect-brk app.js

# Python debugging
python -m pdb script.py

Frontend Debugging with Chrome DevTools

  • Open DevTools → Console for errors
  • Network tab for failed requests
  • Sources tab for breakpoints
  • Performance tab for slow operations

Post-Fix Checklist

  • Root cause identified and documented
  • Regression test added
  • Similar code checked (use find_symbol to locate)
  • Fix reviewed by another developer