agentsclimarketplace
Sign in

Systematic debugging

Skill majiayu000/spellbook/skills/systematic-debugging

Four-phase debugging framework for any technical issue. Use when encountering bugs, errors, or unexpected behavior. Prevents random fix attempts.From its SKILL.md

Install
npx -y skills add majiayu000/spellbook --skill systematic-debugging

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

SKILL.md

3.8 KB, 898 tokens by cl100k_base, as published. Nobody here has run it

Systematic 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:

  1. Read error messages carefully

    • Full stack traces
    • Error codes and descriptions
    • Timestamps and context

  2. Reproduce consistently

    • Document exact steps
    • Identify triggers
    • Note environmental factors

  3. Check recent changes

    • Recent commits
    • Dependency updates
    • Configuration changes

  4. Gather diagnostic evidence

    • Add logging at component boundaries
    • Check input/output at each step
    • Trace data flow backward to source

Phase 2: Pattern Analysis

  1. Find similar working code

    • Search codebase for related functionality
    • Look for existing patterns

  2. Read reference implementations completely

    • Don't skim
    • Understand the full context

  3. Compare working vs broken

    • What's different?
    • What assumptions changed?

  4. Understand dependencies

    • What does this code rely on?
    • What relies on this code?

Phase 3: Hypothesis and Testing

  1. Form a SINGLE, SPECIFIC hypothesis

    • "The error occurs because X"
    • Not "maybe it's A or B or C"

  2. Test with minimal changes

    • One variable at a time
    • Don't combine fixes

  3. Accept results

    • If hypothesis is wrong, form new one
    • Don't force-fit evidence

  4. Ask for help when stuck

    • After genuine investigation
    • With evidence gathered

Phase 4: Implementation

  1. Create a failing test case FIRST

    • Reproduces the bug
    • Will pass when fixed

  2. Implement SINGLE fix

    • Address root cause only
    • Don't fix "nearby" issues

  3. 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

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Gives 6 of the 12 instructions most debug triage skills give in 898 tokens

Counted across 1,020 of the 1,639 authors here whose files we hold, read 2026-09-06

  • Find root cause before attempting any fixin 134 of 1020, across 118 files
  • Create a failing test case before implementing a fixhere, and in 109 of 1020, across 95 files
  • Read error messages and stack traces completelyhere, and in 102 of 1020, across 88 files
  • Reproduce the issue consistently before investigatinghere, and in 90 of 1020, across 77 files
  • Make the smallest possible change to test a hypothesisin 90 of 1020, across 76 files
  • Trace data flow backward to find the sourcein 84 of 1020, across 70 files
  • Form a single hypothesis before testinghere, and in 78 of 1020, across 64 files
  • Implement only one fix at a timehere, and in 76 of 1020, across 63 files
  • Question the architecture if three fixes failin 73 of 1020, across 59 files
  • Add diagnostic instrumentation at component boundarieshere, and in 68 of 1020, across 56 files
  • Compare broken code against working examplesin 68 of 1020, across 57 files
  • Write a regression test before applying the fixin 62 of 1020, across 55 files

Said here and by no other author read

  • test with minimal changes

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 325,949. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.