Plan-checker: risolvere BLOCKER e WARNING iterativamente in GSD

Tra tutte le componenti di GSD, il plan-checker è quella che mi ha cambiato di più il workflow. Non perché trovi sempre cose drammatiche, ma perché trova esattamente quelle cose che il planner ha dimenticato e tu non avresti notato finché non fossero esplose in execute. Ti restituisce piani che non implodono. Cinque minuti di check ti risparmiano tre ore di fix-during-execute.

Disclaimer di indipendenza: non sono affiliato a qrx né ad Anthropic. La descrizione che segue è basata su circa sessanta cicli plan-checker che ho eseguito sul mio portfolio brownfield.

Cosa fa il plan-checker

Dopo che il planner ha prodotto i NN-NN-PLAN.md, il workflow /gsd-plan-phase spawn un sub-agent gsd-plan-checker con accesso in lettura a:

• Tutti i PLAN.md della fase.
• Il CONTEXT.md della fase (decisioni utente lockate).
• Il RESEARCH.md (output researcher).
• UI-SPEC.md e AI-SPEC.md se presenti.
• VALIDATION.md (Nyquist sampling per dimension).
• REQUIREMENTS.md (lista REQ-ID coperti dalla fase).
• PROJECT.md (core value, vincoli globali).

Output: report strutturato con BLOCKER e WARNING per dimensione. Esempio di output (sintesi):

## ISSUES FOUND

BLOCKER (3):
  1. SERIES-CCWF-12 dual-claim - dichiarato in entrambi 20-03 e 20-04 frontmatter
  2. 20-07 scope eccessivo - 6 task, 80h, 108k parole, ~80 file
  3. RESEARCH.md Open Questions non RESOLVED - 4 domande aperte non risolte

WARNING (5):
  1. VALIDATION.md frontmatter outdated (nyquist_compliant: false)
  2. D-04 deroga 18 cluster EN body auto-translate non documentata
  3. ContactController toolPrincipale enum Java/string mismatch frontend
  4. 20-04 Task 3 cornerstone content 3500+ parole stessa sessione (qualità a rischio)
  5. 20-03 ComparativeMatrixComponent rgba hardcoded viola CSS variable policy

Ogni issue ha file:line reference, dimensione affetta, severity, e fix_hint actionable.

Le otto-dieci dimensioni valutate

1. Goal coverage: i N plan portano davvero al goal della fase? Mapping goal element → plan task.
2. Requirement coverage: tutti i REQ-ID elencati nella ROADMAP per la fase appaiono nel frontmatter requirements: di almeno un plan?
3. Decision coverage: tutte le D-XX del CONTEXT + 8 D-EVAL del AI-SPEC + UI-SPEC decisions sono riflesse in task?
4. Task quality: ogni task ha <read_first> +<acceptance_criteria> +<action> con identificatori concreti? Spot-check 3 task per plan, sample 24 task totali.
5. Wave dependencies: la struttura wave è aciclica? Plan della stessa wave hanno file disjoint?
6. Threat model coverage: plan che toccano surface security-relevant hanno blocco <threat_model> con threat ID specifici?
7. must_haves goal-backward: ogni plan declara must_haves derivate dalla phase goal? Non generic.
8. Scope sanity: nessun plan eccede 5 task o ~80 file modificati? Se sì, BLOCKER per splittare.
9. Reuse verification: plan citano file Phase precedenti per reuse pattern? Se assenti, WARNING.
10. CLAUDE.md compliance: plan rispettano vincoli globali (es. light theme only, no AWS, Ollama on-prem only, i18n Pattern A)?

Esempio reale: Phase 20 iter 1

La Phase 20 (la fase che ha pianificato la serie editoriale che stai leggendo) ha avuto iter 1 con 3 BLOCKER + 5 WARNING. Riassunto:

BLOCKER 1: RESEARCH.md aveva sezione "Open Questions (for planner)" con 10 domande aperte, non marcate come RESOLVED. Il planner le aveva implicitamente risolte (es. publishedAt fixato a 2026-10-01T08:00:00Z nei frontmatter), ma 4 questions rimaste senza risposta documentata. Iter 2 ha aggiunto risposte inline e marcato la sezione "(RESOLVED 2026-05-21 - iter 2)".

