Debug-skill troubleshooting end-to-end con plan-checker e agent

I bug puntuali si risolvono con la skill debugging da sola. I bug che invalidano decisioni di design durante un execute-phase richiedono di più: skill debugging per investigare, plan-checker GSD per verificare che il fix non rompa il piano restante, agent orchestration per eseguire le modifiche derivate. Questo cluster mostra il pattern end-to-end con un esempio reale dal portfolio.

Disclaimer di indipendenza: non sono affiliato a obra, qrx, o Anthropic. Il pattern descritto è quello che ho consolidato dopo aver fatto un disastro di "fix puntuale" che ha invalidato 2 plan futuri di fase non ancora eseguita.

Il problema: bug a cascata che invalida planning

Esempio dal portfolio (sintesi reale). Durante Wave 3 di una fase passata, executor backend produce errore: l'endpoint che doveva tornare lista risultati restituisce 500 in production-like environment. Bug apparentemente puntuale.

Investigazione skill debugging rivela: la causa è una dipendenza transitiva non gestita su una libreria. Il fix richiede di:

1. Sostituire la libreria.
2. Riscrivere l'adapter che la usava.
3. Aggiornare 2 plan futuri della stessa fase (Wave 4, 5) che assumevano la libreria originale.

Se fai solo step 1+2 (fix puntuale), step 3 esplode quando Wave 4 parte. Devi gestire le conseguenze pre-emptively.

Il pattern end-to-end in 5 step

1. Skill debugging: investigation strutturata, scientific method loop, checkpoint pattern. Output: causa identificata + proposta fix.
2. Pre-fix analysis: prima di applicare il fix, identifica conseguenze. Quali altri plan toccano gli stessi file? Quali decisioni del CONTEXT vengono invalidate?
3. Plan-checker re-run mirato: spawn plan-checker con prompt revision che include il fix proposto. Verifica che fix non rompa altri plan ancora da eseguire.
4. Apply fix + agent orchestration: applica fix. Eventualmente spawn agent paralleli per modifiche derivate (rewrite adapter, update plan futuri).
5. Post-fix verification: re-run test suite, verify nessuna regression. Update STATE.md con la modifica.

Esempio reale: bug i18n hreflang che ha richiesto cascade fix

Riprendo l'esempio del cluster 9202 (Debugging skill) ed espando con la parte end-to-end. Bug: GSC segnala 999+ URL con canonical sbagliato (sv → en bundle). Skill debugging ha identificato causa: 11 lingue runtime servono bundle EN sotto path locale-specific.

Conseguenze a cascata:

1. Fix tecnico: chrome runtime Transloco per 11 lingue.
2. Plan futuri impattati: 3 plan di Phase 17 (Search Console Fix) assumevano hreflang corretto come baseline.
3. Decisione CONTEXT impattata: D-04 i18n hybrid (7 AOT + 11 runtime) doveva essere documentata come "in adozione" prima di Wave successiva.

Workflow end-to-end seguito:

1. Skill debugging (40 min): causa identificata
2. Pre-fix analysis (15 min): trovati 3 plan impattati + 1 decisione CONTEXT
3. Plan-checker iter 2 mirato (10 min):
   - verifica che adozione chrome runtime non rompa Plan 17-01, 17-02, 17-03
   - update CONTEXT.md con D-04 in "decided"
4. Apply fix (45 min): chrome runtime + i18n bulk re-translate 11 lingue
5. Post-fix verification (15 min): hreflang test green, build deploy successful

Total: ~2h 5min wall-clock

Senza il pattern end-to-end avrei applicato fix step 1+2 (~45 min) e lasciato esplodere step 3 al Wave successivo (~ +2-4 ore di debug cascade post-facto).

Quando l'integrazione vale la pena

Tre situazioni dove il pattern end-to-end è giustificato:

