bvandeusenandClaude Opus 5.5
e99f1169f7
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 52s
CI & Build / integration (push) Successful in 1m1s
CI & Build / Python tests (push) Successful in 1m55s
CI & Build / Build & push image (push) Successful in 36s
Step 1 of the Scribe -> Grimoire rename: every capitalised "Scribe" in prose
becomes "Grimoire" ("Fabled Scribe" -> "Fabled Grimoire") across the UI,
the PWA manifest and page title, the MCP instructions and tool docstrings,
hook and skill text, docs and README, with the tests that assert on that
prose moving with it. Old migrations keep their wording.
Identifiers are untouched here: the package, plugin name, MCP server key,
hook file names, env vars, the .scribe marker and FabledScribe repo/image
names move in steps 2 and 3, along with prose that quotes them.
The sweep matched "Scribe" only as a whole word, so describe/subscribe and
friends are untouched. The longer name took the MCP instructions one
character over their 1,600 budget; two phrases are shortened to fit.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
42 lines
2.1 KiB
Markdown
42 lines
2.1 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 Grimoire so it isn't re-debugged from scratch.
|
|
metadata:
|
|
moments: work.debug
|
|
---
|
|
|
|
# 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` Grimoire 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 Grimoire 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`.
|