BLOCKER 2: SERIES-CCWF-12 (Comparative matrix component) era dichiarato in entrambi i frontmatter di 20-03 (component) e 20-04 (data), creando dual-claim. Iter 2 ha rimosso CCWF-12 da 20-03 e lasciato solo in 20-04, aggiungendo test esplicito sticky/accordion mobile in 20-03 spec.

BLOCKER 3: Plan 20-07 aveva 6 task, 80h stima, 108k parole content, ~80 file. Scope sanity check fallito (soglia 5 task / 80 file = BLOCKER). Iter 2 ha splittato in 20-07A (build pipeline + OSS) + 20-07B (cluster 01-09) + 20-07C (cluster 10-18 + linking) = 10 plan totali, ognuno dentro scope sano.

Tempo totale per risolvere i 3 BLOCKER: iter 2 ha richiesto 30 minuti di re-spawn planner Opus. Senza il check, sarei andato in execute con Plan 20-07 mostro che probabilmente avrebbe fallito a metà Wave 4, costandomi ore di debug + replanning d'emergenza.

Il revision loop in pratica

Workflow tipico con plan-checker attivo:

1. /gsd-plan-phase N
2. Researcher spawn → RESEARCH.md prodotto.
3. Planner spawn → N PLAN.md prodotti.
4. Plan-checker spawn → review.
5. Se ## GOAL_MET: tutti i BLOCKER pass, WARNING tollerabili. Workflow chiude.
6. Se ## BLOCKER: lista BLOCKER strutturata. Workflow chiede decisione: retry (re-spawn planner con revision context) o abort.
7. Su retry: iter 2 spawn planner con istruzioni mirate ("fix BLOCKER 1+2+3 per istruzioni X, preserva resto"). Planner produce update plan.
8. Plan-checker re-spawn su plan revisionati. Re-evaluation.
9. Max iter 3. Dopo iter 3 con BLOCKER ancora aperti: force-approve / edit / abandon.

Sul mio campione di 19 phase del portfolio, distribuzione iterations:

• Iter 1 GOAL_MET diretto: ~30% (6 fasi).
• Iter 2 GOAL_MET dopo BLOCKER fix: ~60% (12 fasi).
• Iter 3 GOAL_MET dopo doppia revisione: ~10% (1 fase).
• Iter 3 con BLOCKER non risolvibili: 0.

Quali BLOCKER ricorrono di più?

Pattern frequenti sul mio portfolio:

1. Requirement non coperto: il planner ha dimenticato di mappare un REQ-ID a un plan. Tipicamente perché il REQ-ID era ambiguo o il CONTEXT non lo enfatizzava.
2. Scope eccessivo: plan con 6+ task. Cause: descrizione fase troppo larga, o feature naturalmente bulky che andava splittata in fasi multiple già a livello roadmap.
3. Wave dependency cycle: plan A depends_on B che depends_on A. Cause: planner ha "incrociato" dipendenze plan senza notare il loop.
4. Task vago: action senza identificatori concreti ("align with backend", "make it consistent"). Cause: planner ha produced action di livello strategy invece di tactical.
5. Threat model assente: plan che modifica surface auth / payment / file upload senza blocco threat_model. Cause: planner ha sottovalutato l'esposizione security.

Quali WARNING ricorrono di più?

1. CLAUDE.md compliance soft: es. hardcoded CSS color invece di CSS variable. Risolvibile in execute con piccole edit.
2. Reuse missing reference: plan dovrebbe citare PR di Phase precedente con pattern simile. Se omessa, executor non sa che esiste analog.
3. Scope risk borderline: plan con 4-5 task ma file count alto. Tipicamente WARNING perché executor potrebbe degradare qualità su un singolo task in fondo.
4. Manual checkpoint placement: plan dichiarato autonomous: true ma include task che logicamente richiedono decisione umana. WARNING per chiedere review.
5. Documentation drift: VALIDATION.md draft vs PLAN finali divergono. WARNING per allineare.

Quando WARNING si possono accettare

WARNING non sono BLOCKER: il workflow può procedere senza risolverli, ma è una scelta esplicita. Casi tipici di WARNING accettati:

