AGENT SKILL

debugging-strategies

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.

License 许可
MIT
所属仓库
filippolmt/skills
最近更新
2026-11-14
Stars
★ 1
Forks
0

01 前言 Front Matter

name
debugging-strategies
description
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.

02 资源文件 3

03 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)

04 同仓库更多 Skills

filippolmt
filippolmt/skills

writing-for-agents

Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.

★ 1
filippolmt
filippolmt/skills

wrangler

Run or troubleshoot Wrangler CLI commands in projects that have a wrangler.jsonc, wrangler.json, or wrangler.toml file, including local development, Previews, deployment, and resource management. For new projects and projects without a Wrangler configuration file, use the cf CLI instead.

★ 1
filippolmt
filippolmt/skills

workers-profiling

Profile or debug CPU usage and memory allocation in deployed Cloudflare Workers and Durable Objects. Then use this information to optimize your code.

★ 1
filippolmt
filippolmt/skills

workers-development

Run, inspect, and debug Cloudflare Workers during local development with cf dev, wrangler dev, or the Cloudflare Vite plugin, using Local Explorer to read and seed binding data and query local traces and logs. Also routes production debugging to Workers observability. Use for debugging requests whether or not the project uses Wrangler.

★ 1
filippolmt
filippolmt/skills

workers-best-practices

Cloudflare Workers best practices for production applications. Use when writing, reviewing, or configuring Workers.

★ 1
filippolmt
filippolmt/skills

wordpress-pro

Develops custom WordPress themes and plugins, creates and registers Gutenberg blocks and block patterns, configures WooCommerce stores, implements WordPress REST API endpoints, applies security hardening (nonces, sanitization, escaping, capability checks), and optimizes performance through caching and query tuning. Use when building WordPress themes, writing plugins, customizing Gutenberg blocks, extending WooCommerce, working with ACF, using the WordPress REST API, applying hooks and filters, or improving WordPress performance and security.

★ 1