{
  "id": "diagnosing-bugs",
  "handle": "diagnosing-bugs",
  "canonicalUrl": "https://bestskillsforclaude.com/en/skills/diagnosing-bugs",
  "language": "en",
  "alternates": {
    "en": "https://bestskillsforclaude.com/en/skills/diagnosing-bugs",
    "es": "https://bestskillsforclaude.com/es/skills/diagnosing-bugs",
    "pt-BR": "https://bestskillsforclaude.com/pt-br/skills/diagnosing-bugs",
    "ja": "https://bestskillsforclaude.com/ja/skills/diagnosing-bugs"
  },
  "category": {
    "id": "build-and-ship",
    "name": "Build and ship"
  },
  "publisher": {
    "name": "Matt Pocock",
    "url": "https://github.com/mattpocock"
  },
  "source": "https://github.com/mattpocock/skills",
  "documentation": null,
  "licenseAsStated": "MIT",
  "runtime": "Claude Code and agents that support the skills CLI",
  "lastReviewed": "2026-08-05",
  "headline": "Why do agent bug fixes so often fix the wrong thing?",
  "summary": "Because a plausible fix is available long before the cause is understood.",
  "verdict": "The diagnosing-bugs skill separates diagnosis from repair: understand what is actually happening, prove it, and only then change code. It directly targets the most common expensive failure in agent assisted debugging, which is a confident patch on a symptom that hides the real defect.",
  "bestFor": "Bugs that have already survived one attempted fix, and anything intermittent.",
  "skipIf": "The failure is obvious and local, where the ceremony costs more than it saves.",
  "keyTakeaways": [
    "Diagnosis and repair are different jobs. Mixing them is how symptom fixes ship.",
    "Handing over your theory early is the fastest way to get your theory confirmed rather than tested.",
    "Ask for the evidence that distinguishes the cause from the next most likely one.",
    "It overlaps with systematic-debugging from superpowers. Try both and keep one."
  ],
  "quickStart": [
    "Install it with the skills CLI from mattpocock/skills, published under MIT.",
    "Give it the observation, not your theory. What you expected, what happened, and how to reproduce it.",
    "Require a stated cause and evidence before accepting any change."
  ],
  "sections": [
    {
      "heading": "What it changes in practice",
      "paragraphs": [
        "Given a stack trace, an agent will almost always produce a change that makes the error disappear. That is not the same as fixing the defect, and the difference usually surfaces a week later with a stranger error.",
        "Insisting on a stated cause before a change makes the reasoning inspectable. If the cause is wrong you can see it immediately, which is far cheaper than discovering it through a regression."
      ]
    },
    {
      "heading": "Where it disappoints",
      "paragraphs": [
        "It cannot diagnose what it cannot observe. Missing logs, no reproduction and unavailable environments limit it exactly as they limit a human.",
        "On trivial bugs it is slower than just fixing them, so keep it for the ones that already wasted an afternoon."
      ]
    }
  ],
  "faq": [
    {
      "question": "How is this different from just asking for a fix?",
      "answer": "It requires a stated, evidenced cause before code changes, so symptom patches are visible instead of silent."
    },
    {
      "question": "Should I share my theory of the bug?",
      "answer": "Not at first. Give observations and a reproduction, or you will get your own theory confirmed back to you."
    },
    {
      "question": "How does it compare to systematic-debugging?",
      "answer": "They overlap. superpowers offers a four phase root cause process, this one is lighter. Running both is duplication."
    }
  ],
  "sources": [
    {
      "label": "mattpocock/skills on GitHub",
      "url": "https://github.com/mattpocock/skills",
      "kind": "repository"
    },
    {
      "label": "Agent skills directory listing",
      "url": "https://skills.sh",
      "kind": "directory"
    }
  ],
  "machineReadable": {
    "markdown": "https://bestskillsforclaude.com/en/skills/diagnosing-bugs/content.md",
    "json": "https://bestskillsforclaude.com/en/skills/diagnosing-bugs/skill.json"
  },
  "disclosure": "Editorial desk review based on the publisher's own repository. Not a security audit, a benchmark or a guarantee of maintenance."
}