Debugging by Evidence

• Without a loop the cause stays hidden. No amount of reading the code will find it.
• The weight sits in the loop and in the five states. Every rule below either sharpens the loop or spends it.
• You opened this in the middle of something. This is how to do that work, not a replacement for it. Name what you were doing before you start, and return to it when this is done.

No hypothesis before a command that reproduces it

• The command MUST already have been run. A command you wrote down and never ran is not a loop.
• Its output MUST show the symptom the user reported. A different red line is a different bug.
• Reading code produces theories nothing can falsify. A theory that cannot fail will survive every test you put it through.
• The loop is that command plus the state it needs. Record both.

What you may write, and when

• Until

  EXPLAINED

  the only write you MAY make is instrumentation. Every inserted line carries a unique tag, so removal is one search. A fix written earlier destroys the red signal that was going to explain it.
• Reverting your own change to re-observe the original failure is allowed here. It is often the point. This skill runs experiments.
• The licence stops at the workspace boundary. No commit. No branch move. No remote or deployment action. Every tag comes out before you close.

Establish before the first run

• Never ask what the environment answers. Three things settle the setup, and the environment already holds two of them.
  • The symptom in the user's own words, quoted.
  • The command the project already declares for running that surface.
  • Whether the failure is reported as constant or occasional, with a rate where it is occasional.
• A symptom you restated in your own words is already a hypothesis. Keep the original beside it.

Which rules to read

• The match sets where to start. The loop state sets what you are allowed to do next. Enter at the matched row, then follow the loop states in order.
• A rule belonging to a state you have not reached is read when you reach it. Not now. Stopping applies from any state and outranks continuing.
• Where two rows both look like the symptom, read both. Under-reading costs a whole loop. Over-reading costs one file.

rules/runnable-signal.md

rules/minimising.md

rules/rival-hypotheses.md

rules/probing.md

rules/fix-at-the-source.md

rules/regression-seam.md

rules/stopping-and-escalating.md

• Signal against minimising. Signal owns a loop that does not reproduce or cannot be trusted. Minimising owns a loop that reproduces but proves too much.
• Hypotheses against probing. Ranking comes before any run. A probe tests exactly one ranked prediction.
• Source against seam. Source decides where the fix belongs. Seam decides where its test belongs. Both wait for

  EXPLAINED

  .

• Get a command to reproduce it before explaining anything.
• Name the state you are in, and take only what that state licenses.
• Never assert a cause no run has supported. An untested explanation is labelled as one.

Say which loop state you are in

NO-SIGNAL

RED

MINIMISED

EXPLAINED

RESOLVED

• Skipping a state is the failure this skill exists to prevent. You MAY spend as long as you need inside one state.
• You SHOULD stop building a loop after five attempts and report

  NO-SIGNAL

  instead. Keep going only where you can name what the sixth attempt does differently.

• NO-SIGNAL

  for long enough is itself the report. Say what you tried and what would produce a signal. Never proceed on theory.
• Know what an empty result means before you trust it. A zero is evidence of absence only from a path that records this event. A path that records nothing, or records only failures, produces the same zero and proves nothing.

What makes a cause a cause

• A run at

  RED

  or better produced it. Not a reading of the code.
• Each link from trigger to symptom cites an exact

  file:line

  .
• One prediction it made was tested and could have failed.
• It explains the whole symptom. That includes the part that seems incidental.

• Confirmed. A probe result you observed.
• Inference. A hypothesis nothing has tested yet.
• Gap. An observation you could not reach. Name what would close it.
• Say what the evidence does not establish. A cause that explains the failure and nothing about its timing has one link missing, not zero.

When to stop instead of trying again

• Three attempted fixes that each reveal a new problem elsewhere are not a fourth attempt. They are the finding.
• The shape is wrong. The report says so, and those three attempts are its evidence.
• One thing you cannot observe stops the run the same way. Name it. Name the observation that would settle it. Then stop, because debugging around an unknown produces a fix nobody can defend.

Output contract

Symptom      as reported, in the user's words, and the loop that shows it
Loop state   one of the five, plus the reproduction rate where it is not 1
Ruled out    each rejected hypothesis with the observation that killed it
Cause        one line per causal link, each at file:line
Not shown    what this evidence leaves open
Fix          the change, and the seam the regression test sits in
Proof        the original loop re-run unmodified, the nearest adjacent path
             also run, and every probe tag removed

• Report what you observed, not what you avoided.
• Never open with "fixed". The reader needs the chain first. A fix stated before its cause reads as a guess that happened to work, and sometimes it is one.

Do not skip this when

• The cause seems obvious. That is the anchor this skill exists to break.
• Someone already told you what is broken. That is a hypothesis, not a signal.
• The fix is one line. A one-line fix to the wrong line is still wrong.
• You are in a hurry. Guessing is what produces the second and third attempt.

Routing

• The table above selects the rule and its order. Read a selected rule in full, interpret it yourself, and say which one you opened in one line.
• Rival explanations MAY be tested in parallel. Ranking them and judging what a result means is not delegated.
• A direct instruction from the user outranks anything here.
• Once a fix exists it stops being a symptom and becomes a change. Hand it to a review of the diff rather than judging it here.