Validazione Documentale & Protocollo "Trust-but-Verify"

Mon, 23 Mar 2026 13:27:55 +0000

🛡️ Validazione Documentale: Il Protocollo “Trust-but-Verify”

Concept: “L’IA genera la bozza, l’Auditor certifica la qualità, l’Umano firma il progetto.”

::: warning IL RISCHIO DELL’ALLUCINAZIONE TECNICA I modelli linguistici sono generatori probabilistici. Senza una validazione rigorosa, c’è il rischio reale di approvare documenti che contengono parametri API inesistenti, diagrammi Mermaid sintatticamente errati per Wiki.js 8.8.2 o requisiti (SRS) che non trovano riscontro nell’architettura (SAD). :::

🎯 Motivazione e Obiettivi

La genesi di questo protocollo risiede nella necessità di eliminare il “debito tecnico documentale”. Un errore in fase di specifica (Design) costa 100 volte più di un bug nel codice.

L’obiettivo è triplice:

Garantire la Coerenza: Assicurarsi che ogni Requisito Funzionale (FR) sia effettivamente implementato nel design.
Validazione Formale: Prevenire errori di rendering dei grafici e link interrotti.
Verifica di Fattibilità: Confermare che le librerie e le tecnologie suggerite esistano realmente e siano compatibili con il nostro hardware (es. Mac Pro 2013).

🏗️ Principi della Validazione Ingegneristica

Il protocollo si basa su tre pilastri fondamentali:

1. Cross-AI Validation (Il Secondo Parere)

Mai usare la stessa sessione di chat o lo stesso modello per generare e validare. Se hai usato Claude 3.7 per il design, usa GPT-4o (o viceversa) per il controllo. Un’IA diversa ha “pregiudizi statistici” differenti e individuerà più facilmente gli errori della prima.

2. Integrità della Tracciabilità (ID Mapping)

Ogni ID requisito (FR-01) deve essere un filo conduttore unico. Se un ID appare nell’SRS ma scompare nell’Implementation Plan, il sistema di governance segnala un’interruzione della catena del valore.

3. Compliance Formale (Mermaid 8.8.2)

Dato che la nostra Wiki.js utilizza una versione specifica di Mermaid, la validazione deve bloccare proattivamente sintassi moderne (come direction o subgraph nidificati) che causerebbero il fallimento del rendering.

🤖 Lo Strumento: Prompt LV_doc_validator_v1

Questo prompt trasforma l’LLM in un QA Software Architect. Carica i documenti prodotti nelle fasi precedenti e lancia questa istruzione.

---
name: LV_doc_validator_v1.md
description: Audit tecnico e validazione di coerenza per la suite documentale ALFO.
---

[RUOLO]
Agisci come un **Senior Technical Auditor** e **QA Software Architect**. Il tuo compito è analizzare criticamente la suite documentale fornita (BRD/PRD, SRS, FSD, SAD, Implementation Plan) per identificare allucinazioni, incoerenze logiche e violazioni dei vincoli tecnici.

[CONTESTO]
Il progetto segue il framework "Design-First". La documentazione deve essere pronta per la pubblicazione su una Wiki (Mermaid 8.8.2) e deve fornire istruzioni inequivocabili per l'implementazione.

[COMPITO - ESEGUI L'AUDIT IN 3 FASI]

### FASE 1: ANALISI FORMALE E SINTATTICA
1. **Mermaid 8.8.2 Check:** Verifica ogni blocco Mermaid. Segnala come ERRORE l'uso di "direction", subgraph nidificati o caratteri speciali non protetti.
2. **ID Traceability:** Scansiona l'SRS e l'Implementation Plan. Ogni ID (FR-x, NFR-x) deve avere una corrispondenza biunivoca. Esistono requisiti orfani?
3. **Placeholder Hunt:** Trova testi come "[TBD]", "...", "[Inserire qui]" o sezioni incomplete.

### FASE 2: ANALISI DI COERENZA (CROSS-DOC)
1. **SRS vs SAD:** Quello che è descritto come requisito funzionale nell'SRS è effettivamente rappresentato nei diagrammi dei componenti o delle classi nel SAD?
2. **Logic Gap:** Esistono flussi descritti nell'FSD che non hanno un supporto architetturale nel SAD?
3. **Tech Stack Alignment:** Le librerie e i framework citati sono coerenti tra i vari documenti?

### FASE 3: VERIFICA EMPIRICA E REALISMO
1. **Hallucination Check:** Le librerie o le API citate sono reali ed esistenti? 
2. **Security & Best Practices:** Sono stati omessi aspetti critici come la gestione dei segreti o la validazione dell'input?
3. **Feasibility:** I requisiti di performance sono realistici per l'hardware dichiarato?

[VINCOLI]
- Sii **estremamente critico**. È meglio un falso positivo che una documentazione errata.
- Non riscrivere i documenti. Elenca solo le criticità trovate.

[OUTPUT]
Inizia con: "Rapporto di Audit Tecnico avviato. Stato della suite documentale: [NON COMPLIANT / PARTIALLY COMPLIANT / READY]"
Fornisci poi l'elenco dei:
- **[CRITICAL]:** Errori bloccanti (Mermaid rotto, ID mancanti, errori logici gravi).
- **[WARNING]:** Suggerimenti di miglioramento o ambiguità.
- **[ACTION PLAN]:** Lista di prompt correttivi da dare all'IA generatrice per risolvere i problemi.

📉 Workflow di Integrazione

graph TD
 A["Suite Documentale Generata"] --> B{"Prompt: LV_doc_validator"}
 B --> C["Generazione Rapporto Audit"]
 C --> D{"Criticità Trovate?"}
 
 D -- "SI: Errori Critici" --> E["Rifinitura con Prompt Correttivi"]
 E --> B
 
 D -- "NO: Solo Suggerimenti" --> F["Validazione Umana Finale"]
 F --> G["Pubblicazione su Wiki.js"]
 
 style B fill:#f9f,stroke:#333
 style G fill:#4CAF50,color:#fff

Tags: #AIValidation #QA #SoftwareArchitecture #Governance #TrustButVerify*

Trustbutverify on GeppettoBarbuto - Wiki