Skip to content
Skills Library
Programming · Testing

mole-debug

/mole-debug

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.

Repository
Lattice ↗
Licence
AGPL-3.0
Last repository change
13.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.10.2026, without references to retired models or APIs.

Licence

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

What it does and when to use it

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.

Triggers from the description

t be found, or
Original author 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.

How it works

  1. When to Activate
  2. The Dig
  3. Quick Decision Guide
  4. MUST DO
  5. MUST NOT
  6. References
Original SKILL.md headings · 200 lines, 1,103 words
SKILL.md preview
---
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:**

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.

```bash
# 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)
```

```bash
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:

```bash
# 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.

```bash
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 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._ ⛏️
Files in this package (3)
  • SKILL.md 8 KB
  • references/debugging-strategies.md 4 KB
  • references/grove-debugging-patterns.md 4 KB

Versions

The database has no other skills named mole-debug.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 4860350200c6 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90debugging
    Systematic root-cause debugging: reproduce, investigate, hypothesize, fix with verification. Use when asked to "debug this", "fix this bug", "why is this failing", "troubleshoot", or mentions errors, stack traces, broken tests, flaky tests, regressions, or unexpected behavior.
  • 100bugs
    Mole incident catalog for cleanup safety, bounded probes, cancellation, dry-run parity, and actionable gates. Use for a Mole safety-sensitive diff; not for docs, release notes, or generic review.
  • 100dev-bug
    Use for bugs and debugging. Triggers include "bug", "debug", "why is X happening", "not working", "this is broken". Two entries, both covered - a bug is listed, or debugging only (may find no bug). Reproduces first, explains in plain terms, finds the root cause from evidence,…
  • 90investigate
    Systematic debugging skill. Use when encountering a bug, test failure, unexpected behavior, or when asked to "investigate", "debug", "diagnose", or "figure out why". Enforces root-cause-first discipline with structured hypothesis tracking.
  • 81shadow-debug
    Diagnose and fix a reported failure using a reproducible symptom, a focused cause investigation, and regression verification. Use for broken behavior, errors, crashes, or failing checks.
  • 100debug
    Systematic debugging workflow: reproduce first, write failing test, then fix. Use when encountering bugs, unexplained errors, or unexpected behavior.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.