{
  "id": "systematic-debugging",
  "handle": "systematic-debugging",
  "canonicalUrl": "https://bestskillsforclaude.com/en/skills/systematic-debugging",
  "language": "en",
  "alternates": {
    "en": "https://bestskillsforclaude.com/en/skills/systematic-debugging",
    "es": "https://bestskillsforclaude.com/es/skills/systematic-debugging",
    "pt-BR": "https://bestskillsforclaude.com/pt-br/skills/systematic-debugging",
    "ja": "https://bestskillsforclaude.com/ja/skills/systematic-debugging"
  },
  "category": {
    "id": "engineering-discipline",
    "name": "Engineering discipline"
  },
  "publisher": {
    "name": "Jesse Vincent (obra)",
    "url": "https://github.com/obra"
  },
  "source": "https://github.com/obra/superpowers",
  "documentation": null,
  "licenseAsStated": "MIT",
  "runtime": "Claude Code and other supported coding agents",
  "lastReviewed": "2026-08-05",
  "headline": "What does systematic debugging give you that guessing does not?",
  "summary": "A cause you can name, and a reason to believe the bug is actually gone.",
  "verdict": "The systematic-debugging skill in superpowers runs a four phase root cause analysis instead of trying fixes until the error stops appearing. Use it on bugs that already survived a first attempt, and on anything intermittent, where guess and patch is not just slow but actively misleading.",
  "bestFor": "Intermittent failures, heisenbugs, and defects that came back after a fix.",
  "skipIf": "The cause is obvious from the stack trace and the fix is one line.",
  "keyTakeaways": [
    "The phases exist to stop the jump from symptom to patch.",
    "A named cause is what tells you whether the fix should work, before you deploy it.",
    "Intermittent bugs are where it earns the most, because guessing there is close to random.",
    "It costs time on simple bugs. Save it for the ones that already cost you a day."
  ],
  "quickStart": [
    "Install superpowers from obra/superpowers, published under MIT.",
    "Provide a reliable reproduction, or accept that the first phase will be about finding one.",
    "Do not accept a fix until the cause has been stated and shown to explain the observed behaviour."
  ],
  "sections": [
    {
      "heading": "What it changes in practice",
      "paragraphs": [
        "Guess and patch works often enough to be dangerous. The bug disappears, everyone moves on, and the defect resurfaces in a different shape when the workaround stops covering it.",
        "Staging the work means the reasoning is written down while it is still cheap to challenge. When the stated cause does not explain every observation, that mismatch is visible instead of buried in a diff."
      ]
    },
    {
      "heading": "Where it disappoints",
      "paragraphs": [
        "Without a reproduction the process stalls at the first phase, which is honest but not always what a team under pressure wants to hear.",
        "It also overlaps with the lighter diagnosing-bugs skill. Pick the one that matches how much ceremony your team will actually tolerate."
      ]
    }
  ],
  "faq": [
    {
      "question": "When is it worth the overhead?",
      "answer": "When a bug is intermittent, or when it has already survived one fix. On simple bugs it is slower than fixing them."
    },
    {
      "question": "What if there is no reproduction?",
      "answer": "The first phase becomes finding one. That is the correct order, even when it feels slower than trying a change."
    },
    {
      "question": "How does it compare with diagnosing-bugs?",
      "answer": "Same intent, more structure. Choose one so the agent gets a single set of instructions."
    }
  ],
  "sources": [
    {
      "label": "obra/superpowers on GitHub",
      "url": "https://github.com/obra/superpowers",
      "kind": "repository"
    },
    {
      "label": "Agent skills directory listing",
      "url": "https://skills.sh",
      "kind": "directory"
    }
  ],
  "machineReadable": {
    "markdown": "https://bestskillsforclaude.com/en/skills/systematic-debugging/content.md",
    "json": "https://bestskillsforclaude.com/en/skills/systematic-debugging/skill.json"
  },
  "disclosure": "Editorial desk review based on the publisher's own repository. Not a security audit, a benchmark or a guarantee of maintenance."
}