Come si presenta un buon record di attrito

Perché i documenti e non i ricordi?

L’attrito che si verifica in una singola sessione è solo rumore. Lo stesso attrito che si ripete nell’arco di otto sessioni costituisce invece un modello che il vostro team può correggere — ma solo se quelle otto sessioni hanno lasciato tracce che potete effettivamente esaminare insieme: coerenti (stesso schema, in modo da essere comparabili) e attendibili (osservazioni supportate da prove, non semplici impressioni).

Nessuna delle due cose avviene per impostazione predefinita. Il momento in cui si verifica un attrito è il momento in cui si dispone del massimo di informazioni al riguardo: la riga esatta ormai obsoleta nel runbook, il parametro esatto che il brief aveva lasciato in sospeso. Tali informazioni si esauriscono rapidamente. L’agente normalizza la propria soluzione alternativa nel giro di pochi cicli e, al termine della sessione, il segnale scompare a meno che non sia stato messo per iscritto; qualunque cosa un subagente riesca a capire «svanisce nel momento stesso in cui viene restituita» (Hindsight, maggio 2026). Il presente capitolo verte proprio sulla messa per iscritto.

Come si percepisce l’attrito

Prima che qualcosa possa essere registrato, deve essere notato. Quattro canali, e ciascuno di essi vede cose diverse:

L’agente si rende conto di trovarsi in difficoltà. Cicli di riprova, backtracking, rilettura dello stesso file o nuova interrogazione della stessa vista analitica, un’ipotesi imposta da una lacuna nel brief. Le piattaforme di produzione hanno sostanzialmente convergito su questo elenco di segnali comportamentali (Factory Signals, gennaio 2026). Il canale più economico, con due limiti evidenti: è cieco nei confronti di ciò che manca (si avverte un ciclo di riprova; un documento che non è mai esistito non produce alcun segnale) e l’auto-osservazione supera l’autodiagnosi — i modelli individuano con scarsa precisione i propri errori di agenzia anche su tracce curate (~11%, TRAIL). Pertanto, il compito durante la sessione consiste nell’osservare i sintomi e citare le prove, mantenendo la diagnosi in modo flessibile.

Un secondo agente esamina la trascrizione. Un revisore che non ha seguito il caso individua ciò che l’agente incaricato aveva considerato normale. È un approccio più obiettivo; richiede una seconda revisione e comporta a sua volta errori di valutazione.

Un operatore umano corregge l’agente. Il sensore dominante rimane comunque l’uomo: uno studio di produzione della durata di 8 settimane ha rilevato che circa il 70% dei guasti silenziosi degli agenti è stato individuato per la prima volta da una persona che ha notato qualcosa di anomalo — non dai test unitari, dai controlli di integrità o dagli audit di governance (arXiv 2606.14589). Ogni correzione (un «no, intendevo…» da parte di un revisore, una parte interessata che spiega nuovamente le indicazioni nel corso di un audit) indica esattamente il punto in cui il contesto si è discostato dall’intento, e l’agente è in grado di coglierlo sul momento senza alcun costo aggiuntivo per il processo.

Telemetria. Tassi di errore degli strumenti, rifiuti di autorizzazioni, conteggi dei cicli, durate prolungate. Automatica e imparziale, ma superficiale: rileva che qualcosa è accaduto, non perché.

Le configurazioni più efficaci si basano su un approccio triangolare: la telemetria indica dove cercare, un’analisi di verifica spiega perché e la correzione manuale colma quella categoria di problemi che nessun segnale automatico è in grado di individuare. Qualunque sia la combinazione che si utilizzi, ciò che rimane dovrebbe essere sempre lo stesso: un record.

Cosa spinge l’agente a registrarlo?

Un agente non registrerà un attrito che nessuno gli ha indicato di cercare. La maggior parte degli attriti non viene registrata non perché non sia stata notata, ma perché nulla ha determinato la sua acquisizione. Quattro meccanismi, che differiscono principalmente per ciò che ne garantisce l’attivazione:

• Una competenza: una procedura scritta e soggetta a versionamento che l’agente esegue al termine della sessione. Contiene lo schema e le regole di onestà, pertanto ciò che viene attivato è coerente: la stessa procedura funziona sia in caso di rifattorizzazione che di revisione di un account pubblicitario. Punto debole: l’attivazione è probabilistica; può non verificarsi mai senza che ciò venga segnalato.
• Un hook: è l’imbracatura stessa a innescare o a segnalare (un’iniezione all’inizio della sessione, un trigger alla fine della sessione). È deterministico (l’unica opzione che non dipende dal fatto che qualcuno si ricordi qualcosa), ma poco preciso (si attiva anche per le sessioni di due minuti) e legato alla piattaforma.
• Una linea convenzionale: un’istruzione permanente nel file di contesto dell’ambito, o nella sua controparte non codificata, un passaggio della procedura operativa standard (SOP) del team: «Concludere ogni sessione significativa assistita dall’IA registrando gli attriti». Infrastruttura pari a zero, ma si basa interamente sul fatto che il modello rispetti una riga tra tante, e la sua efficacia diminuisce man mano che il file cresce; la modalità di errore identificata è il file di memoria che ha «smesso di essere letto» (nota sul campo relativa agli anti-pattern).
• Un comando: un comando digitato da una persona/retroal termine di un ramo di funzionalità o di un turno di triage. Deliberato e tempestivo; l’anello debole è la memoria umana.

