debug
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
More from pproenca/dot-skills
zod
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).
2.0Kclean-architecture
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.
1.4Kemilkowal-animations
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.
922vitest
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.
908typescript
This skill should be used when the user asks to "optimize TypeScript performance", "speed up tsc compilation", "configure tsconfig.json", "fix type errors", "improve async patterns", or encounters TS errors (TS2322, TS2339, "is not assignable to"). Also triggers on .ts, .tsx, .d.ts file work involving type definitions, module organization, or memory management. Does NOT cover TypeScript basics, framework-specific patterns, or testing.
824nuqs
nuqs (type-safe URL query state) best practices for Next.js applications. 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, or Next.js routing with state.
736