AutoGineer
Generated banner for Debugging Strategies
Generated logo for Debugging Strategies

Debugging Strategies

Seth HobsonCommunityCreated by Seth Hobson

  • Skill
  • Guidelines
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

Master systematic debugging techniques, profiling tools, and root cause analysis to efficiently track down bugs across any codebase or technology stack. Use when investigating bugs, performance issues, or unexpected behavior.
— the description by Seth Hobson

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to debugging, moving away from guesswork toward a scientific process of observation, hypothesis, and verification. It covers essential mindsets, reproduction strategies, and specific patterns for handling intermittent, performance, and production-related issues. The guide emphasizes the importance of isolating problems, leveraging version control, and using appropriate tooling to ensure root causes are addressed rather than just symptoms.

What it does

  • Defines a scientific method for systematic problem-solving
  • Provides checklists for reproducing and documenting bugs
  • Outlines strategies for intermittent, performance, and production issues
  • Offers best practices for isolation and root cause analysis
  • Lists common debugging pitfalls to avoid
  • Integrates with language-specific debugging tools and techniques

When to use it

  • When you encounter elusive or hard-to-reproduce bugs
  • When investigating application performance bottlenecks
  • When you need to understand or fix unfamiliar codebases
  • When debugging production incidents safely
  • When analyzing crash dumps or stack traces

Advantages

  • Reduces frustration by replacing guesswork with a clear process
  • Increases efficiency through structured isolation techniques
  • Helps prevent recurring issues by focusing on root cause analysis
  • Provides a consistent framework applicable across different technology stacks
  • Encourages better documentation of findings for future reference

Usage examples

“I have an intermittent bug in my Node.js application. How should I approach it?”
The agent will guide you through adding extensive logging, checking for race conditions, analyzing timing dependencies, and performing stress tests to isolate the flaky behavior.
“My Python application is running slowly. What is the best way to find the bottleneck?”
The agent will recommend profiling the code using cProfile, measuring before and after optimizations, and checking for common culprits like N+1 queries or synchronous I/O.
“I need to debug a production issue without breaking anything. What should I do?”
The agent will advise on gathering evidence from logs and error trackers, reproducing the issue locally with anonymized data, and using feature flags for safe investigation.
“How can I use the VS Code debugger for my TypeScript project?”
The agent will provide a configuration template for launch.json to enable debugging, setting breakpoints, and stepping through your TypeScript code.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/wshobson/debugging-strategies/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip debugging-strategies.zip -d .agents/skills

Documentation by Seth Hobson

Debugging Strategies

Transform debugging from frustrating guesswork into systematic problem-solving with proven strategies, powerful tools, and methodical approaches.

When to Use This Skill

  • Tracking down elusive bugs

  • Investigating performance issues

  • Understanding unfamiliar codebases

  • Debugging production issues

  • Analyzing crash dumps and stack traces

  • Profiling application performance

  • Investigating memory leaks

  • Debugging distributed systems

Core Principles

1. The Scientific Method

1. Observe: What's the actual behavior? 2. Hypothesize: What could be causing it? 3. Experiment: Test your hypothesis 4. Analyze: Did it prove/disprove your theory? 5. Repeat: Until you find the root cause

2. Debugging Mindset

Don't Assume:

  • "It can't be X" - Yes it can

  • "I didn't change Y" - Check anyway

  • "It works on my machine" - Find out why

Do:

  • Reproduce consistently

  • Isolate the problem

  • Keep detailed notes

  • Question everything

  • Take breaks when stuck

3. Rubber Duck Debugging

Explain your code and problem out loud (to a rubber duck, colleague, or yourself). Often reveals the issue.

Systematic Debugging Process

Phase 1: Reproduce
## Reproduction Checklist

1. **Can you reproduce it?**
   - Always? Sometimes? Randomly?
   - Specific conditions needed?
   - Can others reproduce it?

2. **Create minimal reproduction**
   - Simplify to smallest example
   - Remove unrelated code
   - Isolate the problem

3. **Document steps**
   - Write down exact steps
   - Note environment details
   - Capture error messages
Phase 2: Gather Information
## Information Collection

1. **Error Messages**
   - Full stack trace
   - Error codes
   - Console/log output

2. **Environment**
   - OS version
   - Language/runtime version
   - Dependencies versions
   - Environment variables

3. **Recent Changes**
   - Git history
   - Deployment timeline
   - Configuration changes

4. **Scope**
   - Affects all users or specific ones?
   - All browsers or specific ones?
   - Production only or also dev?
Phase 3: Form Hypothesis
## Hypothesis Formation

Based on gathered info, ask:

1. **What changed?**
   - Recent code changes
   - Dependency updates
   - Infrastructure changes

