ROADMAP-driven planning: horizontal vs vertical phasing in GSD

Quando inizi un nuovo progetto, una delle prime decisioni con GSD è come strutturare la ROADMAP: fasi orizzontali (per layer/dominio tematico, parallelizzabili) o fasi verticali (slice end-to-end, una feature alla volta). La risposta cambia tutto: come parallelizza il team, come si misura il progresso, dove si annidano i rischi.

Disclaimer di indipendenza: non sono affiliato a qrx né ad Anthropic. Uso GSD da circa un anno sul mio portfolio brownfield, con diciannove fasi orizzontali eseguite. Su un side project greenfield più piccolo ho sperimentato la modalità MVP vertical per quattro fasi iniziali e poi sono passato all'orizzontale.

La ROADMAP come fonte di verità

ROADMAP.md è il file più letto in una sessione GSD. Ogni comando slash che spawn un sub-agent (researcher, planner, plan-checker, executor) inizia leggendo la ROADMAP per capire dove sei, dove vai, quali fasi precedenti hanno chiuso. Senza ROADMAP coerente, GSD perde la spina dorsale.

Struttura essenziale di una entry ROADMAP:

### Phase 21: Add OAuth Google login + Stripe webhook for subscription refresh

**Goal**: Implementare login OAuth Google + webhook Stripe per refresh subscription
quando l'utente cambia metodo di pagamento, mantenendo backward compat con il login
email/password esistente.

**Depends on**: Phase 10 (Stripe integration base), Phase 16 (auth JWT)

**Requirements**: AUTH-04, AUTH-05, PAY-12, PAY-13

**Plans**: TBD (run /gsd-plan-phase 21)

**Mode**: standard | mvp

Il campo Mode determina se il planner organizzerà la fase in horizontal layers (default standard) o in vertical slice (mvp).

Horizontal phasing: fasi tematiche per dominio

Una fase orizzontale è dedicata a un dominio/layer specifico: tutto il backend di una feature, tutto il frontend, tutta l'infrastruttura. I plan dentro la fase sono spesso parallelizzabili perché toccano file disgiunti.

Esempio: Phase 20 del portfolio (la fase di scrittura di questa serie) è strutturata orizzontalmente:

Wave 1: 20-01 (infrastruttura: script + test stub + config)
Wave 2: 20-02 (backend lead-magnet) ∥ 20-03 (frontend components)
Wave 3: 20-04 (cornerstone) ∥ 20-05 (sub-page SP) ∥ 20-06 (sub-page GSD)
Wave 4a: 20-07A (build pipeline + OSS)
Wave 4b: 20-07B (cluster 01-09) ∥ 20-07C (cluster 10-18 + linking)
Wave 5: 20-08 (i18n bulk + Lighthouse + verify)

Wave 2 e Wave 3 hanno plan paralleli: backend non tocca file frontend, le tre career page toccano cartelle separate. Lo speedup misurato è tipicamente 3-5x rispetto a un'esecuzione sequenziale.

Pro horizontal

• Parallelism alto: più sub-agent (o developer) in parallelo su layer diversi.
• Modularità: ogni fase tocca un dominio chiaro; più facile assegnare review a chi conosce quel dominio.
• Risk isolation: un problema nel backend non blocca lo sviluppo del frontend in altra fase.
• Test infrastructure dedicata: una fase "test setup" può scaffold tutto il framework di test prima delle fasi di feature.

Contro horizontal

• Visibility utente bassa: il valore concreto (feature usabile) arriva tardi, dopo che N fasi orizzontali si sono allineate.
• Integration risk alto: backend e frontend devono incastrarsi alla fine. Disallineamenti emergono a integrazione, non subito.
• Stakeholder confusion: chi non è developer non capisce perché "siamo a metà del progetto e non c'è ancora nulla da cliccare".

Vertical slice: feature end-to-end

Una fase verticale tocca tutti i layer per portare una feature dal DB al UI. Esempio: "Add user signup" come fase singola include schema DB + backend endpoint + email send + frontend form + test e2e.

