agentsclimarketplace

Systematic debugging

Skill majiayu000/spellbook/skills/systematic-debugging

Cross-runtime skills for Claude Code, Codex, and multi-agent workflows.

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.

What its author says it does

Copied from the file, not written here

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

SKILL.md

3.8 KB, 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

Gives 7 of the 12 instructions most debug triage skills give

Counted across 839 of the 1,149 authors here whose files we hold, read 2026-08-06

  • investigate root cause before proposing any fixhere, and in 102 of 839, across 65 files
  • read error messages completelyhere, and in 90 of 839, across 48 files
  • create a failing test case before fixinghere, and in 84 of 839, across 44 files
  • reproduce the issue consistentlyhere, and in 82 of 839, across 40 files
  • change one variable at a timehere, and in 82 of 839, across 42 files
  • check recent changesin 74 of 839, across 35 files
  • write the regression test before fixingin 74 of 839, across 36 files
  • fix the root cause not the symptomin 60 of 839, across 43 files
  • implement a single fix at a timein 59 of 839, across 20 files
  • trace data flow backward to the sourcehere, and in 50 of 839, across 20 files
  • remove all debug instrumentationin 49 of 839, across 13 files
  • form a single hypothesishere, and in 48 of 839, across 18 files

Said here and by no other author read

  • Ask for help when genuinely stuck

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.

Keep looking

Skills are one crate of 328,083. 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.