Fix errors · How to use a skill

debug-systematically

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.

Version 1.0 · Updated 2026-10-31

View raw SKILL.md

Install in Claude Code, Cursor or Codex (optional)

Only for AI coding tools that read skill folders. Run one line in a terminal, in your project folder. It downloads this skill's text files from TheSkillVault and nothing else; you can read them first with “View raw SKILL.md”.

Claude Code (all your projects)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/debug-systematically/raw' -o ~/'.claude/skills/debug-systematically/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/debug-systematically/files/LICENSE.txt' -o ~/'.claude/skills/debug-systematically/LICENSE.txt'

Cursor (this project)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/debug-systematically/raw' -o '.cursor/skills/debug-systematically/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/debug-systematically/files/LICENSE.txt' -o '.cursor/skills/debug-systematically/LICENSE.txt'

Codex and other Agent Skills tools (this project)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/debug-systematically/raw' -o '.agents/skills/debug-systematically/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/debug-systematically/files/LICENSE.txt' -o '.agents/skills/debug-systematically/LICENSE.txt'

Or connect the whole library over MCP

Add TheSkillVault to Cursor or add this to your app's MCP settings (read-only; help):

{
  "mcpServers": {
    "theskillvault": {
      "url": "https://theskillvault.ai/mcp"
    }
  }
}

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.

Adapted from Jesse Vincent (obra/superpowers) (Copyright (c) 2025 Jesse Vincent), MIT License. Adapted by TheSkillVault: shortened, rewritten in plain language for beginners, made stack-neutral, added safety and done-when sections.

Licence: MIT License. Attribution when you reuse it: Based on work by Jesse Vincent (obra/superpowers) (Copyright (c) 2025 Jesse Vincent, MIT License), https://github.com/obra/superpowers/blob/2ce8aa15d05bd57213e6f746f953aafb7ded7a8b/skills/systematic-debugging/SKILL.md; adapted by TheSkillVault, https://theskillvault.ai