2. **What's different?**
   - Working vs broken environment
   - Working vs broken user
   - Before vs after

3. **Where could this fail?**
   - Input validation
   - Business logic
   - Data layer
   - External services
Phase 4: Test & Verify
## Testing Strategies

1. **Binary Search**
   - Comment out half the code
   - Narrow down problematic section
   - Repeat until found

2. **Add Logging**
   - Strategic console.log/print
   - Track variable values
   - Trace execution flow

3. **Isolate Components**
   - Test each piece separately
   - Mock dependencies
   - Remove complexity

4. **Compare Working vs Broken**
   - Diff configurations
   - Diff environments
   - Diff data

Before selecting debugging tools or performing bisect, differential, trace, or memory analysis, read references/tools-and-techniques.md.

Debugging Patterns by Issue Type

Pattern 1: Intermittent Bugs
## Strategies for Flaky Bugs

1. **Add extensive logging**
   - Log timing information
   - Log all state transitions
   - Log external interactions

2. **Look for race conditions**
   - Concurrent access to shared state
   - Async operations completing out of order
   - Missing synchronization

3. **Check timing dependencies**
   - setTimeout/setInterval
   - Promise resolution order
   - Animation frame timing

4. **Stress test**
   - Run many times
   - Vary timing
   - Simulate load
Pattern 2: Performance Issues
## Performance Debugging

1. **Profile first**
   - Don't optimize blindly
   - Measure before and after
   - Find bottlenecks

2. **Common culprits**
   - N+1 queries
   - Unnecessary re-renders
   - Large data processing
   - Synchronous I/O

3. **Tools**
   - Browser DevTools Performance tab
   - Lighthouse
   - Python: cProfile, line_profiler
   - Node: clinic.js, 0x
Pattern 3: Production Bugs
## Production Debugging

1. **Gather evidence**
   - Error tracking (Sentry, Bugsnag)
   - Application logs
   - User reports
   - Metrics/monitoring

2. **Reproduce locally**
   - Use production data (anonymized)
   - Match environment
   - Follow exact steps

3. **Safe investigation**
   - Don't change production
   - Use feature flags
   - Add monitoring/logging
   - Test fixes in staging

Best Practices

  1. Reproduce First: Can't fix what you can't reproduce

  2. Isolate the Problem: Remove complexity until minimal case

  3. Read Error Messages: They're usually helpful

  4. Check Recent Changes: Most bugs are recent

  5. Use Version Control: Git bisect, blame, history

  6. Take Breaks: Fresh eyes see better

  7. Document Findings: Help future you

  8. Fix Root Cause: Not just symptoms

Common Debugging Mistakes

  • Making Multiple Changes: Change one thing at a time

  • Not Reading Error Messages: Read the full stack trace

  • Assuming It's Complex: Often it's simple

  • Debug Logging in Prod: Remove before shipping

  • Not Using Debugger: console.log isn't always best

  • Giving Up Too Soon: Persistence pays off

  • Not Testing the Fix: Verify it actually works

Quick Debugging Checklist

## When Stuck, Check:

- [ ] Spelling errors (typos in variable names)
- [ ] Case sensitivity (fileName vs filename)
- [ ] Null/undefined values
- [ ] Array index off-by-one
- [ ] Async timing (race conditions)
- [ ] Scope issues (closure, hoisting)
- [ ] Type mismatches
- [ ] Missing dependencies
- [ ] Environment variables
- [ ] File paths (absolute vs relative)
- [ ] Cache issues (clear cache)
- [ ] Stale data (refresh database)

Files

SKILL.md

Debugging Strategies

Transform debugging from frustrating guesswork into systematic problem-solving with proven strategies, powerful tools, and methodical approaches.

When to Use This Skill

  • Tracking down elusive bugs

  • Investigating performance issues

  • Understanding unfamiliar codebases

  • Debugging production issues

  • Analyzing crash dumps and stack traces

  • Profiling application performance

  • Investigating memory leaks

  • Debugging distributed systems

Core Principles

1. The Scientific Method

1. Observe: What's the actual behavior? 2. Hypothesize: What could be causing it? 3. Experiment: Test your hypothesis 4. Analyze: Did it prove/disprove your theory? 5. Repeat: Until you find the root cause

2. Debugging Mindset

Don't Assume:

  • "It can't be X" - Yes it can

  • "I didn't change Y" - Check anyway

  • "It works on my machine" - Find out why

Do:

  • Reproduce consistently

  • Isolate the problem

  • Keep detailed notes

  • Question everything

  • Take breaks when stuck

3. Rubber Duck Debugging

Explain your code and problem out loud (to a rubber duck, colleague, or yourself). Often reveals the issue.

Systematic Debugging Process

Phase 1: Reproduce
## Reproduction Checklist

