agentsclimarketplace

Debug

Skill cookys/autopilot/skills/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

Install
npx -y skills add cookys/autopilot --skill debug

Assembled 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.md project context injection. Stricter discipline; prescriptive ordering.
  • superpowers:systematic-debugging is more general-purpose with broader hypothesis-driven framing. Less prescriptive, broader applicability.
<!-- Project-specific config (tool tables, log locations, common commands) -->

!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

SkillWhen to Use
debugCorrectness: crashes, bugs, logic errors, data corruption, connectivity
profilingPerformance: 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

  1. Reproduce the issue reliably
  2. Collect evidence with appropriate tools
  3. Form hypothesis based on evidence
  4. Verify hypothesis (don't assume)
  5. Fix root cause (not symptoms)
  6. Verify fix with same tool + same test
  7. 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 CategoryWhat to Look ForGeneric Tool Examples
Crash / panicStack trace, exit code, core dumpDebugger (gdb/lldb), backtrace env vars, crash logs
Logic errorWrong output, unexpected stateBreakpoints, print/log statements, unit test isolation
Data corruptionBad values in storage, schema mismatchDB query tools, EXPLAIN plans, data validation scripts
ConnectivityTimeout, refused, DNS failurecurl, netcat, ping, tcpdump, browser Network tab
Auth / permissions401/403, token expiry, role mismatchToken decode tools, request headers, auth middleware logs
Build / compileError messages, missing depsBuild tool verbose mode, dependency tree, clean rebuild
State / concurrencyRace condition, deadlock, stale cacheThread dumps, lock analysis, cache inspection

Log Query Funnel

  1. Filter by time range -- narrow to incident window
  2. Filter by severity -- errors, warnings, panics, exceptions
  3. Correlate by request -- trace ID, request ID, session context
  4. Expand context -- surrounding log lines for the correlated events

Anti-Patterns

Anti-PatternFix
Guessing from code without evidenceCollect tool evidence first
Changing code to "see what happens"Form hypothesis, then verify
Fixing symptoms instead of root causeTrace the full causal chain
Ignoring intermittent failuresReproduce under controlled conditions
Assuming "works on my machine"Check environment differences

See Also

  • learn -- record debugging discoveries
  • audit -- systematic comparison for parity issues
  • profiling -- performance-specific investigation
  • references/probe-playbook.md -- match symptom against playbook entries (discriminating checks); no match ⇒ escalate per ledger convention

Keep looking

Skills are one crate of 611,178. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.