Przejdź do treści
Biblioteka skilli
Programowanie · Testowanie

mole-debug

/mole-debug

Prowadzi systematyczne debugowanie przez hipotezy: odtwarza błąd, śledzi przepływ danych, zawęża problem bisekcją, naprawia go z testem nieprzechodzącym i zabezpiecza przed nawrotem.

Repozytorium
Lattice ↗
Licencja
AGPL-3.0
Ostatnia zmiana repozytorium
13.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
3
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

Co robi i kiedy

Prowadzi systematyczne debugowanie przez hipotezy: odtwarza błąd, śledzi przepływ danych, zawęża problem bisekcją, naprawia go z testem nieprzechodzącym i zabezpiecza przed nawrotem.

Wyzwalacze z opisu

t be found, or
Oryginalny opis (EN)

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.

Jak działa

  1. When to Activate
  2. The Dig
  3. Quick Decision Guide
  4. MUST DO
  5. MUST NOT
  6. References
Sekcje z nagłówków SKILL.md, w oryginale · 200 linii, 1 103 słów
Podgląd SKILL.md
---
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._ ⛏️
Pliki w paczce (3)
  • SKILL.md 8 KB
  • references/debugging-strategies.md 4 KB
  • references/grove-debugging-patterns.md 4 KB

Wersje

W bazie nie ma innych skilli o nazwie mole-debug.

Identyczna treść występuje jeszcze w 1 innych folderach na GitHubie. Tu pokazujemy jedną, najlepiej ocenioną kopię.

Migawka bazy z 13.11.2026 · wersja paczki 4860350200c6 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90debugging
    Prowadzi systematyczne debugowanie: odtworzenie, badanie, hipotezy i poprawkę z weryfikacją przy błędach i regresjach.
  • 100bugs
    Opisuje katalog incydentów Mole dotyczących bezpieczeństwa czyszczenia, ograniczonych sond, anulowania, zgodności dry-run i bramek akcji, przy diffach wrażliwych na bezpieczeństwo.
  • 100dev-bug
    Odtwarza błąd, znajduje przyczynę na podstawie dowodów, a potem naprawia go wraz z testem regresji.
  • 90investigate
    Prowadzi systematyczne debugowanie: szuka przyczyny źródłowej i śledzi hipotezy przy błędach oraz testach.
  • 81shadow-debug
    Diagnozuje i naprawia zgłoszony błąd: odtwarza objaw, szuka przyczyny i sprawdza poprawkę testem regresji.
  • 100debug
    Prowadzi systematyczne debugowanie: najpierw odtworzenie błędu, potem test, który się nie udaje, na końcu poprawka.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.