PrompTom
All skills

Finding the cause, not a fix that happens to work

debug-root-causePROdebuggingbugs

Forces you to reproduce the bug and name the cause before touching any code.

What it does

  • Triggers on “it broke”, “it worked yesterday”, “the test fails intermittently”, “production behaves differently”.
  • Demands the bug stated in one sentence: given this input, in this state, the code does X where it should do Y. Without that sentence, every edit is a guess.
  • Finds the last working version before reading the code: the commit that introduced it usually names the cause outright and costs less than reading.
  • Allows one change at a time. Two at once and you cannot tell which one told you the truth.
  • Knows the usual hiding places: a value that is not what you assume, shared state between requests, ordering, an error swallowed by an empty catch.
  • Will not let you close with “I changed it and it stopped”. That is not a cause, it is the bug moved somewhere quieter.

Why you'd want it

A guessed fix sometimes works, and that is worse than failing outright: the bug has not gone anywhere, it has gone quiet and will surface where nobody is looking. This runs the work backwards — reproduce, then believe something, then test that one belief. Slower for the first ten minutes and markedly shorter over the whole job.

Where to put it

  1. 1Create the folder .claude/skills/debug-root-cause in your project
  2. 2Put a SKILL.md file in it with the text below
  3. 3That's it. Claude Code loads the skill itself when a task matches the description

To make the skill available in every project rather than one, put it in ~/.claude/skills instead of the project folder.

SKILL.md file

# Finding the cause, not a fix that happens to work

Before changing a single line, be able to state the bug as: given this
input, in this state, the code does X where it should do Y.

If you cannot state it that way, you do not understand it yet, and any
edit you make is a guess. Guesses that appear to work are worse than
guesses that fail — they move the bug somewhere quieter.

## The order

**1. Reproduce it.**
Find the shortest sequence that triggers it every time. "Sometimes" is
not a reproduction. If it only happens sometimes, the missing variable
is part of the bug: time, order, cached state, a second request, an
empty list on the first run.

**2. Find the last version that worked.**
`git log` on the touched files, or bisect. Knowing which commit
introduced it usually names the cause outright and costs less than
reading the code.

**3. Write down what you believe is happening.**

This skill's file is part of the PRO collection

Unlock access
Finding the cause, not a fix that happens to work — PrompTom