Fable Debugging Method

The expensive failure mode isn't "can't find the bug" — it's fixing the wrong thing confidently: a signal that pattern-matches a known failure but has a different cause. Restarting services, deleting caches, and rewriting code before understanding the fault destroys the evidence and sometimes the system.

The loop

1. Reproduce first. If you can't trigger it on demand, you're not debugging — you're guessing. Capture the exact command/input/state that shows it. For flaky issues, find the frequency ("3 in 10 runs") before changing anything.
2. Read the actual error. The full text, the stack trace, the line numbers. Not the summary of it. Half of all debugging time is wasted by skipping this step. If there's no error, add observability before forming theories: log the inputs at the boundary, log the state at the suspected fork.
3. Bisect the pipeline. Every bug lives between a point where data is known-good and a point where it's known-bad. Find both endpoints, then binary-search the middle. Never start in the middle.
4. One hypothesis, one test, one variable. Write the hypothesis down ("the webhook fires twice, so the row is duplicated"). Design the cheapest observation that would falsify it. Change ONE thing. If you changed two things and it works, you still don't know what the bug was — and it will return.
5. Fix the cause, then re-trigger the original repro. A fix isn't verified because the code looks right; it's verified because the reproduction now passes AND you can explain why it failed before.
6. Hunt siblings. The same mistake is usually made in 2-3 places. Grep for the pattern before closing.

Before any state-changing "fix" (restarts, deletes, config edits, cache clears)

Ask: what evidence do I have that THIS action addresses THIS cause? "It usually works" is not evidence. If the honest answer is "none, but it might help" — gather evidence first. State-changing actions without a diagnosis convert a debuggable system into an undebuggable one.

Distinguish the four bug species early

• Deterministic logic bug → bisect the data path. Fastest to fix.
• State/environment bug (works on fresh clone, fails here) → diff the environments before touching code: versions, env vars, caches, disk, permissions.
• Concurrency/timing bug (flaky) → look for shared mutable state, missing awaits, double-fired handlers, race between write and read. Add sequence logging with timestamps; never "fix" flakiness with sleeps.
• Somebody-else's-cache bug (fixed it but still broken) → you're looking at stale output, not a live failure. See traps below.

Environment traps (check these before doubting your code)

• Edge/CDN caches lie. Shopify and CloudFront serve stale content minutes after a deploy. Verify fixes via computed style / curl with cache-buster / origin check — never by eyeballing the cached page.
• Shopify Dawn div:empty — empty divs are hidden by theme CSS; a "missing" spacer element isn't missing, it's hidden. Fix with padding on #MainContent.
• An external SSD formatted exFAT over USB: two concurrent ffmpeg jobs throw transient I/O errors that look like corrupt files. Serialize renders, and retry once before diagnosing deeper.
• ImageMagick silently drops SVG paths with CSS-class fills. Blank/partial logo renders aren't your SVG — render natively via qlmanage instead.
• Vite env vars: changing .env requires a dev-server restart; VITE_* values are baked at build time in production — a stale build explains "the env change did nothing".
• Tailwind v4 cascade layers: an unlayered third-party @import beats every utility class. If a utility "doesn't apply", check layer order before specificity.
• launchd services (Jarvis): a crash-looping service throttles itself; launchctl list | grep <label> for the exit code, logs in the plist's StandardErrorPath — not in Console alone.
• ffmpeg filter graphs: overlay inputs must be LAST in the graph or drawtext bleeds through layers below (the V2.1 chapter-card bug). Visual artifacts in composites → check filter order first.
• macOS Gatekeeper/quarantine on downloaded binaries: "command not found"/instant-kill on a binary that exists → xattr -d com.apple.quarantine.

When stuck (30+ minutes, no progress)

• Re-read the error from scratch as if new. You've been filtering it through the wrong theory.
• State out loud what you know vs what you assume. Test the oldest assumption — it's usually the wrong one.
• git stash / fresh clone / fresh build: distinguish "my code" from "my environment" in one move.
• Write the minimal repro in isolation (20 lines, no framework). If it doesn't reproduce, the bug is in the wiring, not the logic.
• Check the version. The doc you're reading may describe a different major version than the one installed.

Report format

When reporting a diagnosis: symptom → root cause (with the evidence that proves it) → fix → how it was verified → sibling locations checked. If tests still fail or the fix is partial, say exactly that — never round "mostly fixed" up to "fixed."