| name | mole-debug |
| description | Systematic debugging through methodical hypothesis-driven investigation. The mole follows vibrations to their source. Use when something is broken and nobody knows why, tests fail for unclear reasons, bugs are reported but can't be found, or "it works on my machine." Reproduces first, traces data flow, binary searches the problem space, fixes with a failing test, and seals against recurrence. |
The Mole ⛏️
The mole works in the dark. It doesn't need to see — it feels. Vibrations travel through the earth, and the mole follows them to their source with absolute patience. It never guesses. It never panics. It digs methodically, one tunnel at a time, testing the soil ahead before committing.
When to Activate
- User says "debug this," "why is this failing," "something's broken," or "find this bug"
- User calls
/mole-debug or mentions mole/debug/investigate/diagnose
- Tests are failing and the cause isn't obvious
- A bug was reported but nobody can locate it
- "It works locally but fails in production" or "it works on my machine"
- Intermittent failures, flaky tests, race conditions
- Error messages that don't point to the actual problem
IMPORTANT: The Mole ALWAYS reproduces first. If you can't make it fail on demand, you haven't started debugging — you're just guessing.
Pair with: beaver-build for regression tests after fix, panther-strike when the bug is already located, bloodhound-scout for understanding unfamiliar code paths, eagle-architect when the Three-Burrow Threshold triggers
The Dig
FEEL → DIG → TUNNEL → SURFACE → SEAL
↓ ↓ ↓ ↓ ↓
Repro- Trace Hypo- Fix Prevent
duce Data thesis with Recur-
Issue Flow Test Test rence
Phase 1: FEEL
The mole presses its paw against the earth. Something trembles beneath...
Reproduce the issue. Get it to fail on demand. No reproduction, no debugging.
Reproduction checklist:
- Exact error — Full error message, stack trace, HTTP status code. Not a summary.
- Exact steps — What sequence triggers the failure? Write them down.
- Exact environment — Node version, browser, OS, local vs production, which tenant.
- Minimal reproduction — Strip away everything unnecessary. Find the smallest case that still breaks.
If you CANNOT reproduce: Widen the search (different browsers, tenants, data states). Check for race conditions. Check git history: git bisect narrows the window.
Record the vibration in a Vibration Log (see references/debugging-strategies.md for template).
Output: A reliably reproducible failure, or a clear statement of what blocks reproduction.
Phase 2: DIG
The mole begins to dig. Not frantically — deliberately...
Trace the data flow from entry to exit. Instrument the boundaries.
Place sensors at strategic points — boundaries between systems, not scattered throughout code. Use [MOLE:LOCATION] labels so you can find and remove them later.
gf --agent func "functionName"
gf --agent search "POST /api/endpoint"
gf --agent usage "ServiceName"
gf --agent impact "src/lib/server/services/affected-file.ts"
For Grove-specific debugging patterns (routes, D1, KV, auth, build), see references/grove-debugging-patterns.md.
For detailed instrumentation techniques, see references/debugging-strategies.md.
Output: A map of the data flow with instrumentation at key boundaries.
Phase 3: TUNNEL
The mole chooses a direction. One tunnel. One hypothesis...
Form hypotheses. Test ONE at a time. Binary search the problem space.
CRITICAL: Never change two things between test runs. One variable at a time. Binary search is logarithmic — for a 16-layer call chain, it finds the fault in 4 steps.
Track every hypothesis in the Vibration Log:
Hypothesis 1: [description]
Test: [what you did]
Result: [CONFIRMED / REFUTED — why]
The Three-Burrow Threshold
HARD RULE: After 3 failed fix attempts in different locations, STOP.
Three failures in three different places = architectural problem, not isolated bug. Surface and call eagle-architect for an aerial view. Document everything in the Vibration Log.
Output: Either a confirmed root cause, or a Three-Burrow escalation with full documentation.
Phase 4: SURFACE
The mole breaks through to daylight...
Write a failing test that demonstrates the bug. Then fix the code. Then the test passes.
This order is mandatory:
1. Write test that reproduces the bug → TEST FAILS (proves bug exists)
2. Fix the code → TEST PASSES (proves fix works)
3. Run full affected CI → ALL TESTS PASS (proves nothing else broke)
pnpm install
gw ci --affected --fail-fast --diagnose
Output: A passing test that proves the bug is fixed, and clean CI.
Phase 5: SEAL
The mole packs the earth behind it, sealing the tunnel forever...
Prevent recurrence.
- Regression test — Already done in SURFACE. Lives permanently in CI.
- Root cause comment — Brief comment at fix site explaining WHY, not WHAT.
- Class-of-bug analysis — Could this happen elsewhere? Search for similar patterns:
gf --agent search "SELECT.*content.*FROM posts"
gf --agent search "FROM posts WHERE"
- Clean up — Remove ALL
[MOLE:*] debug logging. The mole seals its tunnels.
gf --agent search "MOLE:"
Output: Sealed tunnel. Regression test. Root cause documented. Class-of-bug checked. Debug instrumentation removed.
Quick Decision Guide
| Symptom | Approach |
|---|
| Test fails, error is clear | Skip to SURFACE — write the fix test, fix it |
| Test fails, error is cryptic | FEEL (reproduce) then DIG (trace data flow) |
| "Works on my machine" | FEEL (compare environments), DIG (check configs) |
| Intermittent failure | FEEL (find trigger pattern), DIG (state snapshots) |
| "It used to work" | Time-travel: git bisect to find breaking commit |
| 500 error, no useful message | DIG (instrument boundaries), check server logs |
| Multiple tests failing | Check common dependency — may be architectural |
| "Everything is broken" | Three-Burrow likely — escalate to Eagle immediately |
MUST DO
- Reproduce the bug before attempting any fix
- Write a failing test before writing the fix
- Test one hypothesis at a time
- Use the Vibration Log to track all attempts
- Binary search the problem space
- Remove all debug instrumentation before committing
- Check for the same class of bug elsewhere
- Run
gw ci --affected --fail-fast --diagnose before considering complete
- Respect the Three-Burrow Threshold
MUST NOT
- Scatter console.logs randomly (instrument boundaries strategically)
- Change multiple variables between test runs
- Fix the symptom instead of the root cause
- Skip reproduction ("I think I know what's wrong")
- Leave debug logging in the codebase
- Commit a fix without a regression test
- Dig past the Three-Burrow Threshold without escalating
References
references/grove-debugging-patterns.md — SvelteKit/Cloudflare-specific patternsreferences/debugging-strategies.md — Detailed techniques (binary search, boundary instrumentation, state snapshots, git bisect, hypothesis tracking, Vibration Log template)
The earth is quiet now. The vibration has stopped. Somewhere beneath the grove, a sealed tunnel marks where the mole found the truth. ⛏️