• WARNING su pattern intenzionali: es. duplicazione documentata fra computeTaxIt e computeTaxFr (non sono duplicazione, sono due funzioni distinte per giurisdizione). Accetto WARNING + documento la ragione in CONTEXT.md.
• WARNING su scope risk borderline: plan con 4-5 task, scope giusto al limite. Procedo accettando il risk, monitorando in execute se qualità degrada. Se sì, splitto in execute.
• WARNING su deroghe esplicite: es. D-04 dice "IT+EN al lancio" ma EN body cluster differiti a Wave 5 auto-translate. Accetto WARNING dopo aver documentato deroga in objective del plan.

Anti-pattern: skip del plan-checker

La tentazione di skippare il check è forte: "lo so io che il piano va bene". Errore. Ho fatto skip per i primi due mesi di GSD, finendo a fix-during-execute con costi 3-5x rispetto al check upfront.

Costo plan-checker: 5-10 minuti, ~15-30k token (su fase media). Costo fix-during-execute di BLOCKER passato inosservato: tipicamente 30-90 minuti per BLOCKER, perché l'execute interrompe + serve replan ad hoc + commit incompleti da rollback. Il calcolo costo-beneficio è cristallino.

Anti-pattern: revision senza priority

Quando il check trova 5+ BLOCKER, la tentazione è chiedere al planner "fix them all". Errore: revision non prioritized produce plan sovra-modificato dove il fix di BLOCKER 1 rompe la mitigation di BLOCKER 3.

Mitigazione: nel prompt revision iter 2, lista i BLOCKER in priorità + separa fix mirato per blocker (e.g., "BLOCKER 1 fix: edit RESEARCH.md add RESOLVED; BLOCKER 2 fix: edit 20-03 frontmatter remove CCWF-12; ..." con istruzioni operative concrete invece di "fix the issues"). Planner produce update mirate, niente rewrite massiccio.

Integrazione con must_haves

Ogni plan dichiara must_haves nel frontmatter: truth conditions che devono essere true al termine dell'execute. Plan-checker verifica che must_haves siano derivate dalla phase goal (goal-backward check), non generiche.

Esempio illustrativo:

must_haves:
  truths:
    - LeadMagnetController endpoint POST /api/v1/lead-magnets/{magnetId}/download
      restituisce 200 + PDF stream per magnetId ∈ enum whitelist (5 nuovi
      Phase 20 IDs)
    - Bucket4j rate limit 10 req/min per IP attivo su endpoint
    - ButtondownNewsletterAdapter.subscribeToListWithTags() chiamato
      atomically con download (testato in IT)
    - Test green: LeadMagnetIdPhase20Test + LeadMagnetControllerPhase20IT +
      PdfLeadMagnetRendererPhase20IT

Queste sono truth verificabili post-execute, non aspirazioni. Il verifier (gsd-verifier) le checka dopo execute completato.

Cosa ho imparato scrivendo questo articolo

La lezione principale è sul costo di skip. Per due mesi ho pensato che il plan-checker fosse overhead. Era la cosa che mi separava da workflow stabile a workflow sempre-in-crisi. Skip ti sembra ti far guadagnare cinque minuti, in realtà te ne costa novanta.

Secondo insight: la qualità delle BLOCKER trovate dipende dalla qualità degli input. Se CONTEXT.md è ricco (27 D-XX ben articolate, come Phase 20), il check trova issue precise. Se CONTEXT.md è povero (5 decisioni vaghe), il check non ha appigli per essere severo, e i plan passano BLOCKER-free ma sono comunque cattivi. Investire in discuss-phase ripaga in plan-checker effectiveness.

Anti-pattern evitati

• Skip "perché sono di fretta". La fretta è esattamente il momento in cui plan-checker ti salva da debug futuri.
• Revision "fix all" generica. Sempre prioritized, sempre con fix instructions operative invece di descrizione del problema.

Una storia ricevuta che vale la pena condividere

Sezione segnaposto. Se hai esperienza con plan-checker che ti ha salvato (o non ha trovato un BLOCKER importante che è poi esploso), scrivimi a federico@federicocalo.dev. Le storie pseudonimizzate entrano nei cluster successivi.

← Cluster precedente: ROADMAP-driven planning Prossimo cluster: Agent orchestration →