Systematic Debugging Agent Skill
Four-phase debugging framework for any technical issue. Use when encountering bugs, errors, or unexpected behavior. Prevents random fix attempts.
Install
one command, takes just this skill from the repositorynpx skills add https://github.com/majiayu000/spellbook --skill systematic-debuggingThe instruction itself
11 sections, as written by the authorSystematic Debugging
> From obra/superpowers
Core Principle
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
Random fixes create new bugs. Understanding must precede solutions.
The Four Phases
Phase 1: Root Cause Investigation
Before ANY fix attempt:
- Read error messages carefully
- Full stack traces
- Error codes and descriptions
- Timestamps and context
- Reproduce consistently
- Document exact steps
- Identify triggers
- Note environmental factors
- Check recent changes
- Recent commits
- Dependency updates
- Configuration changes
- Gather diagnostic evidence
- Add logging at component boundaries
- Check input/output at each step
- Trace data flow backward to source
Phase 2: Pattern Analysis
- Find similar working code
- Search codebase for related functionality
- Look for existing patterns
- Read reference implementations completely
- Don't skim
- Understand the full context
- Compare working vs broken
- What's different?
- What assumptions changed?
- Understand dependencies
- What does this code rely on?
- What relies on this code?
Phase 3: Hypothesis and Testing
- Form a SINGLE, SPECIFIC hypothesis
- "The error occurs because X"
- Not "maybe it's A or B or C"
- Test with minimal changes
- One variable at a time
- Don't combine fixes
- Accept results
- If hypothesis is wrong, form new one
- Don't force-fit evidence
- Ask for help when stuck
- After genuine investigation
- With evidence gathered
Phase 4: Implementation
- Create a failing test case FIRST
- Reproduces the bug
- Will pass when fixed
- Implement SINGLE fix
- Address root cause only
- Don't fix "nearby" issues
- Verify the fix
- Test case passes
- No regressions
- Issue is resolved
The 3-Fix Rule
If ≥3 fixes fail: STOP and question the architecture
Three consecutive failed fixes signal:
- Architectural problem, not implementation bug
- Wrong mental model of the system
- Need to step back and reassess
Do NOT attempt more fixes. Reassess the approach.
Critical Red Flags
STOP and restart investigation if you:
- Propose fixes before understanding the problem
- Add multiple changes simultaneously
- Skip investigation for "quick fixes"
- Make 3+ failed fix attempts
- Say "let's just try this"
Debugging Checklist
## Investigation
- [ ] Read full error message/stack trace
- [ ] Reproduced issue consistently
- [ ] Checked recent changes
- [ ] Added diagnostic logging
- [ ] Traced data flow
## Analysis
- [ ] Found similar working code
- [ ] Compared working vs broken
- [ ] Understood all dependencies
## Hypothesis
- [ ] Formed single specific hypothesis
- [ ] Tested with minimal change
- [ ] Accepted results honestly
## Fix
- [ ] Created failing test case
- [ ] Implemented single fix
- [ ] Verified fix works
- [ ] No regressions
Example Workflow
Issue: User login fails silently
Phase 1 - Investigation:
- Error: "null reference at AuthService.validate()"
- Reproduced: happens with specific user emails
- Recent change: added email normalization
Phase 2 - Analysis:
- Working logins use lowercase emails
- Failing logins have mixed case
- Normalization strips @ symbol incorrectly
Phase 3 - Hypothesis:
- "Email normalization regex is wrong"
- Test: log email before/after normalization
- Result: "[email protected]" → "testexample.com"
- Confirmed!
Phase 4 - Fix:
- Write test: normalize("[email protected]") == "[email protected]"
- Fix regex to preserve @
- Verify: test passes, logins work
Other skills for the same job
different authors, same section of the catalogue
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
Use when implementing any feature or bugfix, before writing implementation code
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
Expert guidance for systematic backtesting of trading strategies. Use when developing, testing, stress-testing, or validating quantitative trading strategies. Covers "beating ideas to death" methodology, parameter robustness testing, slippage modeling, bias prevention, and interpreting backtest results. Applicable when user asks about backtesting, strategy validation, robustness testing, avoiding overfitting, or systematic trading development.
Cloud laboratory platform for automated protein testing and validation. Use when designing proteins and needing experimental validation including binding assays, expression testing, thermostability measurements, enzyme activity assays, or protein sequence optimization. Also use for submitting experiments via API, tracking experiment status, downloading results, optimizing protein sequences for better expression using computational tools (NetSolP, SoluProt, SolubleMPNN, ESM), or managing protein design workflows with wet-lab validation.
This skill should be used for time series machine learning tasks including classification, regression, clustering, forecasting, anomaly detection, segmentation, and similarity search. Use when working with temporal data, sequential patterns, or time-indexed observations requiring specialized algorithms beyond standard ML approaches. Particularly suited for univariate and multivariate time series analysis with scikit-learn compatible APIs.
How to use it
Take majiayu000/systematic-debugging from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.