Redazione guidata dalla spec: perché batte il ChatGPT generico

Redigere documenti complessi e regolamentati — policy, narrative di controllo, report CAPA, pacchetti di autorizzazione — con un’interfaccia chat generica è allettante: incolli un prompt e ottieni una bozza. Il problema è coerenza, struttura e conformità. I prompt occasionali non impongono workflow, non eseguono controlli e non danno al modello un modo per correggersi. La redazione guidata dalla spec in Rakenne capovolge la situazione: gli skill definiscono workflow, caricano riferimenti e usano estensioni così che l’agente possa validare, correggere e mantenere la qualità. Questo articolo spiega perché questo approccio è di gran lunga migliore del “normale prompting su ChatGPT” e mostra esempi concreti e confronti di output.

Perché la spec batte il prompting ad hoc

In breve: la redazione guidata dalla spec dà al LLM una spec (workflow + riferimenti + struttura) e strumenti (estensioni) per controllare e correggersi. Il prompting generico no.

Come gli skill Rakenne implementano la redazione guidata dalla spec

In Rakenne ogni skill è un piccolo pacchetto che l’agente pi può attivare. Di solito include:

1. SKILL.md — Nome, descrizione (quando usarlo) e un workflow: passi ordinati (es. definisci scope → carica riferimento → redigi → valida).
2. Riferimenti — File Markdown (standard, elenchi criteri, schemi) che l’agente carica quando lo skill è attivo, così la bozza resta allineata alle fonti ufficiali.
3. Estensioni (opzionale) — Strumenti TypeScript registrati con l’agente (extension.ts) che eseguono controlli deterministici sul documento (copertura, gate logici, completezza). L’agente li invoca, legge il risultato e revisiona finché i controlli non passano.

Il contesto di progetto (tipo documento, dominio, glossario) vive in AGENTS.md nel workspace, così ogni conversazione in quel progetto ha lo stesso perimetro.

Qui sotto usiamo skill Rakenne reali per illustrare workflow, controlli e auto-correzione, poi confrontiamo gli output.

Esempio 1: Policy medicinali HIQA (workflow + riferimento)

Skill: HIQA Designated Centre Medication . Redige una policy sui medicinali per i centri designati irlandesi allineata agli standard HIQA.

Workflow nello skill:

1. Definisci scope — Tipo di centro, autosomministrazione vs medicinali somministrati, procedure esistenti.
2. Carica riferimento — Leggi references/hiqa-nssbh.md per NSSBH Theme 3 (cura sicura, sicurezza dei medicinali).
3. Redigi — Produci una policy che copra: ordinazione, conservazione, prescrizione, somministrazione, autosomministrazione, schede MAR, errori/incidenti, smaltimento, formazione, revisione.
4. Riferimento incrociato — Allinea con segnalazione incidenti e pianificazione assistenza/supporto.

Il file di riferimento specifica gli otto temi HIQA e le aspettative di governance così l’agente non indovina.

Rakenne (con lo skill): L’agente segue il workflow, attinge NSSBH Theme 3 e i testi di governance correlati dal riferimento e produce una policy con sezioni nominate (ordinazione, conservazione, somministrazione, errori, formazione, ecc.) e allineamento esplicito a “NSSBH Theme 3” e contesto “designated centre”.

ChatGPT generico: Potresti chiedere: “Scrivi una policy sui medicinali per una casa di cura in Irlanda.” Il modello restituisce spesso una “policy medicinali” generica applicabile ovunque: “revisione periodica”, “personale appropriato” vaghi, nessun legame con HIQA o NSSBH. Nessuna garanzia che il Theme 3 (o conservazione, MAR, errori, smaltimento) sia coperto in modo sistematico e nessun passaggio integrato “carica riferimento poi redigi”.

Esempio 2: Narrative di controllo SOC 2 (workflow + strumenti di validazione)

Skill: SOC 2 Control Narrative Author . Costruisce la documentazione SOC 2 con narrative di controllo, mappatura TSC e segnaposto per le evidenze.

Workflow:

1. Scope — Quali categorie TSC (Security sempre; opzionalmente Availability, PI, Confidentiality, Privacy).
2. Narrative di controllo — Per ogni criterio in scope (CC1–CC9, A1, PI1, C1, P1–P8): narrativa + riferimento evidenza.
3. Evidenze — Aggiungi segnaposto evidenza per narrativa.
4. Valida — Esegui le estensioni e correggi finché non passano.

Strumenti di estensione:

• check_trust_services_criteria_coverage — Verifica che ogni criterio TSC in scope abbia una narrativa e un riferimento evidenza; segnala criteri non mappati.
• soc2_narrative_reliability_check — Applica il Rubric SOC 2 Reliability: segnala frasi vaghe (“revisionato periodicamente”, “il management mantiene la sicurezza”) e spinge verso specificità (chi, come, quando, dove, tecnologia nominata).

Rakenne (con lo skill): L’agente redige le narrative poi esegue entrambi gli strumenti. Se CC4 non ha riferimento evidenza o la narrativa dice “l’accesso è revisionato periodicamente”, gli strumenti restituiscono FAIL con riscontri concreti. L’agente revisiona (aggiunge evidenza, specifica “trimestralmente dal team sicurezza tramite report accessi IdP”) e riesegue finché PASS.

