Guided workflow for systematically identifying and fixing software bugs.
Install
mkdir -p .claude/skills/debug-3lawie && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/17375" && unzip -o skill.zip -d .claude/skills/debug-3lawie && rm skill.zipInstalls to .claude/skills/debug-3lawie
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Systematically diagnose and resolve a bug or unexpected behavior — reproduce, isolate, hypothesize, instrument, and verify. Use when the user reports a bug, says "this doesn't work", "why is this broken", or encounters unexpected behavior.Key capabilities
- →Reproduce reported bugs deterministically
- →Isolate the scope of a bug
- →Formulate testable hypotheses for bug causes
- →Instrument code to confirm or reject hypotheses
- →Apply narrowest possible fix to address root cause
- →Verify fix resolves original bug and doesn't break adjacent behavior
How it works
The skill follows a systematic procedure to reproduce, isolate, hypothesize, instrument, fix, and verify bugs, treating them as information gaps.
Inputs & outputs
When to use debug
- →Fix unexpected runtime error
- →Debug intermittent feature failure
- →Identify root cause of crash
About this skill
Systematic Debugging
Read learnings.md beside this file before starting; append an entry when a bug's root cause defied a category below.
Governing Principle
Bugs are information gaps. Debugging is not guessing — it is a systematic process of narrowing the gap between expected and actual behavior until the root cause is isolated and verifiable.
Procedure
-
Reproduce — confirm the bug exists and is deterministic. If the user hasn't described exact steps, ask. If it's intermittent, instrument logging before proceeding.
-
Isolate — narrow the scope:
- Discover the entry point: which route, server function, or component is involved?
- Trace the data flow from trigger to symptom. Read the code path, don't guess.
- Identify the boundary where expected behavior diverges from actual behavior.
-
Hypothesize — form exactly ONE testable hypothesis. State it as: "The bug occurs because [X] causes [Y] at [file:line]." Never hold multiple hypotheses simultaneously — test one, discard or confirm, then move to the next.
-
Instrument — add the minimum observation needed to confirm or reject the hypothesis:
- Console.log at the divergence point (remove after)
- Read error output carefully — the first error in a stack is usually the root cause
- Check types: is the runtime value what the type signature claims?
- Check timing: is an async operation completing before it's consumed?
-
Fix — apply the narrowest possible change that addresses the root cause, not the symptom. Constrain the fix:
- Does it match the project's established patterns? (
/patterns) - Does it introduce a new failure mode?
- Is the fix in the right layer? (data bug → fix in service, not in component rendering)
- Does it match the project's established patterns? (
-
Verify — confirm the fix resolves the original reproduction AND doesn't break adjacent behavior:
- Run the project's linter and type-checker
- If tests exist, run them
- Manually trace the fixed code path once more
Common Bug Categories
| Category | First thing to check |
|---|---|
| Type mismatch | Runtime value vs declared type — look for as any casts hiding the real type |
| Async race | Missing await, check-then-act without atomicity (TOCTOU) |
| State desync | Cache not invalidated after mutation, stale closure in a hook |
| Boundary violation | Server code imported client-side, env variable missing at runtime |
| Null path | Optional field accessed without guard, empty array not handled |
Constraints
- Never guess-and-check. Read the code path before changing anything.
- Remove all debugging instrumentation (console.log, temp vars) before considering the fix complete.
- If the bug reveals a missing pattern or architectural gap, flag it — don't silently patch around it.
Handoffs
- Bug reveals a design problem →
/system-design. - Fix needs to follow an established pattern →
/patterns. - User wants to understand why the bug existed →
/teach. - Fix complete →
/full-reviewto validate.
When not to use it
- →When the user wants to guess-and-check solutions
- →When the user wants to fix symptoms instead of root causes
Limitations
- →The skill does not allow guessing-and-checking
- →All debugging instrumentation must be removed before considering the fix complete
How it compares
This skill enforces a structured, hypothesis-driven debugging process, preventing guesswork and ensuring root causes are addressed, unlike ad-hoc debugging.
Compared to similar skills
debug side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| debug (this skill) | 0 | 17d | No flags | Intermediate |
| python-testing-patterns | 77 | 2mo | Review | Intermediate |
| chrome-devtools | 41 | 6mo | Review | Intermediate |
| bats | 9 | 7mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
python-testing-patterns
wshobson
Implement comprehensive testing strategies with pytest, fixtures, mocking, and test-driven development. Use when writing Python tests, setting up test suites, or implementing testing best practices.
chrome-devtools
mrgoonie
Browser automation, debugging, and performance analysis using Puppeteer CLI scripts. Use for automating browsers, taking screenshots, analyzing performance, monitoring network traffic, web scraping, form automation, and JavaScript debugging.
bats
OleksandrKucherenko
Bash Automated Testing System (BATS) for TDD-style testing of shell scripts. Use when: (1) Writing unit or integration tests for Bash scripts, (2) Testing CLI tools or shell functions, (3) Setting up test infrastructure with setup/teardown hooks, (4) Mocking external commands (curl, git, docker), (5) Generating JUnit reports for CI/CD, (6) Debugging test failures or flaky tests, (7) Implementing test-driven development for shell scripts.
browser-daemon
noiv
Persistent browser automation via Playwright daemon. Keep a browser window open and send it commands (navigate, execute JS, inspect console). Perfect for interactive debugging, development, and testing web applications. Use when you need to interact with a browser repeatedly without opening/closing it.
performance-profiling
davila7
Performance profiling principles. Measurement, analysis, and optimization techniques.
obsidian-local-dev-loop
jeremylongshore
Configure Obsidian plugin development with hot-reload and fast iteration. Use when setting up development workflow, configuring test vaults, or establishing a rapid development cycle. Trigger with phrases like "obsidian dev loop", "obsidian hot reload", "obsidian development workflow", "develop obsidian plugin".