In GSD si attiva con /gsd-plan-phase N --mvp (one-shot) o mettendo Mode: mvp nella entry ROADMAP (persistente). Il planner riceve istruzioni di organizzare i plan come slice (UI → API → DB per ogni feature) invece che come layer.

Su una fase MVP iniziale di nuovo progetto, GSD emette anche SKELETON.md - il "walking skeleton" che scaffold tutto il progetto + routing + un read/write DB reale + un'interaction UI reale + deployment dev. È il primo deliverable end-to-end che dimostra che la pipeline funziona.

Pro vertical

• Time-to-value veloce: ogni fase produce feature usabile. Stakeholder vedono progresso continuo.
• Integration testata da subito: il flow end-to-end gira da Wave 1; integration bug emergono presto.
• Risk validation: scopri subito se il tuo stack scelto funziona davvero su un task realistico.
• Greenfield-friendly: niente legacy da rispettare, hai libertà di scegliere la slice giusta.

Contro vertical

• Parallelism limitato: una slice è naturalmente sequenziale (DB → backend → frontend). Difficile parallelizzare se non ci sono slice indipendenti contemporanee.
• Repetition: pattern simili (es. CRUD per N entity) vanno ripetuti per ogni slice invece di scaffold una volta.
• Brownfield difficile: forzare slice end-to-end su un legacy esistente significa toccare layer multipli per ogni fase, con risk regression.

Decision matrix: quale scegliere?

Migrare da horizontal a vertical (o viceversa)

GSD supporta entrambe le modalità per fasi diverse dello stesso progetto. Il campo Mode nella entry ROADMAP è per-fase. Una transizione tipica:

1. Phase 1-3: MVP greenfield, Mode: mvp, vertical slice.
2. Phase 4+: post-MVP scaling, Mode: standard, horizontal layers.

Sul portfolio brownfield ho avuto la transizione inversa: phase 1-10 (i fondamentali) erano horizontal, poi Phase 15 (OSS didattico Trittico) è vertical perché ogni progetto OSS è feature end-to-end indipendente (Spring Boot app clone, Stripe clone, Twitter clone), e parallelism fra progetti non aggiunge valore.

Wave-based parallel execution (horizontal)

Il vantaggio principale di horizontal sono le wave. Ogni NN-NN-PLAN.md ha un campo wave: nel frontmatter. Plan con la stessa wave + file disjoint sono indipendenti = parallelizzabili.

Esempio di frontmatter PLAN typical:

