SD

systematic debugging

obra / superpowers
Apr 27, 2026

Use systematic-debugging to investigate bugs and intermittent issues through root cause tracing, verification before the fix.

Introduction

systematic-debugging fits naturally into a developer workflow, especially in the moments right before a deadline when the system still has too many bugs and the team starts reaching for short-term fixes instead of trying to understand what is actually broken. That instinct is understandable, but it usually leads to patches that appear to work while leaving the real root cause untouched. The main value of this skill is that it interrupts that pattern. It does not encourage patch-first debugging. Instead, it asks you to reproduce the problem, collect evidence, trace the failure back to its source, and only then change code.

That may sound slower than just trying something, but in practice it is often faster. Random fixes tend to obscure the real issue, and once that happens the team gets pulled into a long cycle of guesswork. systematic-debugging is designed to stop that cycle as early as possible.

Core Principles

This skill is built around a few non-negotiable rules:

  • Do not propose a fix before the root cause investigation is complete
  • Symptoms are signals, not the point where analysis should stop
  • Evidence matters more than intuition
  • A failed fix means the hypothesis was wrong, not that it is time to pile on more guesses

That is exactly why it becomes more useful under pressure, not less. The whole workflow is designed to resist the urge to make one quick change and hope for the best.

When to Use

systematic-debugging is a strong fit when:

  • A production bug keeps coming back after a few superficial fixes
  • The failure crosses multiple layers, such as CI, build scripts, an API, the service layer, the database, or a signing flow
  • The team is under time pressure and people are starting to feel that guessing a fix would be faster

When Not to Use

It is not the right tool when:

  • The task is really about feature design or requirement exploration rather than diagnosing a failure
  • The investigation is already complete and the only remaining work is external mitigation or operational handling
  • You are unwilling to create even a minimal failing reproduction before making changes

How the Workflow Works

Phase 1: Investigate the Root Cause

  • Read the full error message and stack trace
  • Reproduce the issue consistently instead of drawing conclusions from a one-off failure
  • Check recent changes in code, configuration, dependencies, and environment
  • Add logging or other diagnostics at the boundaries between components in a multi-layer system
  • Trace the bad value, broken state, or failing call chain backward until you find the original trigger

Phase 2: Compare Patterns

  • Find a similar implementation in the same repository that works correctly and use it as a reference
  • Read the reference implementation carefully instead of skimming it and copying pieces of it
  • List every difference, even the ones that seem minor
  • Identify dependencies, environmental prerequisites, and hidden assumptions

Phase 3: Test a Single Hypothesis

  • Write down one concrete hypothesis about the root cause
  • Change one variable at a time
  • Verify the result before deciding what to do next
  • If the hypothesis does not hold, go back to analysis instead of stacking on another quick fix

Phase 4: Implement and Verify

  • Create the smallest failing test or reproduction first
  • Fix the root cause, not the surface symptom
  • Run the relevant tests and confirm that the change does not introduce new bugs
  • If three fixes in a row fail, step back and question the architectural pattern instead of forcing a fourth patch

Supporting Techniques

Alongside the main skill, there are a couple of related companion skills:

  • root-cause-tracing for tracing a problem back to its source
  • defense-in-depth for adding layered validation around data correctness

Why This Skill Stands Out

  • It pushes back against the very human temptation to take shortcuts. The goal is to uncover the real cause of a bug instead of trying to cover it up
  • Its guidance on logging and evidence gathering is concrete, not just a vague suggestion to add more instrumentation
  • It treats reproduction and verification as part of debugging, not as something you do afterward and hope works out
  • It gives you a clear fallback rule when fixes fail, which helps cut down on wasted trial and error

Setup and Usage

There are several ways to install a skill:

  • Method 1: In OpenClaw or Hermes Agent, ask the agent to install the systematic-debugging skill directly.
  • Method 2: Visit skillhub, install the store, and then install the skill.
  • Method 3: Visit Skills.sh, search for systematic-debugging, and use the command provided there.
  • Method 4: Visit Clawhub, download the skill package, and place it in your local skills directory.

Skill Design Evaluation

Back to Developer Skills List