Przejdź do treści
Biblioteka skilli
Programowanie · Analiza

debug-detective

/debug-detective

Znajduje przyczyny błędów metodą odtworzenia, izolacji, hipotez, bisekcji i weryfikacji, zastępując zgadywanie systematycznym śledztwem opartym na dowodach, także przy regresjach i niestabilnych testach.

Repozytorium
AgentSkills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
14.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
8
Skrypty
1
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

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

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/git_bisect_helper.sh

Co robi i kiedy

Znajduje przyczyny błędów metodą odtworzenia, izolacji, hipotez, bisekcji i weryfikacji, zastępując zgadywanie systematycznym śledztwem opartym na dowodach, także przy regresjach i niestabilnych testach.

Wyzwalacze z opisu

used to workdebugfind the root causefigure out why X happenstrack down
Oryginalny opis (EN)

Systematically root-causes software bugs using a reproduce → isolate → hypothesize → bisect → verify methodology, replacing guess-and-check debugging with a disciplined, evidence-driven investigation. Use this skill when a user reports a bug, a test is failing intermittently or consistently, behavior differs between environments, a regression appeared after a change, something "used to work" and now doesn't, an error/stack trace needs root-causing, or when asked to "debug", "find the root cause", "figure out why X happens", or "track down" a defect. Triggers include crashes, wrong output, flak

Jak działa

  1. Overview
  2. Workflow
  3. Decision Framework: which technique by symptom
  4. Best Practices
  5. Common Pitfalls
  6. Bundled Resources
Sekcje z nagłówków SKILL.md, w oryginale · 90 linii, 1 078 słów
Podgląd SKILL.md
---
name: debug-detective
license: MIT
description: Systematically root-causes software bugs using a reproduce → isolate → hypothesize → bisect → verify methodology, replacing guess-and-check debugging with a disciplined, evidence-driven investigation. Use this skill when a user reports a bug, a test is failing intermittently or consistently, behavior differs between environments, a regression appeared after a change, something "used to work" and now doesn't, an error/stack trace needs root-causing, or when asked to "debug", "find the root cause", "figure out why X happens", or "track down" a defect. Triggers include crashes, wrong output, flaky tests, hangs/deadlocks, memory leaks, performance regressions, heisenbugs, and works-on-my-machine problems.
---

# Debug Detective

## Overview

Debugging fails when it becomes random poking — changing lines, re-running, hoping. This skill enforces a **scientific, evidence-first** process: you never change code to "see what happens" until you have a falsifiable hypothesis backed by an observation. The goal is to find the *root cause*, not to make the symptom disappear.

Keywords: debug, root cause, bug, regression, crash, stack trace, flaky test, intermittent, heisenbug, deadlock, memory leak, race condition, bisect, repro, reproduce, isolate, hypothesis, works on my machine.

Core principle: **A bug you cannot reproduce is a bug you cannot confirm fixed.** Spend your effort earning a reliable reproduction first; everything else gets faster after that.

## Workflow

Follow these phases in order. Do not skip ahead — a fix found by skipping is usually a coincidence, not a cure.

### 1. Capture & Reproduce
- Collect the exact symptom: error message, stack trace, wrong vs. expected output, exit code, screenshot, logs.
- Record the environment: OS, runtime/language version, dependency versions, config, env vars, data, concurrency, time/locale.
- Build a **minimal reliable reproduction** — the smallest command/input that triggers the bug. Note how often it fails (100%? 1 in 20?).
- If it is intermittent, quantify the rate and try to raise it (loop it, add load, shrink timeouts) before proceeding. See `references/intermittent-bugs.md`.
- **Gate:** Do not continue until you can trigger the bug on demand (or have a measured failure rate). Write the repro down.

### 2. Isolate
- Shrink the surface area. Remove inputs, disable features, stub dependencies until the bug still reproduces with the least machinery. (Delta-debugging mindset.)
- Establish the boundary: which layer/module/function is the last place behavior is correct, and the first place it is wrong?
- Add observation points (logging, breakpoints, assertions, `print` of invariants) — observe, don't fix.

### 3. Hypothesize
- State a single, **falsifiable** hypothesis: "The crash happens because `users` is `None` when the cache misses." A good hypothesis predicts an observation you haven't made yet.
- Rank candidate hypotheses by likelihood × cheapness-to-test. Test the cheapest discriminating one first.
- For each, write the prediction *before* you run the experiment. See `references/hypothesis-log.md` for the format and use `templates/investigation-log.md` to track them.

### 4. Experiment / Bisect
- Run the smallest experiment that confirms or refutes the hypothesis. One variable per experiment.
- If a regression ("worked before"), use `git bisect` to find the offending commit. Run `scripts/git_bisect_helper.sh` to automate it with a test command.
- Update the log with the actual result. Refuted hypotheses are progress — they shrink the search space.

### 5. Diagnose Root Cause
- Confirm you can *explain the full causal chain* from root cause to symptom. If there's a gap ("and then somehow..."), you're not done.
- Distinguish the **root cause** from **contributing factors** and the **trigger**. Ask "why" until you reach something actionable (see 5-Whys in `references/root-cause-frameworks.md`).