---
plan_id: 20-02
phase: 20
wave: 2
depends_on: [20-01]
files_modified:
  - backend/src/main/java/.../leadmagnet/LeadMagnetController.java
  - backend/src/main/java/.../leadmagnet/LeadMagnetId.java
  - backend/src/test/java/.../leadmagnet/*.java
autonomous: true
requirements: [SERIES-CCWF-05, SERIES-CCWF-06, SERIES-CCWF-07]
---

Il workflow /gsd-execute-phase legge tutti i PLAN, raggruppa per wave, verifica che file_modified siano disjoint, e spawn executor paralleli per ogni plan dentro la stessa wave.

Walking skeleton (vertical, prima fase greenfield)

Quando --mvp è attivo + Phase 1 + nessuna fase precedente conclusa = GSD attiva la modalità walking skeleton. Il planner emette SKELETON.md oltre ai PLAN.md: è una checklist del minimo end-to-end che la fase deve produrre per essere considerata "fondazione".

Tipicamente: project scaffold + routing + un read DB reale + un write DB reale + un'interaction UI reale + deployment in env dev. Niente stub, niente mock - tutto reale. Quando lo skeleton cammina, sai che pipeline funziona; da lì in poi aggiungi muscoli (feature) senza ridiscutere lo scheletro.

Anti-pattern: roadmap che cresce senza struttura

Errore comune: aggiungere fasi senza tematizzarle. La ROADMAP diventa una lista di trenta entry random ("Add login", "Fix nav bug", "Refactor X service", "Add OAuth", "Update docs"). Senza tematica chiara:

• Parallelism diventa impossibile (non sai cosa è indipendente da cosa).
• Stakeholder confusi (non c'è narrativa).
• Plan-checker fallisce su scope sanity (fasi mescolano UI + DB + infra).

Mitigazione: rivedi la ROADMAP ogni quarter, raggruppa entry tematiche, promuovi a "pilastri" (es. Infrastructure, Authentication, Payment, i18n) e organizza fasi sotto i pilastri. L'esercizio richiede 30-60 minuti e ripaga in chiarezza per mesi.

Anti-pattern: fasi sovradimensionate

Fasi che "fanno tutto" sono difficili da pianificare e da eseguire. Plan-checker GSD ha BLOCKER su scope sanity: una fase con plan da 6+ task o 80+ file modificati viene rifiutata. Risposta corretta: splittare in fasi multiple.

Esempio reale dal portfolio: Phase 20 originale era pianificata come 8 plan ma il piano 20-07 conteneva 18 articoli da 6000 parole + build pipeline + 2 OSS repos = 108k parole content + ~80 file. Plan-checker iter 1 ha flaggato BLOCKER. Iter 2 ha splittato 20-07 in 20-07A (build + OSS) + 20-07B (cluster 01-09) + 20-07C (cluster 10-18 + linking) = 10 plan totali, ognuno dentro scope sano.

Sessione tipica: pianificare una nuova fase

Workflow operativo per aggiungere una fase:

1. /gsd-phase <descrizione> - crea la entry ROADMAP.
2. /gsd-discuss-phase N - adaptive Q&A per CONTEXT.md.
3. (opz.) /gsd-ui-phase N - UI design contract.
4. (opz.) /gsd-ai-integration-phase N - AI design contract.
5. /gsd-plan-phase N - spawn researcher → planner → plan-checker.
6. /gsd-execute-phase N - esecuzione wave-based.
7. /gsd:verify-work N - verifica goal-backward.

Tempo medio per pianificare una fase orizzontale media: 60-120 minuti (compreso discuss + research + plan + checker iter 1-2). Esecuzione varia da 4-8 ore per fasi piccole a 200+ ore per fasi mostro come Phase 20.

Cosa ho imparato scrivendo questo articolo

La lezione principale è sulla narrativa. La ROADMAP non è solo un task tracker, è la storia del progetto raccontata in fasi tematiche. Una ROADMAP ben strutturata permette a un nuovo contributor (umano o LLM) di capire in cinque minuti dove siamo e perché. Una ROADMAP disordinata richiede ore di archeologia per ricostruire il contesto.

Secondo insight: la modalità MVP vertical è seducente in greenfield ("ship rapido!") ma deve essere abbandonata appena il progetto cresce. Continuare vertical su un brownfield maturo significa accettare slowdown sostanziale. La transizione horizontal va fatta esplicitamente, non "scivolando" - altrimenti finisci con fasi metà-vertical metà-horizontal che confondono tutti.

Anti-pattern evitati

• Modalità implicita. Non lasciare il campo Mode ambiguo. Dichiara esplicitamente standard o mvp per ogni fase. Default GSD è standard, ma esplicitare aiuta i contributor futuri.
• ROADMAP che cresce post-facto. Aggiungere fasi solo quando servono produce una ROADMAP che riflette il caos. Meglio pianificare 6-12 mesi avanti con fasi tematiche, anche se ad alto livello, e raffinare quando arrivi vicino.

Una storia ricevuta che vale la pena condividere

Sezione segnaposto. Se hai esperienza con MVP vertical che è poi dovuto diventare horizontal (o viceversa), scrivimi a federico@federicocalo.dev. Le storie pseudonimizzate sui momenti di transizione strutturale entrano nei cluster successivi.

← Sub-page GSD Prossimo cluster: Plan-checker iterativo →