debug
/debug
Bada przyczynę źródłową systematycznie, wymaga dowodu przed poprawką i generuje test regresyjny przy błędzie, awarii lub nieprzechodzącym teście.
- Autor
- tansuasici ↗
- Repozytorium
- claude-code-kit ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 21.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 21.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Bada przyczynę źródłową systematycznie, wymaga dowodu przed poprawką i generuje test regresyjny przy błędzie, awarii lub nieprzechodzącym teście.
Oryginalny opis (EN)
Systematic root-cause debugging with evidence-before-fix enforcement and regression-test generation. Use when chasing a bug, failing test, error, crash, or unexpected behavior — before attempting a fix.
Jak działa
- Core Rule
- When to Use
- Process
- Output Format
- Common Error Patterns
- Common Rationalizations
- Notes
Podgląd SKILL.md
---
name: debug
description: Systematic root-cause debugging with evidence-before-fix enforcement and regression-test generation. Use when chasing a bug, failing test, error, crash, or unexpected behavior — before attempting a fix.
user-invocable: true
---
# Debug
## Core Rule
Form a single hypothesis at a time. Validate with a falsifiable test before fixing. Never patch a symptom you haven't reproduced.
## When to Use
Invoke with `/debug` when:
- A bug has been reported or observed and needs systematic investigation
- A test is failing and the cause isn't obvious
- Something "just stopped working" and you need to find out why
- Previous fix attempts haven't resolved the issue
- You want to ensure the fix includes a regression test
## Process
### Phase 1: Reproduce
Before investigating, establish a reliable reproduction:
1. **Get the symptoms** — exact error message, stack trace, unexpected behavior
2. **Get the trigger** — what action causes the bug? What input?
3. **Reproduce locally** — can you make it happen on demand?
4. **Identify consistency** — does it always happen, or is it intermittent?
If you cannot reproduce the bug, do NOT guess at fixes. Instead, add logging/instrumentation to gather more data.
### Phase 2: Hypothesize
Form hypotheses based on evidence, not intuition:
1. **Read the error** — what does the error message actually say?
2. **Read the stack trace** — where exactly does it fail?
3. **Check recent changes** — `git log --since='3 days ago'` — did something change?
4. **Check the language pattern lookup** — if the error matches a category in `references/error-patterns.md`, use it to seed hypotheses (do not blindly accept; verify against the actual code)
5. **Form 2-3 hypotheses** — rank by likelihood
```markdown
### Hypotheses
1. [Most likely] — DB query returns null when user has no orders → NPE on line 45
2. [Possible] — Race condition between auth check and data fetch
3. [Less likely] — Timezone mismatch in date comparison
```
### Phase 3: Investigate
Test each hypothesis systematically:
1. **Start with the most likely hypothesis**
2. **Gather evidence** — read the relevant code, check logs, add temporary logging
3. **Narrow the scope** — binary search: which layer? which function? which line?
4. **Confirm or reject** — does the evidence support this hypothesis?
5. **Move to next hypothesis** if rejected
**Rules:**
- Do NOT fix anything yet — investigation only
- Do NOT change code to "see if this helps"
- Every investigation step must produce evidence
- If you're guessing, you don't understand the bug yet
### Phase 4: Root Cause
Document the confirmed root cause:
```markdown
### Root Cause
**What**: [one sentence description]
**Where**: [file:line]
**Why**: [why does this code behave this way?]
**When**: [under what conditions does this trigger?]
**Evidence**: [how we confirmed this is the cause]
```
The root cause must explain ALL observed symptoms. If it doesn't, keep investigating.
### Phase 5: Fix
Only after root cause is confirmed:
1. **Design the fix** — what's the minimal change that addresses the root cause?
2. **Check for related issues** — does this bug exist elsewhere? (same pattern in other files)
3. **Implement the fix** — one focused change
4. **Verify the fix** — reproduce the original bug → confirm it's gone
5. **Check for regressions** — run the full test suite
**Rules:**
- One fix per commit
- Fix the root cause, not the symptom
- Don't refactor surrounding code in the same commit
- If the fix is complex, explain why in the commit message
### Phase 6: Regression Test
Write a test that:
1. **Fails without the fix** — reproduces the exact bug scenario
2. **Passes with the fix** — confirms the fix works
3. **Tests the edge case** — not just the happy path
4. **Is named descriptively** — describes the bug scenario, not the fix
```text
test("returns empty array when user has no orders instead of throwing NPE")
```
## Output Format
```markdown
# Debug Report
## Bug
**Symptom**: [what the user sees]
**Trigger**: [what action causes it]
**Reproducible**: Yes/No/Intermittent
## Investigation
### Hypothesis 1: [description]
- Evidence: [what we checked]
- Result: Confirmed / Rejected
### Hypothesis 2: [description]
- Evidence: [what we checked]
- Result: Confirmed / Rejected
## Root Cause
**What**: [description]
**Where**: file:line
**Why**: [explanation]
**Evidence**: [how we confirmed]
## Fix
**Change**: [description of the fix]
**Files**: [modified files]
**Commit**: [commit hash]
## Regression Test
**Test**: [test name and location]
**Verifies**: [what the test checks]
## Related Issues
- [Other places this pattern exists, if any]
```
## Common Error Patterns
When forming hypotheses in Phase 2, consult `references/error-patterns.md` for language-specific lookup tables of frequently-misdiagnosed errors and their common root causes.
Loaded on-demand — only when the error message matches a category in the table. For unfamiliar errors, fall back to first-principles investigation rather than guessing from the table.
## Common Rationalizations
| Rationalization | Reality |
|---|---|
| "I know what the bug is, I'll just fix it" | Reproduce first. Assumption-based fixes are wrong ~30% of the time and create new bugs. |
| "The failing test is probably wrong" | Read the test. If it's wrong, fix it. If it's right, fix your code. Never skip. |
| "It works locally, CI must be flaky" | Environments differ. Reproduce in CI conditions before dismissing. |
| "I'll add logging later" | Intermittent bugs without logging become permanent mysteries. Add instrumentation now. |
| "The stack trace points to X, so X is broken" | Stack traces show where the error surfaces, not where it originates. Trace upstream. |
## Notes
- The #1 rule: **no fix without confirmed root cause** — guessing leads to patches that mask bugs
- Evidence-before-fix is non-negotiable — if you can't explain why the fix works, you don't understand the bug
- Intermittent bugs need more logging, not more guessing — add instrumentation first
- If the bug is in a dependency, document the workaround and file an upstream issue
- Each debug session should improve the codebase's debuggability (better error messages, logging, assertions)
Pliki w paczce (2)
- SKILL.md 6 KB
- references/error-patterns.md 2 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · tansuasici/claude-code-kit | 100 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| nicsuzor/academicops | 100 | MIT |
| duronext/jig | 100 | MIT |
| drosam/agents | 100 | MIT |
| rizukirr/vibekit | 100 | MIT |
| DingyangLyu/MatClaw | 100 | Apache-2.0 |
| Kanevry/session-orchestrator | 100 | MIT |
| kdlbs/kandev | 100 | AGPL-3.0 |
Migawka bazy z 13.11.2026 · wersja paczki a48b79f12210 (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
Wymaga badania przyczyny przed poprawką błędu, awarii, nieudanego testu lub regresji, bez zajmowania się nowymi funkcjami. - 100systematic-debugging
Wymusza zbadanie przyczyny przed poprawką błędu, awarii lub nieudanego testu, bez zajmowania się nowymi funkcjami. - 100systematic-debugging
Wymaga znalezienia przyczyny źródłowej przed próbą poprawki przy każdym błędzie, awarii lub nieoczekiwanym zachowaniu, bo naprawa samych objawów zawodzi. - 100systematic-debugging
Znajduje przyczynę źródłową błędu, nieudanego testu lub nieoczekiwanego zachowania przed jakąkolwiek poprawką, także gdy poprzednia naprawa nie zadziałała lub błąd wraca. - 90systematic-debugging
Szuka przyczyny źródłowej i naprawia błąd, gdy użytkownik zgłasza awarię, błąd, nieoczekiwane zachowanie lub niezaliczony test. - 100systematic-debugging
Szuka przyczyny błędu i awarii przed poprawką; przy awarii produkcji najpierw działa według planu reakcji na incydent.