1. **Can you reproduce it?**
   - Always? Sometimes? Randomly?
   - Specific conditions needed?
   - Can others reproduce it?

2. **Create minimal reproduction**
   - Simplify to smallest example
   - Remove unrelated code
   - Isolate the problem

3. **Document steps**
   - Write down exact steps
   - Note environment details
   - Capture error messages
Phase 2: Gather Information
## Information Collection

1. **Error Messages**
   - Full stack trace
   - Error codes
   - Console/log output

2. **Environment**
   - OS version
   - Language/runtime version
   - Dependencies versions
   - Environment variables

3. **Recent Changes**
   - Git history
   - Deployment timeline
   - Configuration changes

4. **Scope**
   - Affects all users or specific ones?
   - All browsers or specific ones?
   - Production only or also dev?
Phase 3: Form Hypothesis
## Hypothesis Formation

Based on gathered info, ask:

1. **What changed?**
   - Recent code changes
   - Dependency updates
   - Infrastructure changes

2. **What's different?**
   - Working vs broken environment
   - Working vs broken user
   - Before vs after

3. **Where could this fail?**
   - Input validation
   - Business logic
   - Data layer
   - External services
Phase 4: Test & Verify
## Testing Strategies

1. **Binary Search**
   - Comment out half the code
   - Narrow down problematic section
   - Repeat until found

2. **Add Logging**
   - Strategic console.log/print
   - Track variable values
   - Trace execution flow

3. **Isolate Components**
   - Test each piece separately
   - Mock dependencies
   - Remove complexity

4. **Compare Working vs Broken**
   - Diff configurations
   - Diff environments
   - Diff data

Before selecting debugging tools or performing bisect, differential, trace, or memory analysis, read references/tools-and-techniques.md.

Debugging Patterns by Issue Type

Pattern 1: Intermittent Bugs
## Strategies for Flaky Bugs

1. **Add extensive logging**
   - Log timing information
   - Log all state transitions
   - Log external interactions

2. **Look for race conditions**
   - Concurrent access to shared state
   - Async operations completing out of order
   - Missing synchronization

3. **Check timing dependencies**
   - setTimeout/setInterval
   - Promise resolution order
   - Animation frame timing

4. **Stress test**
   - Run many times
   - Vary timing
   - Simulate load
Pattern 2: Performance Issues
## Performance Debugging

1. **Profile first**
   - Don't optimize blindly
   - Measure before and after
   - Find bottlenecks

2. **Common culprits**
   - N+1 queries
   - Unnecessary re-renders
   - Large data processing
   - Synchronous I/O

3. **Tools**
   - Browser DevTools Performance tab
   - Lighthouse
   - Python: cProfile, line_profiler
   - Node: clinic.js, 0x
Pattern 3: Production Bugs
## Production Debugging

1. **Gather evidence**
   - Error tracking (Sentry, Bugsnag)
   - Application logs
   - User reports
   - Metrics/monitoring

2. **Reproduce locally**
   - Use production data (anonymized)
   - Match environment
   - Follow exact steps

3. **Safe investigation**
   - Don't change production
   - Use feature flags
   - Add monitoring/logging
   - Test fixes in staging

Best Practices

  1. Reproduce First: Can't fix what you can't reproduce

  2. Isolate the Problem: Remove complexity until minimal case

  3. Read Error Messages: They're usually helpful

  4. Check Recent Changes: Most bugs are recent

  5. Use Version Control: Git bisect, blame, history

  6. Take Breaks: Fresh eyes see better

  7. Document Findings: Help future you

  8. Fix Root Cause: Not just symptoms

Common Debugging Mistakes

  • Making Multiple Changes: Change one thing at a time

  • Not Reading Error Messages: Read the full stack trace

  • Assuming It's Complex: Often it's simple

  • Debug Logging in Prod: Remove before shipping

  • Not Using Debugger: console.log isn't always best

  • Giving Up Too Soon: Persistence pays off

  • Not Testing the Fix: Verify it actually works

Quick Debugging Checklist

## When Stuck, Check:

- [ ] Spelling errors (typos in variable names)
- [ ] Case sensitivity (fileName vs filename)
- [ ] Null/undefined values
- [ ] Array index off-by-one
- [ ] Async timing (race conditions)
- [ ] Scope issues (closure, hoisting)
- [ ] Type mismatches
- [ ] Missing dependencies
- [ ] Environment variables
- [ ] File paths (absolute vs relative)
- [ ] Cache issues (clear cache)
- [ ] Stale data (refresh database)

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Seth Hobson
Publisher
Seth Hobson (Community)
Source
wshobson/agents · plugins/developer-essentials/skills/debugging-strategies · commit 4bde316
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Seth Hobson.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download debugging-strategies.zip