| name | debug |
| description | Evidence-first debugging for correctness issues. Invoke when diagnosing bugs, crashes, logic errors, data corruption, connectivity problems, intermittent failures (incl. flaky tests with environment divergence), or 'works on my machine' issues. For performance issues (slow / high latency / CPU / memory), use the profiling skill instead. For perf regressions with known change attribution, profiling is still primary — measure first, don't guess from the deploy diff. |
Evidence-First Debugging
Routing overlap? If this intent better matches a sibling skill, redirect per references/routing-tiebreaks.md (prefer single-bug diagnosis over baseline test design).
Coexistence with Superpowers
This skill is autopilot's standalone fallback for debugging methodology. If the superpowers plugin is installed, you may prefer superpowers:systematic-debugging — both work; .claude/dispatch-config.md's ## Debugging chain controls which one orchestrator skills (ceo-agent / finish-flow / quality-pipeline) dispatch.
Differences worth knowing:
- autopilot:debug is evidence-first (tool → log → code) with explicit Three Red Lines integration and
debug-config.md project context injection. Stricter discipline; prescriptive ordering.
- superpowers:systematic-debugging is more general-purpose with broader hypothesis-driven framing. Less prescriptive, broader applicability.
!cat .claude/debug-config.md 2>/dev/null || echo "No project-specific debug config found. Use generic evidence collection below."
Core Principle
1. Tool-collected evidence -> profiler, logs, EXPLAIN, debugger, DevTools
2. Log analysis -> correlate with tool findings
3. Source code analysis -> informed by evidence from 1 + 2
Never guess from code alone. Always collect evidence first.
Relationship with Profiling
| Skill | When to Use |
|---|
| debug | Correctness: crashes, bugs, logic errors, data corruption, connectivity |
| profiling | Performance: slow queries, high memory, CPU spikes, latency |
If unsure, start with debug. If evidence points to a performance root cause, switch to profiling.
Debug Cycle
- Reproduce the issue reliably
- Collect evidence with appropriate tools
- Form hypothesis based on evidence
- Verify hypothesis (don't assume)
- Fix root cause (not symptoms)
- Verify fix with same tool + same test
- Record in knowledge base if non-trivial (invoke learn skill)
3-fix architecture gate. If 3 fix attempts have failed, STOP attempting fix #4 — the
repeated failure is itself evidence that the mental model of the architecture is wrong, not that
the next tweak is the right one. Step back and question the structure: is the bug where you think it
is? Is a component boundary / assumption (data shape, ordering, ownership, environment) violated
upstream of where you're patching? Re-collect evidence at the boundary above the suspected site
before any further fix. (Changing a flag/parameter is not a new attempt; changing the diagnostic
angle is.)
Evidence Collection Guide
Identify the right tools for your problem category. If your project has a debug-config.md, it will list specific commands. Otherwise, use this generic guide:
| Problem Category | What to Look For | Generic Tool Examples |
|---|
| Crash / panic | Stack trace, exit code, core dump | Debugger (gdb/lldb), backtrace env vars, crash logs |
| Logic error | Wrong output, unexpected state | Breakpoints, print/log statements, unit test isolation |
| Data corruption | Bad values in storage, schema mismatch | DB query tools, EXPLAIN plans, data validation scripts |
| Connectivity | Timeout, refused, DNS failure | curl, netcat, ping, tcpdump, browser Network tab |
| Auth / permissions | 401/403, token expiry, role mismatch | Token decode tools, request headers, auth middleware logs |
| Build / compile | Error messages, missing deps | Build tool verbose mode, dependency tree, clean rebuild |
| State / concurrency | Race condition, deadlock, stale cache | Thread dumps, lock analysis, cache inspection |
Log Query Funnel
- Filter by time range -- narrow to incident window
- Filter by severity -- errors, warnings, panics, exceptions
- Correlate by request -- trace ID, request ID, session context
- Expand context -- surrounding log lines for the correlated events
Anti-Patterns
| Anti-Pattern | Fix |
|---|
| Guessing from code without evidence | Collect tool evidence first |
| Changing code to "see what happens" | Form hypothesis, then verify |
| Fixing symptoms instead of root cause | Trace the full causal chain |
| Ignoring intermittent failures | Reproduce under controlled conditions |
| Assuming "works on my machine" | Check environment differences |
See Also
learn -- record debugging discoveriesaudit -- systematic comparison for parity issuesprofiling -- performance-specific investigationreferences/probe-playbook.md -- match symptom against playbook entries (discriminating checks); no match ⇒ escalate per ledger convention
