Root Cause Debugging

在证明根因之前禁止任何修改：先把已知事实与假设分开，再提出假说，并要求根因能解释全部症状。

针对的正是这种失败：agent 猜一个原因、改一处代码、症状转移，于是一个 bug 变成三个。提示词要求写出精确的预期与实际行为并引用原始报错而非转述，强制「先观察后假说、先证明后修改」，并坚持「只能解释部分症状 = 根因错了」。附加章节涵盖用 git log 与 bisect 定位「昨天还好好的」回归，以及自下而上读栈追踪、找出状态最早出错的帧而非最终崩溃的帧。

# Debugging

**Use when:** something is broken and you want the cause found, not a patch that makes the symptom go away.
**Pairs with:** [test_engineering.md](test_engineering.md), [../core/loop_engineering.md](../core/loop_engineering.md)

The failure mode here is specific. An agent guesses a cause, changes something, the symptom shifts, and you now have two bugs. This prompt forbids changing anything until the cause is proven.

---

## The prompt

```text
You are debugging. You do not get to guess.

The rule: no fix until the cause is proven. A fix applied to an unproven
cause is how one bug becomes three.

STEP 1: STATE THE FACTS
Separate what is known from what is assumed. Write:
- Expected behaviour, exactly.
- Actual behaviour, exactly. Quote the error, the wrong value, the stack
  trace. Not a paraphrase.
- When it started, if known. What changed around then.
- Does it happen every time or sometimes? If sometimes, what differs.
Mark every line as OBSERVED or ASSUMED. Do not blur them.

STEP 2: REPRODUCE
Get a reliable trigger before touching anything.
- The exact steps, command, or input that causes it.
- Confirm it fails. Show the output.
If you cannot reproduce it, say so and stop guessing. Instead, list what
information would make it reproducible and how to collect it.

STEP 3: NARROW
Cut the space in half at a time. Do not read the whole codebase.
- Where is the last point the state is correct?
- Where is the first point it is wrong?
- Keep bisecting between them. Say what you checked and what it showed.
Use whatever gives real information: a print, a breakpoint, a log, git
bisect, disabling half the input. Show actual output at each step, not a
description of what you expect.

STEP 4: HYPOTHESISE
Write 3 candidate causes, ranked by likelihood.
For each: the specific mechanism, and a cheap test that would prove it
false. A hypothesis you cannot disprove is not a hypothesis.

STEP 5: PROVE
Test the top hypothesis. Show the result.
The cause is proven only when you can do both:
  a) make the bug appear on demand by triggering the cause, and
  b) explain every observed symptom, including the weird ones.
If a symptom is left unexplained, you have found a cause, not the cause.
Keep going.

STEP 6: FIX
Only now.
- Fix the cause, not the symptom. If you are adding a null check, ask why
  the value is null. That is usually the real bug.
- Change the smallest thing that fixes it.
- Ask what else has this same cause. Bugs come in families. Search for
  the pattern elsewhere.

STEP 7: PROVE THE FIX
- Write a test that fails before the fix and passes after. Show both runs.
- Run the full suite. Show the output.
- Explain why this fix cannot break anything else. Name what you checked.

REPORT
- Root cause, one sentence, mechanical not vague.
- Why it produced these exact symptoms.
- The fix, and why this fix and not another.
- Where else this pattern exists.
- What would have caught this earlier.

BANNED
- "Try changing X and see if it helps."
- Changing several things at once.
- "This should fix it." Either it is proven or it is not.
- Adding a defensive check to hide a symptom without explaining the cause.
- Calling it fixed without a test that fails on the old code.
```

---

## For bugs that will not reproduce

```text
This is intermittent. Do not guess at causes.
Instead:
1. List everything that differs between a passing run and a failing run:
   timing, order, concurrency, data, cache state, network, environment,
   clock, locale, machine.
2. For each, say how you would make it deterministic, force it to happen
   every time, or rule it out.
3. Pick the cheapest one that would eliminate the largest number of
   candidates. Do that first.
4. If we need more data from production, tell me exactly what to log or
   capture, and what pattern in that data would confirm each hypothesis.
```

---

## For "it worked yesterday"

```text
Something changed. Find the change before theorising.
- git log and git diff over the window when it broke.
- Dependency versions, lockfile changes, config changes, environment
  variables, data changes, and anything outside the repo.
- Use git bisect if the window is wide. Give me the exact commands.
Report the commit or change that introduced it before proposing a fix.
```

---

## For a stack trace

```text
Read the trace bottom up. For each frame, say what it was doing and with
what values. Find the frame where the state first became wrong, not the
frame where it finally crashed. Those are usually different, and the
crash frame is usually innocent.
```

---

## Why it works

Models pattern match a stack trace to a common cause and propose the common fix. That is right often enough to be dangerous. The steps here force observation before hypothesis and proof before change, which is the actual difference between debugging and guessing.

The single strongest line is in step 5: the cause must explain every symptom. Partial explanations are how the wrong cause survives.