Questi elementi costituiscono il sistema; li si sovrappone. Un trigger deterministico (un hook o una fase SOP di fine turno), un payload procedurale (la competenza) e una linea convenzionale che definisce la pratica come norma — scegliete almeno un trigger, meglio se due. Persino i fornitori hanno intuito questa logica: le linee guida di Codex di OpenAI recitano «quando Codex commette lo stesso errore due volte, richiedetegli un’analisi retrospettiva e aggiornate il file AGENTS.md» (migliori pratiche).

L’anatomia di un buon inizio

Un record rappresenta il contratto tra la sessione che ha rilevato l’attrito e tutte le fasi successive: la qualità della sintesi è limitata dalla qualità del record. Quattro elementi fondamentali:

1. Un evento documentato, con il relativo costo. Cosa è accaduto, quando è avvenuto e quale conseguenza osservabile ne è derivata, in modo sufficientemente specifico da consentire a chi non era presente alla sessione di agire di conseguenza. Per «costo» si intende lavoro da rifare, tempo sprecato, risultato errato; una registrazione priva di indicazione del costo non potrà essere classificata in seguito. La stima del costo da parte dell’agente è approssimativa: è preferibile indicarla(est.) piuttosto che fingere precisione.

2. Esattamente un’etichetta di causa principale scelta da un vocabolario fisso composto da dieci etichette. I vocabolari fissi consentono un’etichettatura affidabile (MAST ha raggiunto un κ = 0,88 su 14 modalità di guasto; si veda arXiv 2503.13657); le categorie libere, invece, variano da persona a persona e non consentono l’aggregazione. Le dieci:

• ambiguous-instruction: la richiesta ha tralasciato un parametro fondamentale (destinatari, ambito, definizione, periodo di tempo) e ha costretto a formulare un’ipotesi
• missing-context: un fatto ben noto al team, ma che non è stato comunicato
• incorrect-context: le informazioni fornite erano errate
• missing-documentation: manca la documentazione che dovrebbe essere presente (non sono disponibili né README, né specifiche, né runbook, né procedure operative standard)
• incorrect-documentation: esiste un documento, ma è obsoleto o errato, e ci si è basati su di esso
• work-material-friction: il materiale su cui si stava lavorando ha rallentato il lavoro o lo ha reso soggetto a errori: debito tecnico o struttura confusa nel codice; un account, un pannello di controllo, un foglio di calcolo o un modello esterno al sistema (si prega di indicare sempre il materiale specifico)
• missing-access-or-tool: non era disponibile un connettore, un’autorizzazione o uno strumento necessario
• agent-error: un errore commesso dall’agente stesso (ipotesi errata, informazioni obsolete, un bug da lui stesso introdotto)
• changed-requirements: le indicazioni sono cambiate nel corso della sessione e il lavoro è stato rifatto
• environment-friction: malfunzionamenti degli strumenti, timeout, problemi relativi alla sandbox o alla piattaforma

Un’etichetta per ogni risultato garantisce l’integrità delle distribuzioni: scegliete quella che meglio si adatta, prendete nota delle incongruenze nelle prove e non inventate mai un’etichetta a metà della voce. Tre regole di delimitazione svolgono la maggior parte del lavoro di disambiguazione. Il test della conoscibilità da parte dell’agente: il fatto era individuabile in qualsiasi luogo in cui l’agente potesse ragionevolmente cercare? Non trovato dove avrebbe dovuto essere → missing-documentation; fornito solo in un secondo momento, da una persona → missing-context. L’errore dell’agente è il residuo: utilizzatelo solo quando gli input erano adeguati e l’agente ha comunque commesso un errore; se l’errore è riconducibile a un input errato, etichettate l’input. E ambiguità contro cambiamento: se il chiarimento ha rivelato ciò che era sempre stato inteso, si tratta di ambiguous-instruction; se l’obiettivo è realmente cambiato, si tratta di changed-requirements.

3. Una soluzione delle dimensioni di un biglietto, che ne specifichi l’ambito di applicazione. L’ambito di applicazione è il livello a cui la soluzione è destinata: memoria, competenze, ambiente, documentazione, il materiale stesso, processo o fase a monte. Una segnalazione di problema a cui non è allegata alcuna soluzione costituisce un reclamo.

Ecco una voce completa tratta da una sessione non dedicata alla programmazione, ovvero la revisione mensile dell’account pubblicitario:

