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)
- Comando rosso obbligatorio: nessuna ipotesi finché non esiste un comando (test, curl, script) che riproduce il bug e fallisce. Se non riesci a scriverlo, non hai ancora capito il bug
- Dopo il fix lo stesso comando deve passare: è la prova, non una rilettura del codice
- Log di debug sempre con un tag univoco (es.
[DEBUG-a3f9]); prima di chiuderegrep -rn "DEBUG-a3f9"e rimuovili tutti - 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
Idee adattate da mattpocock/skills@59db609 (MIT, © 2026 Matt Pocock).