Debug
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.From its SKILL.md
npx -y skills add cookys/autopilot --skill debugAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 12 stars12 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
5.3 KB, as published. Nobody here has run it
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.mdproject 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