debug
Comprehensive debugging methodology for finding and fixing bugs (formerly debugging). This skill should be used when debugging code, investigating errors, troubleshooting issues, performing root cause analysis, or responding to incidents. Covers systematic reproduction, hypothesis-driven investigation, and root cause analysis techniques. Use when encountering exceptions, stack traces, crashes, segfaults, undefined behavior, or when bug reports need investigation.
- Installs
- 439
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/pproenca/dot-skills --skill debug- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads debug automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
dot-skills Debugging Best Practices
Comprehensive debugging methodology guide for software engineers, containing 54 rules across 10 categories prioritized by impact. Based on research from Andreas Zeller's "Why Programs Fail" and academic debugging curricula.
When to Apply
Reference these guidelines when:
- Investigating a bug or unexpected behavior
- Debugging code during development
- Code produces wrong results or crashes
- Performance issues need root cause analysis
- Triaging incoming bug reports and prioritizing fixes
- Conducting root cause analysis for incidents
- Reviewing debugging approaches or code for common bug patterns
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Problem Definition | CRITICAL | prob- |
| 2 | Hypothesis-Driven Search | CRITICAL | hypo- |
| 3 | Observation Techniques | HIGH | obs- |
| 4 | Root Cause Analysis | HIGH | rca- |
| 5 | Tool Mastery | MEDIUM-HIGH | tool- |
| 6 | Bug Triage and Classification | MEDIUM | triage- |
| 7 | Common Bug Patterns | MEDIUM | pattern- |
| 8 | Fix Verification | MEDIUM | verify- |
| 9 | Anti-Patterns | MEDIUM | anti- |
| 10 | Prevention & Learning | LOW-MEDIUM | prev- |
Quick Reference
1. Problem Definition (CRITICAL)
prob-reproduce-before-debug- Reproduce the bug before investigatingprob-minimal-reproduction- Create minimal reproduction casesprob-document-symptoms- Document symptoms preciselyprob-separate-symptoms-causes- Separate symptoms from causesprob-state-expected-actual- State expected vs actual behaviorprob-recent-changes- Check recent changes first
2. Hypothesis-Driven Search (CRITICAL)
hypo-scientific-method- Apply the scientific methodhypo-binary-search- Use binary search to localize bugshypo-one-change-at-time- Test one hypothesis at a timehypo-where-not-what- Find WHERE before asking WHAThypo-rule-out-obvious- Rule out obvious causes firsthypo-rubber-duck- Explain the problem aloud
3. Observation Techniques (HIGH)
obs-strategic-logging- Use strategic loggingobs-log-inputs-outputs- Log function inputs and outputsobs-breakpoint-strategy- Use breakpoints strategicallyobs-stack-trace-reading- Read stack traces bottom to topobs-watch-expressions- Use watch expressions for stateobs-trace-data-flow- Trace data flow through system
4. Root Cause Analysis (HIGH)
rca-five-whys- Use the 5 Whys techniquerca-fault-propagation- Trace fault propagation chainsrca-last-known-good- Find the last known good staterca-question-assumptions- Question your assumptionsrca-examine-boundaries- Examine system boundaries
5. Tool Mastery (MEDIUM-HIGH)
tool-conditional-breakpoints- Use conditional breakpointstool-logpoints- Use logpoints instead of modifying codetool-step-commands- Master step over/into/outtool-call-stack-navigation- Navigate the call stacktool-memory-inspection- Inspect memory and object statetool-exception-breakpoints- Use exception breakpoints
6. Bug Triage and Classification (MEDIUM)
triage-severity-vs-priority- Separate severity from prioritytriage-user-impact-assessment- Assess user impact before prioritizingtriage-reproducibility-matters- Factor reproducibility into triagetriage-quick-wins-first- Identify and ship quick wins firsttriage-duplicate-detection- Detect and link duplicate bug reports
7. Common Bug Patterns (MEDIUM)
pattern-null-pointer- Recognize null pointer patternspattern-off-by-one- Spot off-by-one errorspattern-race-condition- Identify race condition symptomspattern-memory-leak- Detect memory leak patternspattern-type-coercion- Watch for type coercion bugspattern-async-await-errors- Catch async/await error handling mistakespattern-timezone-issues- Recognize timezone and date bugs
8. Fix Verification (MEDIUM)
verify-reproduce-fix- Verify with original reproductionverify-regression-check- Check for regressionsverify-understand-why-fix-works- Understand why fix worksverify-add-test- Add test to prevent recurrence
9. Anti-Patterns (MEDIUM)
anti-shotgun-debugging- Avoid shotgun debugginganti-quick-patch- Avoid quick patches without understandinganti-tunnel-vision- Avoid tunnel vision on initial hypothesisanti-debug-fatigue- Recognize debugging fatigueanti-blame-tool- Don't blame the tool too quickly
10. Prevention & Learning (LOW-MEDIUM)
prev-document-solution- Document bug solutionsprev-postmortem- Conduct blameless postmortemsprev-defensive-coding- Add defensive code at boundariesprev-improve-error-messages- Improve error messages
How to Use
Read individual reference files for detailed explanations and code examples:
- Section definitions - Category structure and impact levels
- Rule template - Template for adding new rules
- Example rules: prob-reproduce-before-debug, hypo-binary-search
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
FAQ
What does the debug skill do?
Comprehensive debugging methodology for finding and fixing bugs (formerly debugging). This skill should be used when debugging code, investigating errors, troubleshooting issues, performing root cause analysis, or responding to incidents. Covers systematic reproduction, hypothesis-driven investigation, and root cause analysis techniques. Use when encountering exceptions, stack traces, crashes, segfaults, undefined behavior, or when bug reports need investigation.
How do I install debug?
Run npx skills add https://github.com/pproenca/dot-skills --skill debug in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/debug/ (personal) or .claude/skills/debug/ (project).
Which AI agents can use debug?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is debug safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains debug?
It is published by pproenca in pproenca/dot-skills. It has 439 recorded installs.
More from pproenca/dot-skills
zod
pproenca/dot-skills
Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover React Hook Form integration patterns (use react-hook-form skill) or OpenAPI client generation (use orval skill).
vitest
pproenca/dot-skills
Vitest testing framework patterns for test setup, async testing, mocking with vi., snapshots, and test performance (formerly test-vitest). This skill should be used when writing or debugging Vitest tests. This skill does NOT cover TDD methodology (use test-tdd skill), API mocking with MSW (use test-msw skill), or Jest-specific APIs.
react-hook-form
pproenca/dot-skills
React Hook Form performance optimization for client-side form validation using useForm, useWatch, useController, useFieldArray, the subscribe() API, and the Watch / FormStateSubscribe / FieldArray render-prop components. Covers RHF 7.82 additions including resetDefaultValues() and the disabled field-array option. This skill should be used when building client-side controlled forms with React Hook Form library. This skill does NOT cover React 19 Server Actions, useActionState, or server-side form handling (use react-19 skill for those).
emilkowal-animations
pproenca/dot-skills
Emil Kowalski's animation best practices for web interfaces. Use when writing, reviewing, or implementing animations in React, CSS, or Framer Motion. Triggers on tasks involving transitions, easing, gestures, toasts, drawers, or motion.
nuqs
pproenca/dot-skills
nuqs (type-safe URL query state) best practices for Next.js and other React frameworks. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, limitUrlUpdates, Standard Schema, NuqsAdapter, or Next.js routing with state.
clean-architecture
pproenca/dot-skills
Clean Architecture principles and best practices from Robert C. Martin's book. This skill should be used when designing software systems, reviewing code structure, or refactoring applications to achieve better separation of concerns. Triggers on tasks involving layers, boundaries, dependency direction, entities, use cases, or system architecture.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.