# Deliverable Templates ## 1. Requisiti e contesto ```md # [Titolo] ## Contesto ## Requisiti espliciti ## Requisiti impliciti o inferiti ## Vincoli ## Punti aperti ## Evidenze ``` ## 2. Specifiche e fonti ```md # [Titolo] ## Fonti analizzate ## Specifiche rilevanti ## Evidenze osservate ## Inferenze tecniche ## Pattern riusabili ## Gap o adattamenti attesi ## Punti aperti ``` ## 3. Stato dell'arte ```md # [Titolo] ## Scope e baseline ## Commit e fonti analizzate ## Componenti coinvolti ## Funzionalità già implementate ## Configurazione già gestita ## Elementi incompleti ## Rischi ## Evidenze ``` ## 4. Analisi tecnica finale ```md # [Titolo] ## Sintesi esecutiva ## Scope e baseline ## Componenti coinvolti ## Fonti consultate ## Evidenze osservate ## Inferenze tecniche ## Impatti ## Rischi e punti aperti ## Piano tecnico proposto ## Criteri di accettazione ## Validazioni consigliate ## Assunzioni ## Prossimi passi ``` ## Regole di scrittura * Usa italiano quando il contesto è italiano. * Redigi segreti e dati sensibili. * Cita ticket, commit, query, documenti e file in modo verificabile. * Distingui fatti, inferenze, punti aperti e raccomandazioni. * Non dichiarare verificato ciò che non è stato consultato. ### Scrittura human-first 1. La sintesi esecutiva contiene conclusioni, decisioni e rischi principali. 2. Le sezioni tecniche contengono evidenze, motivazioni e limiti; la sintesi non le copia integralmente. 3. Il dettaglio cresce con rischio, complessità e incertezza; informazioni secondarie o non operative sono abbreviate. 4. Fatti, inferenze, punti aperti e raccomandazioni restano distinti. 5. Identificatori come `REQ-01`, `RSK-01` o `VAL-01` sono facoltativi e si usano solo se migliorano la navigazione di deliverable medio-grandi. ## 5. Export Mantis-ready Usa `bug-standard` come formato predefinito; usa `legacy-markdown` solo su richiesta esplicita. Produci esclusivamente testo copy-paste e non creare o modificare ticket. ```md Riassunto: **ARGOMENTO** - ***ARGOMENTO2*** - Descrizione Description Steps To Reproduce # Sviluppi ## Riferimenti tecnici Additional Information ``` Includi `Additional Information` solo se applicabile e `## Riferimenti tecnici` solo se verificabili. Non inventare passi, test, path o impatti. ## 6. Documento da template Google Drive Usa obbligatoriamente il template indicato nelle Instructions. Crea una copia senza modificare l'originale, preserva struttura e stile e indica le sezioni non compilabili. Se il template non è accessibile, usa il messaggio fail-closed delle Instructions. ## 7. Prompt per agente AI Prompt unico, autonomo ed execution-first per un agente di implementazione, consigliato per attività circoscritte, a scope stabile e in una sola fase: deve funzionare copiato 1:1 e anche con il documento di analisi `.md` come riferimento aggiuntivo. ```md # [Titolo] ## Obiettivo operativo ## Repository, branch e baseline ## Contesto minimo e comportamento atteso ## Scope ## File o componenti coinvolti ## Vincoli e attività fuori scope ## Evidenze tecniche essenziali ## Piano incrementale ## Criteri di accettazione ## Test e validazioni ## Rischi e punti aperti ## Analisi di riferimento ``` `Analisi di riferimento` è facoltativa: indica il nome o path noto del documento `.md` disponibile come evidenza e approfondimento, senza sostituire obiettivo, scope, vincoli, piano, criteri di accettazione o test. Non inventare il path. Il prompt resta comprensibile anche senza allegato. Regole: 1. Non copiare integralmente l'analisi umana né la cronologia dell'indagine. 2. Includi solo evidenze che condizionano soluzione, compatibilità, rischio o validazione e riporta repository, branch e baseline. 3. Definisci comportamento atteso, scope e attività fuori scope senza rinvii vaghi o inferenze implicite. 4. Usa istruzioni concrete e incrementali, criteri di accettazione verificabili e test nominali, negativi, edge case, compatibilità e regressione quando pertinenti. 5. Ripeti brevemente vincoli critici nel passo o test pertinente solo quando riduce il rischio di errore; non duplicare descrizioni lunghe. 6. Non inventare file, path, simboli, test o dettagli tecnici e non includere istruzioni di code review o riferimenti automatici a `mcp-code-reviewer`. ## 8. Documento di analisi `.md` Versione file dell'analisi tecnica finale, autonoma, human-readable e utilizzabile come riferimento da un agente di sviluppo. Non è una seconda analisi: deriva dal deliverable finale già validato, ne preserva conclusioni, evidenze, inferenze, rischi, piano e validazioni, rimuove solo framing conversazionale e consolida riferimenti dipendenti dalla conversazione. ```md # [Titolo] Repository: [repository] Branch: [branch] Baseline: [commit, tag o ref] ## Sintesi esecutiva ## Problema e obiettivo ## Comportamento attuale e atteso ## Scope e fuori scope ## Componenti coinvolti ## Evidenze osservate ## Inferenze tecniche ## Vincoli ## Piano tecnico proposto ## Criteri di accettazione ## Validazioni consigliate ## Rischi e punti aperti ``` Generare il documento di analisi `.md` significa creare un artefatto scaricabile nella conversazione; non significa scriverlo nel repository target, modificare file esistenti o eseguire commit o push. Puoi proporre un nome file descrittivo e stabile, ma non un path di destinazione nel repository. Il documento non contiene preamboli o chiusure conversazionali, offerte di export, rinvii vaghi come "come detto sopra" o affermazioni di versione o commit eseguiti. Non riaprire discovery, quality gate o controllo delta per questa trasformazione editoriale. Esegui il solo controllo delta già previsto esclusivamente se la trasformazione cambia materialmente conclusioni, scope, rischi, impatti o validazioni. Il documento deve bastare anche da solo a ricostruire problema e obiettivo, repository/branch/baseline, comportamento attuale e atteso, componenti, evidenze, vincoli e fuori scope, piano, criteri di accettazione, validazioni, rischi e punti aperti. Insieme al prompt, il prompt definisce l'attività e il documento fornisce analisi, evidenze e motivazioni, senza duplicazione integrale. ### Struttura multi-step per attività complesse Per attività complesse, multi-step, con milestone indipendenti, dipendenze tra fasi, checkpoint o validazioni intermedie, preferisci lo stesso documento di analisi `.md` organizzato per step o milestone: resta un singolo artefatto scaricabile. Non imporre questa struttura ai task semplici. ```md # [Titolo] ## Contesto, obiettivo e baseline ## Scope e fuori scope ## Evidenze e vincoli trasversali ## Architettura del piano ## Milestone 1 — [Titolo] ### Obiettivo ### Dipendenze e input ### Attività ### Deliverable ### Criteri di completamento ### Validazioni ### Rischi e punti aperti ## Milestone 2 — [Titolo] ... ## Validazione finale ## Rischi residui ## Handoff ``` Per inventory legacy usa la parity matrix definita in `legacy-system-inventory.md`. Per audit multi-dominio usa il relativo workflow e, prima della consegna, applica il quality gate di `analysis-workflow.md`. ### Diagramma opzionale del piano multi-milestone Usa un diagramma Mermaid solo se il piano ha almeno due milestone distinte e il grafico rende piu' comprensibili sequenza, dipendenze, checkpoint o attivita' parallelizzabili. E' un indicatore grafico per il lettore umano: il testo resta autorevole e deve comunque descrivere milestone, dipendenze, deliverable, criteri di completamento, validazioni, rischi e punti aperti. * Con date, scadenze, finestre o durate gia' disponibili nelle fonti o fornite esplicitamente dall'utente, usa `gantt`; senza tali informazioni usa `flowchart`. Non calcolare, stimare, richiedere o introdurre dati temporali soltanto per generare il diagramma. * Mantieni una riga o un nodo per milestone e ometti dettagli tecnici gia' chiari nel testo. Non aggiungere una matrice delle dipendenze, nuovi identificatori o strutture obbligatorie se le milestone le esprimono gia' adeguatamente. * Non usare `done`, `active` o `crit` senza evidenza esplicita. Non inventare avanzamento, percorso critico, date, durate, percentuali o dipendenze. Esempio senza informazioni temporali: ```mermaid flowchart LR M1["M1 - Fondazione"] --> M2["M2 - Backend"] M1 --> M3["M3 - Frontend"] M2 --> M4["M4 - Integrazione"] M3 --> M4 ``` Esempio con informazioni temporali disponibili: ```mermaid gantt dateFormat YYYY-MM-DD title Piano di integrazione section Milestone Fondazione :m1, 2026-08-03, 5d Backend :m2, after m1, 5d Frontend :m3, after m1, 5d Integrazione :m4, after m2 m3, 3d ``` ## Offerta di export dopo la consegna Dopo aver consegnato un'analisi tecnica Markdown completa, può essere proposta una sola conversione: `Mantis-ready` per ticket copy-paste, `Google Drive` per documento dal template, `prompt per agente AI` per un'attività circoscritta oppure documento di analisi `.md` scaricabile, anche multi-step per attività complesse o con milestone. Mostra l'offerta solo se il formato non era già scelto, il deliverable è convertibile e non è fail-closed, `BLOCCATO` o `ticket-first-light`; non mostrarla per chiarimenti o quando requisiti/template mancanti hanno impedito la generazione. Non generare automaticamente export né implicare accesso a Mantis o Google Drive. `Vuoi anche un export? Mantis-ready per un ticket copy-paste, Google Drive per un documento dal template, prompt per agente AI per un'attività circoscritta oppure documento di analisi `.md` scaricabile, anche multi-step per attività complesse o con milestone.`