---
name: debug-systematically
description: A four-phase method for any bug, failing test or strange behaviour - find the root cause first, compare with working code, test one hypothesis at a time, then fix with a failing test. Use when something is broken and you do not know why, a fix did not work, or you keep guessing at changes.
license: MIT
metadata:
  category: debugging
  tags: "debugging,testing,quality"
  author: johnny-bravo
  version: "1.0"
  updated: "2026-10-31"
  status: published
  source_url: "https://github.com/obra/superpowers/blob/2ce8aa15d05bd57213e6f746f953aafb7ded7a8b/skills/systematic-debugging/SKILL.md"
  source_license: MIT
  copyright: "Copyright (c) 2025 Jesse Vincent"
  original_author: "Jesse Vincent (obra/superpowers)"
  modified: "Adapted by TheSkillVault: shortened, rewritten in plain language for beginners, made stack-neutral, added safety and done-when sections."
  imported_on: "2026-10-31"
---

# Debug systematically

Find the root cause before you change anything. Guessing feels fast, but it usually makes things worse.

## When to use
- A bug, failing test, build error or odd behaviour, and the cause is not obvious.
- You already tried a fix and it did not work.
- You feel the urge to "just try something quickly".

## Steps
1. **Read the error in full.** Read the whole message and stack trace. Note the file, line and error code.
2. **Reproduce it.** Write down the exact steps that make it happen. If you cannot trigger it reliably, gather more data before guessing.
3. **Check what changed.** Look at `git diff`, recent commits, new packages and config or environment changes.
4. **Find where it breaks.** In a system with several parts (browser, API, database, CI), log what goes in and out of each part. Run once and see which part gets bad data.
5. **Trace the bad value back.** Ask where the wrong value came from, then what called that. Fix it at the source, not where it shows up.
6. **Compare with something that works.** Find similar working code in the same project or the official docs. List every difference, even small ones.
7. **Form one hypothesis.** Write it as "I think X causes this because Y". Make the smallest change that tests it. Change one thing at a time.
8. **Lock it in with a test.** Write a test (or a tiny script) that fails because of the bug. Then make the single fix and watch the test pass.
9. **Stop after three failed fixes.** If each fix reveals a new problem somewhere else, the design is probably wrong. Step back and discuss it before trying fix number four.

## Gotchas
- "Quick fix for now, investigate later."
- Changing several things at once and re-running.
- "It's probably X" without evidence.

## Safety
- Never print secrets, API keys or tokens while logging. Log whether they are set, not their values.
- Debug against a copy or a test database, not live customer data. Back up before risky changes.

## Works with any stack
The method is the same in any language or framework. Use your own test runner and logging tools instead of the examples.

## Done when
- You can explain the root cause in one sentence.
- A test that reproduced the bug now passes, and the other tests still pass.
- The fix is one focused change, with no unrelated edits.

## Example prompt
"My checkout page broke again and I've tried three fixes. Help me find the real cause."

---
Adapted from "systematic-debugging" in obra/superpowers by Jesse Vincent (MIT). See LICENSE.txt.