Debugging Methodology
debugging-methodology: Systematic debugging approach with tool recommendations for memory, performance, and system-level issues.
Installation
Details
Usage
After installing, this skill will be available to your AI coding assistant.
Verify installation:
npx agent-skills-cli listSkill Instructions
model: opus name: debugging-methodology description: Systematic debugging approach with tool recommendations for memory, performance, and system-level issues. user-invocable: false allowed-tools: Bash, Read, Grep, Glob created: 2025-12-27 modified: 2025-12-27 reviewed: 2025-12-27
Debugging Methodology
Systematic approach to finding and fixing bugs.
Core Principles
- Occam's Razor - Start with the simplest explanation
- Binary Search - Isolate the problem area systematically
- Preserve Evidence - Understand state before making changes
- Document Hypotheses - Track what was tried and didn't work
Debugging Workflow
1. Understand → What is expected vs actual behavior?
2. Reproduce → Can you trigger the bug reliably?
3. Locate → Where in the code does it happen?
4. Diagnose → Why does it happen? (root cause)
5. Fix → Minimal change to resolve
6. Verify → Confirm fix works, no regressions
Common Bug Patterns
| Symptom | Likely Cause | Check First |
|---|---|---|
| TypeError/null | Missing null check | Input validation |
| Off-by-one | Loop bounds, array index | Boundary conditions |
| Race condition | Async timing | Await/promise handling |
| Import error | Path/module resolution | File paths, exports |
| Type mismatch | Wrong type passed | Function signatures |
| Flaky test | Timing, shared state | Test isolation |
System-Level Tools
Memory Analysis
# Valgrind (C/C++/Rust)
valgrind --leak-check=full --show-leak-kinds=all ./program
valgrind --tool=massif ./program # Heap profiling
# Python
python -m memory_profiler script.py
Performance Profiling
# Linux perf
perf record -g ./program
perf report
perf top # Real-time CPU usage
# Python
python -m cProfile -s cumtime script.py
System Tracing (Traditional)
# System calls (ptrace-based, high overhead)
strace -f -e trace=all -p PID
# Library calls
ltrace -f -S ./program
# Open files/sockets
lsof -p PID
# Memory mapping
pmap -x PID
eBPF Tracing (Modern, Production-Safe)
eBPF is the modern replacement for strace/ptrace-based tracing. Key advantages:
- Low overhead: Safe for production use
- No recompilation: Works on running binaries
- Non-intrusive: Doesn't stop program execution
- Kernel-verified: Bounded execution, can't crash the system
# BCC tools (install: apt install bpfcc-tools)
# Trace syscalls with timing (like strace but faster)
sudo syscount -p PID # Count syscalls
sudo opensnoop -p PID # Trace file opens
sudo execsnoop # Trace new processes
sudo tcpconnect # Trace TCP connections
sudo funccount 'vfs_*' # Count kernel function calls
# bpftrace (install: apt install bpftrace)
# One-liner tracing scripts
sudo bpftrace -e 'tracepoint:syscalls:sys_enter_open { printf("%s %s\n", comm, str(args->filename)); }'
sudo bpftrace -e 'uprobe:/bin/bash:readline { printf("readline\n"); }'
# Trace function arguments in Go/other languages
sudo bpftrace -e 'uprobe:./myapp:main.handleRequest { printf("called\n"); }'
eBPF Tool Hierarchy:
| Level | Tool | Use Case |
|---|---|---|
| High | BCC tools | Pre-built tracing scripts |
| Medium | bpftrace | One-liner custom traces |
| Low | libbpf/gobpf | Custom eBPF programs |
When to use eBPF over strace:
- Production systems (strace adds 10-100x overhead)
- Long-running traces
- High-frequency syscalls
- When you can't afford to slow down the process
Network Debugging
# Packet capture
tcpdump -i any port 8080
# Connection status
ss -tuln
netstat -tuln
Language-Specific Debugging
Python
# Quick debug
import pdb; pdb.set_trace()
# Better: ipdb or pudb
import ipdb; ipdb.set_trace()
# Print with context
print(f"{var=}") # Python 3.8+
JavaScript/TypeScript
// Browser/Node
debugger;
// Structured logging
console.log({ var1, var2, context: 'function_name' });
Rust
// Debug print
dbg!(&variable);
// Backtrace on panic
RUST_BACKTRACE=1 cargo run
Debugging Questions
When stuck, ask:
- What changed recently that could cause this?
- Does it happen in all environments or just one?
- Is the bug in my code or a dependency?
- What assumptions am I making that might be wrong?
- Can I write a minimal reproduction?
Effective Debugging Practices
- Targeted changes: Form a hypothesis, change one thing at a time
- Use proper debuggers: Step through code with breakpoints when possible
- Find root causes: Trace issues to their origin, fix the source
- Reproduce first: Create a minimal reproduction before attempting a fix
- Verify the fix: Confirm the fix resolves the issue and passes tests
More by laurigates
View allInspect GitHub Actions workflow runs, check status, analyze logs, debug failures, and identify root causes. Use when investigating CI/CD failures, checking workflow status, or debugging GitHub Actions issues.
Convert Markdown documents to professional LaTeX with TikZ visualizations and compile to PDF. Use when the user wants to create a presentation-quality PDF from a Markdown document, generate a professional report with diagrams, or convert documentation to print-ready format.
Multi-phase refactoring with persistent checkpoint files that survive context limits. Use when refactoring spans 10+ files, requires multiple phases, or risks hitting conversation context limits. Each phase reads/writes a plan file, enabling resume from any point. Supports "continue the refactor" across sessions.
FVH (Forum Virium Helsinki) Skaffold configuration standards for local Kubernetes development with OrbStack and dotenvx. Use when configuring Skaffold, setting up local K8s development, or when the user mentions FVH Skaffold, local development, Kubernetes profiles, or dotenvx secrets.