### 6. Fix & Verify
- Fix the root cause, not the symptom. Prefer the narrowest correct change.
- **Verify:** run the original repro — it must now pass. Then run it the way that previously failed (loop the flaky case, original environment, original data).
- **Regression-guard:** add a test that fails without the fix and passes with it. This is non-negotiable for a real bug.
- Check for siblings: the same root cause often manifests elsewhere. Search the codebase for the same pattern.

### 7. Document
- Record root cause, fix, and how it was verified. Note any latent issues found. Use `templates/investigation-log.md`.

## Decision Framework: which technique by symptom

| Symptom | First move | Key reference |
|---|---|---|
| Consistent crash / exception | Read the full stack trace bottom-up; find the deepest frame in *your* code | `references/techniques.md` |
| "Worked before this change" | `git bisect` | `scripts/git_bisect_helper.sh` |
| Flaky / 1-in-N failure | Raise failure rate, look for shared state / ordering / time / concurrency | `references/intermittent-bugs.md` |
| Wrong output, no error | Binary-search the data pipeline; assert invariants at each stage | `references/techniques.md` |
| Hang / deadlock | Get a thread dump / `py-spy dump`; find who holds what lock | `references/techniques.md` |
| Memory growth | Snapshot heap over time; diff allocations; check unbounded caches/listeners | `references/techniques.md` |
| Works on my machine | Diff the two environments systematically (versions, config, data, locale, TZ) | `references/techniques.md` |
| Performance regression | Profile, don't guess; compare flamegraphs before/after | `references/techniques.md` |

## Best Practices
- **Change one thing at a time.** Multiple simultaneous changes destroy your ability to attribute cause.
- **Write the prediction before the experiment.** Forces honesty and prevents post-hoc rationalization.
- **Trust observations over intuition.** When the data contradicts your mental model, the model is wrong.
- **Read the actual error.** Most "mysterious" bugs are explained in a log line nobody read fully.
- **Keep the repro fast.** Tighten the loop; a 2-second repro lets you run 100 experiments, a 5-minute one lets you run 6.
- **Version-control your investigation.** Commit experimental changes on a scratch branch so you can revert cleanly.
- **Binary search everything** — commits, inputs, config, time ranges. It turns linear searches into logarithmic ones.

## Common Pitfalls
- **Fixing the symptom:** wrapping a `null` in a guard without asking why it was `null`. The real bug moves downstream.
- **Confirmation bias:** running only experiments that support your favorite theory. Design experiments that could *refute* it.
- **Premature fixing:** editing code before you can reproduce. You'll never know if it worked.
- **Heisenbug denial:** adding logging makes it disappear → that's a *clue* (timing/race), not bad luck.
- **Skipping the regression test:** the bug will return and nobody will know it regressed.
- **Tunnel vision on recent changes:** the trigger may be new code, but the root cause can be old latent code newly exercised.
- **Ignoring "it can't be that":** the bug *is* in the place you're sure is correct. That's why you haven't found it.

## Bundled Resources
- `references/techniques.md` — detailed per-symptom techniques, tooling, and language-specific tips.
- `references/intermittent-bugs.md` — playbook for flaky tests, races, and heisenbugs.
- `references/root-cause-frameworks.md` — 5 Whys, fault trees, delta debugging, and the scientific method applied to code.
- `references/hypothesis-log.md` — how to write and rank falsifiable hypotheses.
- `scripts/git_bisect_helper.sh` — automated `git bisect run` wrapper for regression hunting.
- `templates/investigation-log.md` — fill-in template to track a debugging session end to end.
- `examples/null-pointer-investigation.md` — a full worked example from report to verified fix.
Pliki w paczce (8)
  • SKILL.md 8 KB
  • examples/null-pointer-investigation.md 4 KB
  • references/hypothesis-log.md 2 KB
  • references/intermittent-bugs.md 4 KB
  • references/root-cause-frameworks.md 3 KB
  • references/techniques.md 5 KB
  • scripts/git_bisect_helper.sh 4 KB
  • templates/investigation-log.md 2 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · JayRHa/AgentSkills100MIT
Kuan-AI-com/agent-skills100MIT
xinghe-labs/debug-detective100MIT

Migawka bazy z 13.11.2026 · wersja paczki 1ba93d301f35 (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

  • 100systematic-debugging
    Znajduje przyczynę błędów metodą odtwarzania, izolowania, hipotez i weryfikacji, w tym z git bisect, i blokuje ją testem regresji.
  • 90debug-to-root-cause
    Szuka przyczyny źródłowej błędów i niestabilnych testów przez odtworzenie, izolację i weryfikację hipotez przed poprawką.
  • 100debugging
    Prowadzi pętlę odtworzenia, izolacji, dowodu, poprawki i weryfikacji przy błędach, niestabilnych testach i błędach obliczeń naukowych.
  • 100debugging-expert
    Stosuje metodyczną diagnozę błędów i analizę przyczyny źródłowej przy wyjątkach, crashach, błędach sporadycznych, regresjach, git bisect i wyścigach, by zastąpić zgadywanie poprawek.
  • 100debugging
    Prowadzi pętlę odtworzenia, izolacji, dowodu, poprawki i weryfikacji przy błędach, niestabilnych testach, awariach buildu i incydentach produkcyjnych, także w debugowaniu numerycznym i naukowym.
  • 100debug
    Szuka przyczyny źródłowej błędów systematycznie: odtworzenie, izolacja, hipotezy i naprawa z użyciem TDD przy awariach, wyjątkach i regresjach.

Uwagi i zgłoszenia

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