Ingest-docs synthesizer: consolidare 60+ documenti di planning in contesto coerente

Quando entri in un brownfield maturo, la documentazione di planning è tipicamente sparsa: roadmap pubbliche dell'anno scorso, ADR vecchi, decisioni nei commit message, RFC nei wiki. Senza un consolidamento, GSD parte da context fragmentato e produce piani che non rispettano decisioni già prese. Il comando /gsd:ingest-docs esiste esattamente per questo: sintetizza N docs sparsi in PROJECT.md + REQUIREMENTS.md + ROADMAP.md coerenti.

Disclaimer di indipendenza: non sono affiliato a qrx né ad Anthropic. Ho usato ingest-docs sul portfolio brownfield Q2 2026 per consolidare ~60 documenti di planning sparsi in docs/05_strategy/02_roadmap/ nel master plan unico 08_piano_master_2026.md.

Il problema: docs sparsi in brownfield

Un progetto vivo da 2-3 anni accumula docs di planning in posti diversi:

• ADR (Architecture Decision Records) in docs/adrs/
• Roadmap pubbliche in docs/strategy/
• RFC interni in wiki o Notion
• Decisioni nei commit message lunghi
• Issue tracker (Jira / GitHub) chiusi con motivazioni
• Documenti Word/PDF da meeting strategy

Senza consolidamento, GSD non sa che la decisione X è stata già presa nel 2024 e tu rifai la discussione da capo. Peggio, prende decisione contraria senza accorgersi.

Cosa fa /gsd:ingest-docs

Spawn un sub-agent gsd-doc-classifier per ogni documento individuato, poi un gsd-doc-synthesizer aggrega gli output. Workflow tipico:

1. Trova tutti i markdown sotto path indicato (default: docs/**/*.md).
2. Per ognuno, classifier estrae: type (ADR / PRD / SPEC / DOC), title, scope summary, cross-references, status, decisions[].
3. Synthesizer aggrega N classification JSON in singolo contesto.
4. Applica regole di precedenza (data più recente vince a parità di autorità; decisione LOCKED esplicita vince su decisione tentative).
5. Produce sintesi in PROJECT.md (core value + decisioni chiuse) + REQUIREMENTS.md (REQ-IDs categorizzati) + ROADMAP.md (fasi se inferibili).
6. Produce INGEST-CONFLICTS.md con 3 buckets di issue da risolvere.

I tre buckets di INGEST-CONFLICTS.md

L'output principale per il debug del consolidamento è il file conflicts:

1. Auto-resolved: conflitti risolti automaticamente per regole di precedenza. Esempio: due ADR sullo stesso topic, ADR-2024-12 e ADR-2026-03 - vince il più recente. Lista per audit, non richiede azione.
2. Competing-variants: equa autorità, non risolvibili automaticamente. Esempio: ADR-2025-07 dice "use PostgreSQL", ADR-2025-09 dice "use MongoDB" (stesso quarter, stesso autore). Escalation utente: scegli quale è vincolante.
3. Unresolved-blockers: decisioni LOCKED in conflitto diretto. Esempio: PROJECT.md dichiara "stack Java", REQUIREMENTS dichiara REQ con "implementare in Python". Hard-block: GSD si rifiuta di proseguire senza decisione esplicita utente.

Esempio reale: consolidamento master plan portfolio

Sul portfolio ho usato ingest-docs per produrre 08_piano_master_2026.md dai 60+ documenti di planning sparsi in docs/05_strategy/02_roadmap/ (vecchie roadmap, decisioni prese tra il 2024 e il 2026, piani per pilastri tematici, ecc.). Risultato sintesi:

• 1.329 righe di master plan consolidato.
• 18 fondamenti A-R identificati come pilastri strategici.
• 13 conflitti auto-resolved (versioni successive di policy che superavano le precedenti).
• 4 competing-variants: scelta consulting ricorrente vs spot, soglia P.IVA forfettaria, freelance EU vs USA, monetization tier breakdown.
• 0 unresolved-blockers: planning preesistente coerente nelle decisioni LOCKED.

Tempo totale ingest: ~3 ore (spawn classifier per 60 docs paralleli, poi synthesizer). Senza ingest avrei impiegato giorni di letture manuali per ricostruire stessa coerenza.

Regole di precedenza built-in

Il synthesizer applica regole nell'ordine:

1. Status: superseded / rejected / deprecated → scartati. Proposed → warning. Accepted → considerato.
2. Data: a parità di status, data più recente vince.
3. Esplicità: decisione marcata "LOCKED" o "BINDING" vince su decisione "tentative" o "exploratory".
4. Autorità: ADR > design doc > commit message > issue comment.
5. Specificità: decisione su scope specifico vince su decisione su scope generale per quel scope.

