git:20260921.9cd7bef to git:20260921.7dfd510

2 added, 1 removed. Audit A to A.

---

name: systematic-debugging

- description: "Phase-based root cause investigation: reproduce, observe, hypothesize, bisect, trace to root cause, verify. TRIGGER when: investigating a bug report, diagnosing unexpected behavior, or doing root cause analysis. SKIP: writing the regression test (use testing-strategy); building a live-repro watcher (use watch-patterns)."

+ description: "Phase-based root cause investigation: reproduce, observe, hypothesize, bisect, verify. TRIGGER when: investigating a bug report, diagnosing unexpected behavior, or doing root cause analysis. SKIP: looking up a known error first (use sofa-search); writing the regression test (use testing-strategy); live-repro watcher (use watch-patterns)."

---

# Systematic Debugging Skill

## Purpose

A repeatable root cause investigation procedure. A bug is not understood until

it can be reproduced on demand and the causal chain is traced back to a fixable

defect. This skill encodes the phase order and the discipline (one variable at a

time, bisect instead of scan, verify by reverting) that keeps an investigation

from turning into guesswork.

## When to Apply

Apply this skill when:

- Investigating a reported bug or unexpected behavior

- Diagnosing a failing test, crash, or incorrect output

- Performing root cause analysis before recommending a fix

- An error message, stack trace, or log output needs to be traced to its origin

Do NOT apply this skill for:

- Writing the regression test that prevents recurrence — use `testing-strategy`

- Constructing the poll/watch loop used to observe a live reproduction — use `watch-patterns`

+ - Looking up a known/unfamiliar error before investigating from scratch — use `sofa-search`

---

## Investigation Phases

Work the phases in order. Do not skip ahead to a fix before phase 6.

| Phase | Action | Exit Criterion |

|-------|--------|-----------------|

| 1. Reproduce first | Establish a minimal, reliable repro before forming any hypothesis | Bug reproduces on demand, deterministically |

| 2. Observe before theorizing | Read the actual error text, stack trace, and logs verbatim | Symptom described using only observed evidence, zero assumptions |

| 3. Hypothesize | State one falsifiable hypothesis and the prediction that would confirm or refute it | Hypothesis has a concrete, testable prediction |

| 4. Test one variable | Change exactly one thing, run the test, compare to the prediction | Prediction confirmed or refuted; refuted hypotheses are discarded, not recycled |

| 5. Bisect the search space | Narrow via git bisect, binary search on input, or disabling half the config — not linear code reading | Candidate range halves each round |

| 6. Trace backward | Walk the call stack from the crash site back to the original trigger | Triggering call/input identified, not just the frame that crashed |

| 7. Root cause, not proximate cause | Keep asking "why" until the chain reaches something you can actually fix | Chain terminates at a fixable defect (bad state, wrong assumption, missing check) |

| 8. Verify by reverting | Revert the fix and confirm the symptom returns; reapply and confirm it clears | Causation proven in both directions |

### Bisection Techniques by Search Space

| Search space | Technique |

|--------------|-----------|

| Regression across commits | `git bisect` between known-good and known-bad revisions |

| Large/complex input triggers failure | Binary search: halve the input, check which half still fails |

| Behavior depends on config/flags | Disable half the flags/config, narrow to the culprit |

| Unclear which layer owns the bug | Bisect the call stack: instrument the midpoint, check state there |

### Hypothesis Discipline

| Rule | Why |

|------|-----|

| One hypothesis at a time | Multiple simultaneous changes make it impossible to attribute the outcome |

| Prediction must be falsifiable | An untestable hypothesis cannot be confirmed or ruled out |

| Never pattern-match a remembered bug onto new symptoms | Confirmation bias skips the actual evidence in phase 2 |

| A refuted hypothesis is discarded, not adjusted and reused | Adjusting mid-test invalidates the prior result |

---

## Anti-Patterns

| Anti-Pattern | Problem | Instead |

|--------------|---------|---------|

| Forming a hypothesis before reproducing | Guessing wastes cycles on an unconfirmed bug | Reproduce deterministically first |

| Pattern-matching to a remembered similar bug | Misses the actual cause, confirmation bias | Read the actual error/stack/logs fresh (phase 2) |

| Changing multiple things per test | Cannot attribute the result to any one change | Change exactly one variable per test |

| Reading code top-to-bottom to find the defect | Slow, linear, scales poorly | Bisect the search space (phase 5) |

| Stopping investigation at the crash site | Fixes the symptom, not the defect | Trace backward to the original trigger (phase 6) |

| Declaring root cause without reverting the fix | Causation asserted, not proven | Revert, confirm symptom returns, reapply (phase 8) |

---

## Quality Checklist

- [ ] Bug reproduces reliably, and reproduction happened before any hypothesis was formed

- [ ] Investigation cites actual error text/stack/logs, not assumptions or memory of a similar bug

- [ ] Each hypothesis had a falsifiable prediction, and only one variable changed per test

- [ ] The search space was bisected, not scanned linearly

- [ ] The causal chain was traced backward from the symptom through the call stack to the trigger

- [ ] The identified cause is a fixable root cause, not a proximate symptom

- [ ] The fix was verified by reverting it and confirming the symptom returns