1. Bug scoperto durante execute con almeno un plan futuro nella stessa fase ancora da eseguire. Cascade risk alto.
2. Bug che invalida una decisione del CONTEXT.md. La decisione era basata su assunzione errata; va aggiornata prima che downstream plan la riusino.
3. Bug che cambia il threat model (security review). Nuovo threat = aggiornamento threat_model nei plan attivi.

Per bug puntuali (no cascade), skill debugging da sola basta. Non tirare in ballo plan-checker se non c'è cascade rischio.

Quando il pattern è overkill

1. Bug isolato in modulo standalone, no dipendenze cross-plan.
2. Bug in script utility, no impatto su feature production.
3. Bug scoperto al PR review umano (fase plan-phase già chiusa, lo gestisci nel PR feedback).

Anti-pattern: fix puntuale senza considerazione cascade

L'errore peggiore che ho fatto. Bug scoperto in Wave 2, fix applicato in 30 minuti. Tre giorni dopo, Wave 4 parte e fallisce perché il plan assumeva il pattern vecchio. Re-planning d'emergenza, plan-checker iter 3 (raro), commit di "fix-fix" che hanno reso lo storia git confusa.

Mitigazione: routine post-investigation. Anche se ti sembra puntuale, 30 secondi di check sui plan futuri ("toccano gli stessi file? assumono questa libreria?") risparmiano disastri.

Anti-pattern: plan-checker su ogni bug fix

L'opposto: invocare plan-checker re-run per ogni typo fix. Costa 10 minuti di overhead per niente.

Heuristica: plan-checker re-run solo se la pre-fix analysis rivela cascade potenziale. Per bug puntuali, skip.

Coordination fra le tre componenti

Skill debugging, plan-checker GSD, e agent orchestration vivono in sistemi separati ma si coordinano via file:

• Skill debugging produce checkpoint testuale + identifica file da modificare.
• Plan-checker legge i plan attivi + il fix proposto, valuta cascade.
• Agent orchestration spawn executor mirati per modifiche derivate.
• Tutto si committa in git, audit trail consultabile.

Pattern: rollback parziale di plan precedente

Caso avanzato: il bug è in un plan già committato di Wave precedente. Rollback parziale richiesto.

1. git revert su commit specifici (atomic per plan = atomic per revert).
2. Skill debugging + plan-checker + agent producono fix sostitutivo.
3. Re-apply nuovo plan come delta sopra revert.
4. Update STATE.md per riflettere la storia (revert + fix).

Sul mio portfolio ho usato questo pattern 2 volte in 12 mesi. Raro, ma cruciale che funzioni quando serve.

Sessione tipica: tempi totali

• Pattern end-to-end (cascade risk basso): 60-90 min.
• Pattern end-to-end (cascade risk alto, 2-3 plan impattati): 2-4 ore.
• Pattern end-to-end con rollback parziale: 3-6 ore.

Cosa ho imparato scrivendo questo articolo

La lezione principale è: i sistemi separati che si parlano via file sono potenti. Skill debugging non sa di GSD; GSD non sa di skill debugging. Ma tutti e tre lavorano sullo stesso repository, e il file è il contratto comune. Pattern end-to-end emerge da come usi i sistemi, non da come sono progettati internamente.

Secondo insight: la disciplina di pre-fix analysis è il singolo cambio che mi ha risparmiato più ore. Trenta secondi di "chi tocca questi file? quali decisioni impattano?" prima di applicare un fix cattura la maggior parte dei disastri cascade.

Anti-pattern evitati

• Fix puntuale senza analysis cascade. Routine post-investigation 30 secondi è disciplina che paga sempre.
• Plan-checker re-run su ogni bug. Heuristica: solo se cascade risk concreto.

Una storia ricevuta che vale la pena condividere

Sezione segnaposto. Se hai esperienza con bug cascade gestiti bene (o disastrosi), scrivimi a federico@federicocalo.dev.

← Cluster precedente: Cost optimization Prossimo cluster (ultimo): Integrazione Superpowers + GSD →