Mole Debug

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:

1. Exact error — Full error message, stack trace, HTTP status code. Not a summary.
2. Exact steps — What sequence triggers the failure? Write them down.
3. Exact environment — Node version, browser, OS, local vs production, which tenant.
4. 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.

# Find the entry point
gf --agent func "functionName"
gf --agent search "POST /api/endpoint"

# Trace imports and impact
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.

1. Regression test — Already done in SURFACE. Lives permanently in CI.
2. Root cause comment — Brief comment at fix site explaining WHY, not WHAT.
3. Class-of-bug analysis — Could this happen elsewhere? Search for similar patterns:

# If schema/query mismatch, check ALL queries
gf --agent search "SELECT.*content.*FROM posts"
# If missing tenant scope, check ALL tenant queries
gf --agent search "FROM posts WHERE"  # Missing tenant_id?

4. 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

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 patterns
• references/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. ⛏️