---
name: debugging-skill
description: Debug riproducibile con metodo scientifico + checkpoint pattern (no scatter-shot fix)
category: debugging
triggers:
  - "bug"
  - "non funziona"
  - "crash"
  - "unexpected behavior"
  - "stack trace"
  - "TypeError"
  - "NullPointerException"
  - "perché"
  - "why doesn't"
license: MIT
author: Federico Calò
---

# Debugging skill

> Forza Claude a **non scatter-shot fix**. Riproduci → ipotizza → testa → fixa.
> Niente cambi multipli "vediamo se funziona". 1 variabile alla volta.

## When to invoke

Auto-invoke quando l'utente:

- Riporta bug (stack trace, comportamento imprevisto)
- Dice "non funziona", "non capisco perché", "ho provato X ma..."
- Chiede di analizzare log/error
- Riporta regressione (funzionava prima)

**Anti-trigger**: chiede "implementa feature nuova" (usa tdd-guide-skill);
chiede review post-code (usa code-reviewer-skill).

## Steps

1. **Reproduce** — chiedi steps di riproduzione minimi. Se utente non
   riesce, prima ottieni repro deterministico. Se solo intermittente, identifica
   pattern (timing, load, dati specifici).
2. **Isolate** — minimal failing case (file, funzione, query). Rimuovi tutto
   quello che non serve.
3. **Hypothesis** — formula 1 ipotesi causa-effetto **falsificabile** (vedi
   [scientific-method.md](references/scientific-method.md)).
4. **Predict** — se ipotesi vera, cosa dovresti osservare? (log specifico,
   DB state, response field).
5. **Test** — un singolo intervento mirato (logging, breakpoint, query). NO
   refactor "while we're here".
6. **Analyze** — confronto risultato vs predizione. Falsifica → torna a step 3.
7. **Fix** — quando root cause confermata, fix minimale + 1 test che la
   coprire (vedi [checkpoint-pattern.md](references/checkpoint-pattern.md)).
8. **Verify regression** — run test suite completa per assicurarsi che il fix
   non rompa altro.

## Anti-patterns

- ❌ "Provo a cambiare questo, mh non funziona, provo a cambiare quello, mh..." —
  questo è scatter-shot. Stop. Formula ipotesi.
- ❌ Cambiare 5 cose insieme. Single variable. Se cambi multi, non saprai
  cosa ha funzionato.
- ❌ Fixare il sintomo (errore in produzione → try/catch silent) invece di
  root cause.
- ❌ "Funziona sul mio PC". Riproduci nell'environment dove fallisce.
- ❌ Skippare il test post-fix. Un bug non testato torna.

## Checkpoint pattern

Quando il debug è lungo (>30 min), checkpoint:

- Cosa ho provato finora (ipotesi → risultato)
- Cosa ho escluso
- Cosa rimane da provare
- Quale è lo stato attuale del code (rollback?)

Questo permette di **non dimenticare** vicoli ciechi già esplorati. Vedi
[checkpoint-pattern.md](references/checkpoint-pattern.md).

## References

- [scientific-method.md](references/scientific-method.md) — metodo scientifico
- [checkpoint-pattern.md](references/checkpoint-pattern.md) — pattern di tracking
  durante sessioni di debug lunghe

## Esempio invocazione

> **User**: "il login non funziona, ricevo 401 random"
>
> **Claude (con debugging-skill)**:
> 1. Reproduce: dammi 3 sessioni consecutive con timestamp + payload + response
> 2. Isolate: solo l'endpoint /auth/login, sempre stesso user
> 3. Hypothesis: clock skew tra client e server fa scadere JWT iat
> 4. Predict: se confronto `iat` JWT vs server time vedrò drift > 30s
> 5. Test: log `iat - server_now` in interceptor
> 6. ...e così via