Se due decisioni passano tutti i livelli a parità, finiscono in competing-variants (escalation utente).

Pattern: ingest periodico per audit

Sul portfolio uso ingest-docs anche fuori dal contesto onboarding, come audit periodico trimestrale:

1. Lancia ingest su docs/**/*.md + .planning/phases/*/[A-Z]*.md.
2. Confronta sintesi nuova con PROJECT.md attuale.
3. Diff = decisioni nuove (committate nei docs ma non riflesse in PROJECT) + decisioni vecchie superseded.
4. Aggiorna PROJECT.md.

L'audit trimestrale cattura decisioni prese "al volo" nei docs ma mai formalizzate nel master state.

Anti-pattern: ingest su docs non strutturati

ingest-docs funziona bene su markdown con struttura riconoscibile (ADR con frontmatter, PRD con header standard, design doc con sezioni esplicite). Funziona male su:

• Stream-of-consciousness markdown (note random senza struttura). Il classifier produce sintesi vaghe, synthesizer non sa cosa è decisione vs cosa è note.
• Docs storici con stile espositivo (es. "Once upon a time we decided X but then in 2024 we changed to Y because..."). Difficile estrarre decisione canonical.
• Slide deck convertite a markdown (bullet points senza contesto). Mancano rationale e references.

Mitigazione: pre-processing pre-ingest. Riformatta docs informali in ADR-like skeleton con sezioni esplicite (decision, status, context, consequences) prima di ingest.

Pattern: ingest per cluster tematico

Su docbase grossi (100+ file), invece di ingest globale, ingest per cluster tematico:

1. Ingest docs/security/**/*.md → sintesi security in PROJECT §Security.
2. Ingest docs/i18n/**/*.md → sintesi i18n in PROJECT §i18n.
3. Ingest docs/deploy/**/*.md → sintesi deploy in PROJECT §Deploy.

Cluster mantiene context window basso, classifier più accurato perché ha topic disambiguato. Trade-off: cross-cluster references vanno gestite manualmente (es. decisione security che impatta deploy).

Quando NON usare ingest-docs

1. Greenfield project: niente da consolidare. Inizia con /gsd:new-project direttamente.
2. Brownfield con docs già consolidati: se hai docs/00-master.md coerente, ingest produrrebbe duplication senza valore.
3. Docs in formato proprietario non convertibile: se la docbase è in formato che non puoi facilmente convertire a markdown, ingest non parte. Investi tempo in conversion prima.

Sessione tipica: ingest brownfield

Workflow:

1. Identifica path docs da consolidare (es. docs/strategy/ + docs/adrs/).
2. Verifica docs siano in markdown. Convert non-markdown via pandoc/jq.
3. Lancia /gsd:ingest-docs docs/strategy/ docs/adrs/.
4. Attendi spawn classifier paralleli (N docs in parallelo, Sonnet).
5. Synthesizer produce PROJECT.md draft + REQUIREMENTS.md draft + INGEST-CONFLICTS.md.
6. Revisiona INGEST-CONFLICTS.md: risolvi competing-variants + unresolved-blockers.
7. Approva PROJECT.md draft come canonical.

Tempo per docbase 60 file: 2-3 ore wall-clock. Senza ingest: giorni di consolidamento manuale.

Cosa ho imparato scrivendo questo articolo

La cosa che mi ha colpito di più è quanto fosse frammentaria la mia stessa documentazione di planning prima dell'ingest. Pensavo di "averla in mente"; ingest ha rivelato 13 conflitti auto-risolvibili (decisioni superseded che non avevo mai marcato) + 4 competing-variants vere. La sintesi ha richiesto 3 ore; senza, avrei continuato a pianificare su base incoerente.

Secondo insight: ingest-docs è uno strumento di disciplina, non solo di consolidamento. Sapere che ogni trimestre passerai i tuoi docs attraverso ingest ti spinge a scrivere ADR più strutturati, decisioni con status esplicito, rationale tracciabile. Il fatto che esista lo strumento migliora la docbase upstream.

Anti-pattern evitati

• Ingest senza pre-processing. Docs non strutturati producono sintesi vaghe. Investi 30 minuti a riformattare i 5-10 docs critici in ADR-like prima di ingest.
• Skip INGEST-CONFLICTS.md. Il file è dove vivono le decisioni vere. Skipparlo significa perdere il valore del consolidamento.

Una storia ricevuta che vale la pena condividere

Sezione segnaposto. Se hai usato ingest-docs su docbase complesse, scrivimi a federico@federicocalo.dev.

← Cluster precedente: Wave-based parallel execution Prossimo cluster: Memory management auto-curated →