---
name: systematic-debugging
description: Use when diagnosing a bug, failure, or unexpected behavior — investigate methodically instead of guessing. Triggers on "why is this failing/breaking", a stack trace, a flaky test, or any "it should work but doesn't". On resolution, capture the issue in Scribe so it isn't re-debugged from scratch.
---

# Systematic debugging

Find the *root cause*, don't patch the symptom. Move one step at a time — a
guessed fix that "seems to work" often just moves the bug somewhere else.

## Recall first

Before digging in, `search` Scribe for the symptom — a prior issue
(`list_tasks(kind="issue")` or `search`) may already hold the cause and the fix.
Don't re-debug what's already solved.

## The loop

1. **Reproduce** — get a reliable, minimal repro. If you can't reproduce it, you
   can't confirm you fixed it.
2. **Observe** — read the actual error / log / state. Don't theorize past the
   data you have.
3. **Isolate** — narrow to the smallest failing case; change one variable at a
   time so each result actually means something.
4. **Hypothesize → test** — state the single most likely cause, then test *that
   one thing*. Confirm or rule it out before moving on; don't stack guesses.
5. **Root cause** — keep going until you can explain *why* it failed, not just
   what made it stop. "It works now" without "because X" is unfinished.
6. **Fix + verify** — fix the cause, then re-run the repro to confirm it's gone.

## Capture the issue (so it's findable)

When resolved, record it in Scribe as its own issue (`create_task(kind="issue")`):
**symptom → root cause → fix → how it was verified** in the body, optionally
linked to the task it arose from (`arose_from_id`) and the subsystem it touches
(`system_ids`). Even a problem fixed in passing is worth two lines — that's how
the next person (or you) avoids re-deriving it. Record it discretely; don't bury
it as a work-log line on an unrelated open task. If the work was already tracked
as its own task, log the resolution there and set it `done`.