bvandeusen
5fbee18a94
CI & Build / Python lint (push) Successful in 3s
CI & Build / integration (push) Successful in 15s
CI & Build / TypeScript typecheck (push) Successful in 34s
CI & Build / Python tests (push) Successful in 46s
CI & Build / Build & push image (push) Successful in 1m3s
Plan #825 (T2 — Issues task_kind) shipped S1–S4 but its S5 docs slice never landed, so every behavioral surface the plugin pushes to the agent still described the pre-kind convention ("tag `issue`" on a create_note). Result: agents fixed bugs without reaching for kind=issue and dumped the work as logs on unrelated open tasks. - _INSTRUCTIONS: rewrite the "record a problem" bullet to create_task(kind="issue") with symptom→cause→fix + arose_from_id / system_ids, and an explicit "not a work-log on an unrelated task"; add Issue + System to the hierarchy section. - skills/systematic-debugging, verification: drop "tag `issue`" / create_note-issue, point at create_task(kind="issue"). - skills/using-scribe: add issues/systems to the entity list + reflex #6. - hooks/scribe_static_context: fix → its own issue on the keyless floor. Instance-agnostic, prose-only; no schema or tool-behavior change. Pairs with always-on rule #118. Issue: #855. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
40 lines
2.0 KiB
Markdown
40 lines
2.0 KiB
Markdown
---
|
|
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`.
|