- **[missing-context]** The brief didn't say the French campaigns were deliberately
  paused for Q3; ~40 min (est.) auditing a "broken" campaign that was fine.
  → Fix (altitude: process): add campaign-status flags to the monthly brief template

Un momento, un costo contrassegnato da un(est.)indicatore, un’etichetta, una soluzione che qualcuno potrebbe adottare la prossima settimana. Si confronti la versione inutilizzabile della stessa osservazione: «le istruzioni erano confuse»: nessun momento, nessun costo, nessun passo successivo. La vaghezza è di per sé una forma di fallimento.

4. Il diritto di non dire nulla. «Nulla di rilevante» è una risposta valida e utile; un registro gonfiato da risultati inventati finisce per oscurare quelli reali.

Un ulteriore aspetto da considerare nella progettazione: la registrazione dovrebbe essere senza filtri — un agente che necessita di autorizzazione per registrare tende a sottostimare gli attriti. Lasciate che registri liberamente e che il feedback umano funga da correzione a posteriori: un segnale aggiuntivo proveniente dalla persona che ha partecipato alla sessione, non un punto di controllo su cui il ciclo rimane in attesa.

Le regole “never-log”

I dati sopravvivono alle sessioni: vengono salvati, condivisi e aggregati. Alcuni elementi non vengono mai inseriti:

• Segreti, credenziali, token o chiavi API, in qualsiasi forma, anche parziali.
• Dati dei clienti o informazioni personali.
• Dati aziendali non ancora resi noti o cifre riservate — descriva l’effetto, non i dati.
• Soprattutto, le persone. Mai un nome, un ruolo o qualsiasi altro elemento che identifichi chi abbia causato una lacuna. Descriva la lacuna e quali sono state le conseguenze: «il brief ha lasciato il pubblico all’oscuro», non «il brief di X». Le voci criticano gli input e i sistemi, non le persone — la stessa disciplina su cui si basa una buona retrospettiva, e ciò che rende il registro sicuro da leggere insieme.

È normale che gli input siano oggetto di critica: brief poco chiari, contesto mancante e requisiti forniti in ritardo sono solitamente gli aspetti su cui si concentra il materiale su cui è possibile intervenire. L’agente dovrebbe autovalutarsi con la stessa onestà. Se non è possibile descrivere gli attriti relativi a un ambito senza ricorrere a un contesto sensibile, si raccomanda di mantenere private le voci relative a tale ambito e di condividere solo il brief aggregato.

Dove si trova il registro

Un registro per ogni ambito di revisione — il confine entro il quale vengono applicate le correzioni. Per la maggior parte del lavoro di sviluppo, tale ambito è rappresentato dal repository: la sua documentazione, la configurazione e le convenzioni risiedono nel repository, pertanto anche il relativo registro delle interazioni vi è ospitato. Al di fuori del codice, l’ambito è l’account pubblicitario, la casella di posta dell’assistenza, il coinvolgimento del cliente; conservate il registro nella cartella dei documenti di quell’area di lavoro. Una registrazione archiviata al di fuori del proprio ambito è una di quelle che il responsabile della correzione non troverà mai; una voce scritta in una directory temporanea viene eliminata al termine della sessione.

Ciò che deve rimanere identico ovunque non è lo spazio di archiviazione, bensì la struttura: è lo schema, non lo spazio di archiviazione, a consentire il successivo raggruppamento delle voci. Questo è il punto centrale di questo capitolo dal punto di vista del lavoro di squadra: sono proprio i record comparabili, tra persone, agenti, sessioni e strumenti, a rendere possibile l’aggregazione a livello di team. Adattate liberamente lo spazio di archiviazione; preservate lo schema.

Cosa succederà ora

Una pila di registrazioni valide costituisce materia prima, non una visione d’insieme. I capitoli successivi partono da qui: la scelta dell’livello di ciascuna registrazione (la differenza tra una nota di memoria e la rielaborazione a cui l’attrito continua a rimandare); la sintesi delle voci in un riassunto di una pagina che il team possa leggere insieme; e la cerimonia in cui le persone e il registro si incontrano — la retrospettiva, con le registrazioni dell’agente come input dei partecipanti. Questo ciclo costituisce un esempio del «Feedback Flywheel»: reintegrare gli insegnamenti appresi negli artefatti che forniscono il contesto (martinfowler.com). E la disciplina alla base delle voci è l’analisi degli errori, «l’attività più importante nelle valutazioni» (Husain & Shankar, FAQ sulle valutazioni), spostata nel momento meno oneroso possibile: mentre la sessione in cui si è verificato l’attrito è ancora in corso.

Tutto quanto sopra funziona con un file di testo e qualsiasi agente compatibile. Se preferite non creare il modello autonomamente, la ai-session-retroskill gratuita implementa questa struttura di inserimento dall’inizio alla fine; il post di avvio rapido illustra come installarla in circa dieci minuti.

Capitolo successivo: Dove dovrebbe avvenire la correzione? — il problema dell’altitudine e la tabella di instradamento.