ChatGPT generico: Chiedi “narrative di controllo SOC 2 per Security”. Ottieni spesso testo che menziona “controlli” e “policy” ma non copre sistematicamente CC1–CC9, non mappa ogni criterio a narrativa + evidenza e usa proprio il tipo di linguaggio vago che il rubric rifiuta (“revisionato periodicamente”, “controlli appropriati”). Nessun controllo automatizzato: lacune e vaghezza emergono solo in fase di preparazione audit.

Esempio 3: Report CAPA (workflow + gate logici)

Skill: CAPA Report . Report di azioni correttive e preventive per non conformità (ISO 9001 / ISO 13485).

Workflow:

1. Non conformità — Rilevazione, scope, contenimento.
2. Causa radice — Completa una sezione 5 Whys (Why 1 … Why 5). Non proporre azioni finché non è fatto.
3. Gate — Esegui root_cause_logic_gate sul documento. Procedi solo quando passa.
4. Azioni correttive / preventive — Azioni, responsabili, scadenze.
5. Implementazione — Registra il completamento.
6. Verifica di efficacia — Imposta una data futura per la verifica. Esegui verification_of_effectiveness_timer prima di chiudere; non chiudere finché non passa.

Strumenti di estensione:

• root_cause_logic_gate — Verifica la presenza di una sezione Causa radice / 5 Whys e di almeno cinque livelli why distinti. Fallisce se il documento salta alle “soluzioni” prima di un 5 Whys corretto.
• verification_of_effectiveness_timer — Assicura che esista una data di verifica di efficacia e che sia nel futuro. Evita di chiudere la CAPA prima che la verifica sia pianificata.

Rakenne (con lo skill): L’agente redige non conformità e causa radice. Se ha solo tre livelli why o salta a “formeremo il personale”, il gate restituisce FAIL con “Livelli why rilevati: 3/5. Completa un’analisi 5 Whys prima di proporre soluzioni.” L’agente aggiunge Why 4 e Why 5, riesegue il gate, poi prosegue con le azioni. Prima di chiudere deve impostare una data di efficacia futura; se mette “2025-01-15” e oggi è dopo, il timer fallisce e l’agente deve impostare una data futura.

ChatGPT generico: Chiedi “una CAPA per un rilievo di audit sulla gestione documentale”. Spesso ottieni un unico paragrafo di causa e un elenco di azioni in un colpo — nessun 5 Whys imposto, nessun gate, nessun controllo che la verifica di efficacia sia pianificata nel futuro. L’output sembra plausibile ma non passerebbe una revisione ISO 9001/13485 rigorosa.

Esempio 4: Pacchetto di autorizzazione FedRAMP (workflow + controllo completezza)

Skill: FedRAMP Authorization Package . SSP, allegati, SAP, SAR, POA&M.

Workflow (semplificato): Categorizza il sistema → descrizione del sistema → perimetro di autorizzazione → flussi di dati → implementazioni controlli (con riferimento baseline) → allegati SSP → Valida con fedramp_package_completeness_check. Correggi e riesegui finché PASS. Sotto-workflow separati per SAP/SAR e POA&M, con lo stesso strumento usato per segnalare controlli mancanti, sezioni allegati mancanti o voci POA&M senza piano di remediation o scadute senza giustificazione.

Rakenne (con lo skill): L’agente segue il workflow, carica i riferimenti baseline e allegati, redige le sezioni ed esegue il controllo di completezza. Le lacune (es. controlli non implementati senza giustificazione, sezione PIA mancante) vengono segnalate; l’agente le colma e rivalida.

ChatGPT generico: Chiedi “un SSP FedRAMP per un prodotto SaaS”. Ottieni un lungo racconto che può sembrare un SSP ma non segue la struttura FedRAMP reale, l’implementazione controllo per controllo né la checklist degli allegati. Nessun modo per verificare la copertura della baseline o la completezza degli allegati; scopri le lacune dopo manualmente.

Riassunto: stesso modello, risultati diversi

Il LLM sottostante può essere lo stesso. La differenza è come viene usato:

• Prompting generico: Una tantum o a botta e risposta senza workflow fisso, senza riferimenti autorevoli caricati dallo skill, senza strumenti di validazione. L’output è generico, la struttura deriva e il modello non può “controllare e correggere” in modo affidabile.
• Guidato dalla spec in Rakenne: Gli skill definiscono workflow, riferimenti e estensioni. L’agente segue il workflow, carica i riferimenti giusti, redige poi esegue strumenti che restituiscono PASS/FAIL e riscontri concreti. Corregge finché i controlli non passano e mantiene struttura e qualità desiderate.

Per documenti complessi e regolamentati — policy, narrative di controllo, CAPA, pacchetti di autorizzazione — la redazione guidata dalla spec con workflow e strumenti di validazione non è un piccolo miglioramento; è la differenza tra “forse sufficiente” e “pronto per l’audit e ripetibile”.

Per provare: scegli uno skill Rakenne per il tuo dominio, crea un progetto con quel workflow e confronta l’output strutturato e validato con ciò che ottieni da un singolo prompt ChatGPT.