debug
/debug
Systematic debugging with hypothesis-driven investigation. Use when something is broken, tests are failing, unexpected behavior occurs, or errors need investigation. Triggers on: 'this is broken', 'debug', 'why is this failing', 'unexpected error', 'not working', 'bug', 'fix this issue', 'investigate', 'tests failing', 'trace the error', 'use debug mode'. Full access mode - can run commands, add logging, and fix issues.
- Author
- mcouthon ↗
- Repository
- agents ↗
- Licence
- MIT
- Last repository change
- 25.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Systematic debugging with hypothesis-driven investigation. Use when something is broken, tests are failing, unexpected behavior occurs, or errors need investigation. Triggers on: 'this is broken', 'debug', 'why is this failing', 'unexpected error', 'not working', 'bug', 'fix this issue', 'investigate', 'tests failing', 'trace the error', 'use debug mode'. Full access mode - can run commands, add logging, and fix issues.
Triggers from the description
Original author description
Systematic debugging with hypothesis-driven investigation. Use when something is broken, tests are failing, unexpected behavior occurs, or errors need investigation. Triggers on: 'this is broken', 'debug', 'why is this failing', 'unexpected error', 'not working', 'bug', 'fix this issue', 'investigate', 'tests failing', 'trace the error', 'use debug mode'. Full access mode - can run commands, add logging, and fix issues.
How it works
- Core Approach
- The 4-Phase Process
- Debugging Checklist
- Hypothesis Template
- Common Root Causes
- Rationalization Prevention
- Red Flags - STOP and Re-Assess
- Debug Report Format
SKILL.md preview
---
name: debug
description: "Systematic debugging with hypothesis-driven investigation. Use when something is broken, tests are failing, unexpected behavior occurs, or errors need investigation. Triggers on: 'this is broken', 'debug', 'why is this failing', 'unexpected error', 'not working', 'bug', 'fix this issue', 'investigate', 'tests failing', 'trace the error', 'use debug mode'. Full access mode - can run commands, add logging, and fix issues."
allowed-tools: [Read, Edit, Write, Bash, Grep, Glob, LSP]
---
# Debug Mode
Systematic bug investigation and resolution.
## Core Approach
> "Don't guess. Form hypotheses. Test them."
## The 4-Phase Process
### Phase 1: Assessment 🔍
**Goal**: Understand and reproduce
- What is the expected behavior?
- What is the actual behavior?
- Can you reliably reproduce?
- What changed recently?
**Key Questions**:
- When did this start happening?
- Does it happen consistently or intermittently?
- What are the exact inputs that trigger it?
- What error messages or symptoms appear?
#### Building a Feedback Loop
**This is the most important step.** If you have a fast, deterministic, agent-runnable pass/fail signal, you will find the cause. If you don't, no amount of code-staring will save you. Spend disproportionate effort here.
**Techniques — try in roughly this order:**
1. **Failing test** at whatever seam reaches the bug (unit, integration, e2e)
2. **Curl / HTTP script** against a running dev server
3. **CLI invocation** with fixture input, diffing stdout against known-good output
4. **Headless browser script** (Playwright/Puppeteer) — drives UI, asserts on DOM/console
5. **Replay captured trace** — save a real request/payload to disk, replay through the code path
6. **Throwaway harness** — minimal subset of system that exercises the bug path
7. **Property/fuzz loop** — if "sometimes wrong output", run 1000 random inputs
8. **Bisection harness** — automate `git bisect run` between known-good and known-bad
9. **Differential loop** — run same input through old vs new version, diff outputs
**Iterate on the loop:** Can you make it faster? Sharper signal? More deterministic?
**If you cannot build a loop:** Stop and say so. List what you tried. Ask for: captured artifacts (logs, HAR file), environment access, or permission to add temporary instrumentation.
### Phase 2: Investigation 🔬
**Goal**: Isolate and trace
- Trace execution from entry point
- Identify where expected diverges from actual
- Form hypotheses about root cause
- Test hypotheses systematically
**Techniques**:
- Add strategic logging/prints
- Use debugger breakpoints
- Simplify inputs to minimal reproduction
- Check boundary conditions
### Phase 3: Resolution 🔧
**Goal**: Fix minimally and verify
- Implement the smallest fix that addresses root cause
- Don't fix symptoms, fix the disease
- Add regression test
- Verify fix doesn't break other things
**If fix doesn't work:**
- Count: How many fixes attempted?
- If < 3: Return to Phase 1, re-analyze with new information
- If ≥ 3: STOP. Question your understanding of the system.
### Phase 4: Quality ✅
**Goal**: Prevent recurrence
- Add test covering the bug
- Document if the cause was non-obvious
- Consider if similar bugs exist elsewhere
- Clean up debug code
## Debugging Checklist
```markdown
- [ ] **Reproduced**: Can trigger bug consistently
- [ ] **Isolated**: Know which component is failing
- [ ] **Root Cause**: Understand WHY it fails
- [ ] **Fixed**: Minimal change addresses cause
- [ ] **Tested**: Regression test added
- [ ] **Clean**: Debug code removed
```
## Hypothesis Template
For each hypothesis, record: **Hypothesis** (what's wrong) → **Test** (how to verify) → **Result** → **Conclusion** (confirmed/rejected/needs more info).
## Common Root Causes
| Symptom | Often Caused By |
| -------------------------- | --------------------------------------------- |
| Works locally, fails in CI | Environment differences, missing deps |
| Intermittent failure | Race condition, timing, external dependency |
| Wrong output | Logic error, wrong variable, off-by-one |
| Crash/exception | Null/None access, type mismatch, missing data |
| Performance issue | N+1 queries, missing index, memory leak |
## Rationalization Prevention
| Excuse | Reality | Required Action |
| ---------------------------------------------- | ------------------------------------------- | ---------------------------------------------------- |
| "The fix is obvious" | Obvious fixes mask root causes | Form a hypothesis and verify before changing code |
| "It's probably X" | "Probably" isn't evidence | Test the hypothesis — name it, design a test, run it |
| "This is too simple to debug formally" | Simple bugs waste the most time undiagnosed | Follow Phase 1 — reproduce, isolate, then fix |
| "Logs look clean" | You didn't add targeted logging | Add debug logging at the suspected point |
| "I've tried 3 things, might as well try a 4th" | Stacking guesses compounds confusion | STOP. Return to Phase 1. Re-analyze with new info |
| "It works now" | If you don't know why, it will break again | Explain WHY it works and what changed |
## Red Flags - STOP and Re-Assess
If you catch yourself skipping reproduction ("I know what's wrong") or testing multiple hypotheses at once — STOP. Return to Phase 1.
## Debug Report Format
```markdown
## Debug Report
### Bug Summary
- **Expected**: [what should happen]
- **Actual**: [what happens instead]
- **Severity**: [critical/high/medium/low]
### Reproduction
1. [Step to reproduce]
2. [Step to reproduce]
3. [Observe bug]
**Minimal reproduction**: [simplest case that triggers bug]
### Investigation
| Hypothesis | Test | Result |
| ---------- | -------------- | -------------------------- |
| [theory] | [what I tried] | ✅ Confirmed / ❌ Rejected |
### Root Cause
[What's actually wrong and why]
### Fix Applied
- **File**: `path/to/file.py`
- **Change**: [what was modified]
- **Why**: [how this fixes the root cause]
### Verification
- [ ] Bug no longer reproduces
- [ ] Existing tests pass
- [ ] Regression test added: `test_name`
- [ ] No debug code left behind
### Prevention
[How to prevent similar bugs in the future]
```
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · mcouthon/agents | 100 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| nicsuzor/academicops | 100 | MIT |
| duronext/jig | 100 | MIT |
| drosam/agents | 100 | MIT |
| rizukirr/vibekit | 100 | MIT |
| DingyangLyu/MatClaw | 100 | Apache-2.0 |
| Kanevry/session-orchestrator | 100 | MIT |
| kdlbs/kandev | 100 | AGPL-3.0 |
Database snapshot: 13.11.2026 · package version 74236369cbad (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90debugging
Systematic root-cause debugging: reproduce, investigate, hypothesize, fix with verification. Use when asked to "debug this", "fix this bug", "why is this failing", "troubleshoot", or mentions errors, stack traces, broken tests, flaky tests, regressions, or unexpected behavior. - 100debug-issue
Systematic debugging workflow for any code error, crash, test failure, or unexpected behavior. Use this skill whenever a user mentions an error, bug, exception, crash, test failure, or says something "isn't working", "is broken", "keeps failing", or "isn't behaving as expected"… - 90adev:debug
Context-aware systematic debugging. Checks ADRs for known issues, specs for expected behavior, and orientation for architecture context before investigating. Use when encountering any bug, test failure, or unexpected behavior. Trigger on 'fix this', 'fix the bug', 'something is… - 100hypothesis-driven-debugging
Investigate build failures, test errors, runtime crashes, or unexpected behavior through systematic minimal reproduction, multi-hypothesis testing, and evidence-based verification. Use when asked to \"debug\", \"investigate a failure\", \"find root cause\", \"troubleshoot\",… - 100debug-root-cause
Systematically find and fix the root cause of bugs, errors, failing tests, and crashes in JavaScript/TypeScript and Python. Use whenever the user pastes an error or stack trace, says something is broken, "not working", "error", "kenapa gagal", "bug", a test fails, or behavior is… - 90systematic-debugging
Root-cause analysis + bug fixing. Use when user reports bug, error, crash, unexpected behavior, failing test, or asks "debug", "fix this", "why is this happening", "investigate this issue".