thomascasali Debugging sistematico
Principio: la causa radice prima del fix. I fix sui sintomi falliscono.
Quando si attiva questa skill
- L'utente segnala un errore, eccezione, stack trace, test fallito, comportamento inatteso
- Una funzione "non funziona", "non parte", "dà errore"
- Sono già stati tentati 2+ fix senza successo → STOP e riparti dalla fase 1
- Una regressione (prima funzionava, ora no)
Le 4 fasi
1. Investigazione causa radice
Prima di proporre QUALSIASI fix:
- Leggi l'errore per intero (stack trace completo, non solo la prima riga)
- Riproduci il bug in modo consistente — se non lo riproduci, non lo hai capito
- Controlla i commit recenti (
git log --oneline -20,git diff HEAD~5) per identificare la regressione - Traccia il flusso dei dati a ritroso dall'errore fino alla sorgente
- Attraversa i confini di sistema: frontend → API → DB, app → servizio → log
2. Analisi del pattern
- Cerca un esempio funzionante simile nel codebase (
grepper pattern simili) - Confronta riga per riga le differenze
- Identifica le dipendenze (versioni pacchetti, env vars, config files, ordine di inizializzazione)
3. Ipotesi e test
- Formula UNA ipotesi specifica e falsificabile ("se cambio X, il bug sparisce perché Y")
- Testa cambiando UNA sola variabile alla volta
- Verifica il risultato prima di procedere
4. Implementazione
- Se possibile, scrivi prima un test che fallisce
- Applica UN fix che indirizzi la causa radice
- Verifica che il fix risolva il problema E che non rompa altro
Red flag che richiedono restart dalla fase 1
Se ti senti pensare:
- "Fix veloce per ora, indagine dopo"
- "Provo a cambiare X e vediamo"
- "Aggiungo un try/catch per nascondere l'errore"
- "Il problema sembra essere..." (senza prove)
→ Torna alla fase 1.
Stop rule
Se 3 fix consecutivi falliscono, ferma i tentativi e metti in discussione l'architettura o le tue assunzioni di base. È un sintomo di problema strutturale, non di bug isolato.
Anti-pattern da evitare
- Cambiare codice "per vedere se funziona"
- Commentare codice che dà fastidio invece di capire perché
- Aggiornare dipendenze sperando che il bug sparisca
- Suggerire all'utente "prova a riavviare" senza diagnosi
- Dichiarare risolto senza eseguire il caso di riproduzione