Ho scritto l'ontologia di un prodotto. Tre volte ho creduto di aver finito.

Arriva una domanda su Slack: il prodotto sa fare questo, per questo cliente, in questo caso preciso?

Non è una domanda astratta. Non è una riflessione sulla visione a cinque anni. È una domanda che viene dal campo, e va risolta entro l'ora. Quindi qualcuno apre un ambiente di test, riproduce il caso, verifica. Mezz'ora. Pagata due volte: da chi cerca e da chi viene interrotto.

Non è un problema di documentazione. Ce n'è, ed è aggiornata. Il problema è che ciò di cui il prodotto è fatto — gli oggetti che manipola, le regole che li governano, le parole per parlarne — non è scritto da nessuna parte in una forma che si possa interrogare. Esiste in due posti: nel codice, che poche persone sanno leggere, e nella testa di quelle stesse persone.

Così ho provato a scriverlo. Il risultato esiste: 52 oggetti descritti, 250 regole, 208 collegamenti tra loro. Questo articolo racconta come ci sono arrivato — e soprattutto cosa ho sbagliato per strada, perché quella è la parte che si trasferisce.

Tre avvertenze prima di iniziare.

La prima: questo resoconto riguarda la costruzione del modello di riferimento, non il suo uso. Esiste, è misurato, ha prodotto i primi sottoprodotti. Ma la fase di sfruttamento non è iniziata. Non posso quindi affermare nulla sul ritorno dell'investimento. Chi ti vende un numero a questo stadio se lo sta inventando.

La seconda: gli esempi vengono da un caso fittizio — un'azienda che vende un SaaS di gestione, un ERP, con i suoi clienti, i suoi ordini, le sue righe e le sue fatture. Ciò che si trasferisce da un prodotto all'altro non sono le mie scoperte, è il tipo di problema che si trova: uno stato ricalcolato dappertutto e definito da nessuna parte, una regola applicata da un solo lato, una parola che i clienti usano e che il prodotto ignora. Quei tre li hai anche tu. Il dettaglio del caso, invece, non interessa a nessuno.

La terza: è lungo, mezz'ora di lettura. È un resoconto, non un post — ho preferito dire tutto piuttosto che essere breve. Se leggi una sola sezione, leggi «Tre criteri di arresto. Tre volte sbagliati.»: il resto è il contesto che la circonda. Le appendici servono solo a chi vorrà rifare il lavoro.

Un'ontologia non è un glossario arricchito

La parola è una trappola. Ad alcuni evoca la filosofia, ad altri un campo accademico con strumenti complicati, e alla maggior parte niente. Meglio metterla giù bene.

Un'ontologia è la descrizione esplicita e strutturata di ciò di cui un dominio è fatto: - i tipi di oggetti che esistono, - ciò che li caratterizza, - ciò che li collega, - ciò che è vero su di loro, - le parole con cui li chiamiamo.

Applicata a un software, risponde a cinque domande. Ciascuna corrisponde a una cosa che si scrive, e ciascuna ha un nome dotto di cui poi non avrai bisogno:

Nel resto dell'articolo, per evitare i termini dotti, dico «oggetti», «proprietà», «collegamenti», «regole» e «parole». È la stessa cosa.

Queste cinque caselle servono anche da filtro: ciò che non entra in nessuna non ha niente a che fare nel modello di riferimento.

Perché un documento in più

Esistevano già un glossario, uno schema di database, della documentazione. Il glossario definisce le parole una alla volta. Lo schema organizza i dati secondo vincoli tecnici, non secondo il business. La documentazione racconta, per un lettore umano.

Ciò che li distingue da un'ontologia si riduce a un punto: i collegamenti contano tanto quanto le definizioni. Un oggetto descritto da solo insegna poco. Lo stesso oggetto collegato ad altri cinque da verbi precisi — emesso da, contiene, fatturato in — descrive un prodotto.

Cosa riconcilia

Uno stesso oggetto porta tre nomi dentro un'azienda. Prendi l'ordine cliente:

Questi tre vocabolari evolvono separatamente, e la distanza tra loro è un'informazione di valore. Il modello di riferimento la conserva: la parola ufficiale, le parole usate dai clienti e quelle che abbiamo abbandonato per strada. È ciò che permette di tradurre la frase di un utente in oggetto del prodotto — e viceversa.

Cosa non ho fatto

Esistono modi molto dotti per fare tutto questo: linguaggi dedicati, strumenti che deducono conclusioni dalle regole che gli dai, norme che li accompagnano. È un campo vero, e non ci sono entrato (tra l'altro per mancanza di competenze).

Ho iniziato da ciò che sapevo tenere in mano: una scheda per oggetto, in un file di testo. Un titolo, qualche campo, collegamenti verso le altre schede. Niente che un editor di testo non sappia aprire. Finché non so a cosa servirà il modello di riferimento, non so di quanto rigore ho bisogno — e cominciare semplice per complicarsi dopo costa sempre meno del contrario.

Il codice è diventato la fonte di verità. Il senso è rimasto fuori.

Attorno a questo prodotto, la documentazione, il registro delle novità, la documentazione di supporto, le risposte alle domande sul prodotto e le specifiche vengono tutte rigenerate dal codice. Il ragionamento è semplice: la verità di un prodotto è ciò che gira, non ciò che era previsto.

Questo cambio elimina un lavoro intero — tenere aggiornati, a mano, documenti che descrivono qualcosa di diverso dalla realtà. È un guadagno considerevole, e lo difenderei ancora.

Ma sposta il problema.

Cosa il codice non dà

Il codice stabilisce come funziona il prodotto. Il senso si costruisce sopra.

Prendi l'ordine e il suo stato. Il codice dà la struttura: ecco i campi, ecco i valori possibili. Quattro informazioni lo rendono davvero utilizzabile, e nessuna si trova lì:

• la regola — un ordine fatturato non riceve più righe. Il prodotto la applica, ma la regola non è scritta da nessuna parte: il controllo è sparso in cinque file e ognuno ne fa solo un pezzo. Per enunciarla in una frase bisogna averli letti tutti e cinque;
• i casi particolari — un ordine urgente è un ordine, con vincoli in più;
• il vocabolario — gli utenti dicono «affare», e un altro termine è stato abbandonato tre anni fa;
• la portata — il prodotto conta due applicazioni, che chiamerò A e B, e ciascuna mette il proprio senso dietro la stessa parola.

Messe insieme, queste quattro informazioni trasformano una struttura di dati in descrizione di prodotto. È esattamente il contenuto di una scheda. E nessuna si trova nello stesso posto: sono distribuite tra il nucleo del codice, il database, le schermate e le traduzioni.

Il costo reale si paga altrove

La domanda dell'inizio è solo un caso tra tanti. Tutto ciò che descrive il prodotto a qualcuno è una ricostruzione, rifatta ogni volta, in parallelo, da ogni reparto: la documentazione, le risposte alle gare d'appalto, la formazione dei nuovi arrivati, il discorso del supporto. Ognuno riparte dal codice, o dalla memoria di qualcuno.

È questa spesa che va eliminata. Non compare in nessun budget, il che spiega perché la paghiamo da anni senza vederla.

Un'IA non può chiedere. Indovina.

Fino a qui, ciò che il prodotto è davvero si trasmetteva a voce. Chiedevi alla persona giusta, ottenevi la regola, tornavi al lavoro. Il modello del prodotto viveva in qualche testa, e funzionava perché si poteva sempre bussare a una porta.

Un'IA non bussa a nessuna porta.

Quando le affidi un'evoluzione, la descrivi in qualche frase. Nella nostra testa c'è un modello completo: cos'è un ordine, quali stati attraversa, cosa è vietato e a partire da quando. L'agente ha solo le nostre poche frasi, più ciò che riesce a leggere nel codice. Il resto lo colma — in modo plausibile, coerente e a volte sbagliato.

La distanza tra ciò che volevamo e ciò che riceviamo è esattamente la parte del nostro modello mentale che non abbiamo scritto.

Un modello di riferimento è quel modello mentale scritto. Darlo a un agente non lo rende più intelligente: gli impedisce di inventare dove una regola esiste già. Ne derivano tre usi, e sono quelli che mi interessano.

Chiedere un'evoluzione senza rispiegare il prodotto. «Aggiungi uno sconto sugli ordini.» Con il modello di riferimento nel contesto, l'agente sa che un ordine fatturato non riceve più righe, che uno sconto ha un tetto e che «ordine» copre anche gli ordini urgenti e gli ordini ricorrenti. Senza, scoprirà una di queste tre cose in fase di revisione — nel migliore dei casi.

Analizzare più in fretta. Istruire un bug comincia sempre col ricostruire il modello della zona interessata. Questa ricostruzione viene rifatta ogni volta, da ogni persona e da ogni agente. Scritta una volta, si legge in qualche secondo. E qualche centinaio di schede sta in un contesto dove migliaia di file di codice non ci stanno: l'agente legge ciò che serve invece di scavare a caso.

Scrivere i test e decidere le segnalazioni. Una regola è un'affermazione verificabile. «Un ordine fatturato non riceve più righe» è un test, così com'è, formulato in linguaggio di business. 250 regole sono 250 test candidati che nessuno deve dedurre dal codice. E davanti a una segnalazione del cliente la domanda diventa meccanica: questo contraddice una regola scritta — allora è un bug; oppure è una regola che nessuno aveva posato — allora è una decisione di prodotto, non un difetto. Oggi quel verdetto lo emette l'esperienza, la persona più anziana del team.

Niente di tutto questo è misurato, conformemente all'avvertenza iniziale. Il meccanismo mi sembra solido — si elimina la parte indovinata — ma non ho fatto la prova. Quella che farò: prendere una trentina di richieste, trattarne metà con il modello di riferimento nel contesto e metà senza, poi confrontare il tempo speso e la quantità di rilavorazioni. Finché non è fatto, questa sezione è un'attesa, non un risultato.

Il metodo: abbozzare per sapere cosa cercare

Un dilemma si presenta subito. Senza un modello, anche grezzo, non sai quale materiale raccogliere — e passi accanto a informazioni importanti senza accorgertene. Senza materiale, non sai quale modello tenere.

Iterare, non sequenziare. Abbozzi quel tanto che basta per sapere cosa cercare, cerchi, riprendi il modello con quello che hai imparato. Un vincolo attraversa gli andirivieni: ciò che si raccoglie viene salvato nella forma più semplice possibile, e sempre con l'indicazione di dove viene. Un cambio di modello non deve mai obbligarti a tornare a cercare ciò che hai già.

Da dove cominciare: venti domande che ci erano già state fatte

Un prodotto ha decine di aree — la fatturazione, gli acquisti, i diritti di accesso, la ricerca, le notifiche. Da quale cominciare? La risposta teorica è nota: si scrivono prima le domande a cui il modello di riferimento dovrà saper rispondere, e sono loro a delimitare il terreno. Il problema è che le domande scritte a freddo, in una sala riunioni, somigliano sempre a ciò che crediamo importante.

Quindi non le ho scritte. Sono andato a cercarle.

Da mesi, ogni domanda sul prodotto che arriva — via Slack, in riunione, da un commerciale che prepara una risposta, dal supporto davanti a un ticket — viene archiviata con la sua risposta. Le ho rilette tutte, poi condensate in venti domande generiche. Nessuna è inventata; ciascuna copre tra cinque e venti domande reali.

Trasposte sull'ERP fittizio, somigliano a questo:

• Quali sono gli stati di un ordine, e quali passaggi da uno all'altro sono permessi?
• Cosa si può ancora annullare, e da quale momento non più?
• Cos'è il saldo di un cliente, e per quali movimenti evolve?
• A chi appartiene un ordine generato automaticamente, e cosa ne diventa se quella persona lascia l'azienda?
• In quali casi un utente di una filiale vede gli ordini di un'altra filiale?
• Come chiamano gli utenti l'ordine, e in quali lingue?

Non sono domande eleganti. Sono quelle che costano mezz'ora a qualcuno, più volte al mese.

Cosa dà immediatamente: l'ordine di lavoro. Ogni domanda tocca una o più aree del prodotto; basta contare. Undici domande su venti battevano sulla stessa area — è diventata la prima. Cinque su una seconda, quattro su una terza. L'ordine non è più una preferenza, è un conteggio.

E servono una seconda volta, all'arrivo. Quando un'area è finita, si riprendono le sue domande e si verifica che il modello di riferimento risponda senza aprire il codice. Il controllo fatto a metà percorso ha dato 18 risposte complete su 20. Le due mancanti mancavano nello stesso modo: una regola scritta in generale dove la domanda si aspettava il dettaglio — «certe operazioni richiedono questo» senza mai dire quali.

È il difetto più probabile in questo tipo di lavoro, e il più difficile da vedere. Contare le schede non l'avrebbe mai mostrato.

Una scheda per oggetto, e collegamenti tra loro

Una scheda per oggetto di business, in un file di testo che porta il suo nome. Ogni volta che una scheda menziona un altro oggetto, lo fa attraverso un collegamento.

Questo dettaglio sembra cosmetico. Non lo è. Le schede e i loro collegamenti formano una rete, e quella rete si può visualizzare: ogni scheda è un punto, ogni collegamento un tratto. Un collegamento che punta a una scheda che non esiste ancora si vede immediatamente — è il segnale che resta un oggetto da descrivere.

La rete smette allora di essere una bella immagine e diventa la coda di lavoro: finché ci sono collegamenti nel vuoto, ci sono schede da scrivere.

La realtà da un lato, l'intenzione dall'altro

Un modello di riferimento può descrivere due cose molto diverse: ciò che il prodotto fa oppure ciò che dovrebbe fare. Ciascuna da sola è incompleta. La prima non permette mai di far emergere un difetto. La seconda perde traccia di ciò che esiste davvero.

Io tengo entrambe, in due posti distinti della stessa scheda. Il corpo della scheda descrive la realtà, così com'è nel codice. Un blocco separato, in fondo alla scheda, elenca gli scostamenti: ogni punto in cui quella realtà diverge da ciò che vorremmo.

Regola assoluta: uno scostamento non modifica mai il corpo della scheda.

Ciò che giustifica la separazione è che le due parti non hanno la stessa durata di vita:

Il corpo si deduce dal codice: si può buttare e rifare senza perdere niente. Gli scostamenti portano giudizio — non si ritrovano da nessuna parte se li perdi. Separarli significa proteggere la parte che costa caro produrre.

Un punto spesso capito male: quando tutto va bene, non si scrive niente. Se il prodotto fa ciò che deve fare, la regola sta semplicemente nel corpo della scheda. Il blocco degli scostamenti contiene solo le divergenze. Una scheda senza scostamenti segnala un oggetto conforme, e questa è già un'informazione.

Cinque nature di scostamento bastano, e sono loro a trasformare il modello di riferimento in materiale di lavoro:

Il punto di partenza: una foto, scattata in un istante dato

Si descrive il prodotto così com'è in un istante dato. Una versione del codice, e tutto ciò che gira con essa: il database così com'è in quella versione, le schermate di quella versione, le traduzioni di quella versione. Questa è la foto.

Ciò che vi compare è lo stato iniziale, senza data di nascita: non cerco di sapere quando è apparso ciascun campo. Ricostruire la storia del prodotto richiederebbe di frugare anni di archivi per un beneficio nullo.

Più tardi si scatta una nuova foto e si aggiornano le schede con ciò che si è mosso tra le due. È tutto il meccanismo.

L'unica cosa da tenere d'occhio, e mi ci sono fatto prendere: una fonte che non viene dalla foto non è una fonte. Ci torno più sotto.

Quattro posti da leggere, nessuno facoltativo

Uno stesso oggetto è descritto in quattro posti del prodotto, e ciascuno dice ciò che gli altri tacciono:

Un'area del prodotto è finita solo quando tutti e quattro sono stati letti. Una regola può esistere benissimo in uno solo.

Le schermate si leggono dopo il nucleo del codice, e prima di chiudere l'argomento. Non è un'esigenza di completezza, è una macchina per trovare scostamenti:

Una regola presente unicamente nella schermata è quasi sempre uno scostamento.

O è una vera regola di business, mal collocata — un attrito. O è aggirabile passando accanto alla schermata, con un'importazione di file o con l'interfaccia che il prodotto espone agli sviluppatori esterni — la sua API. E allora è un difetto, con una questione di sicurezza: ciò che la schermata vieta, un altro percorso lo autorizza.

Il caso inverso esiste e si tratta allo stesso modo. Una regola applicata dal nucleo del codice ma che la schermata non riflette produce un messaggio di errore incomprensibile: all'utente viene rifiutata l'azione senza che veda cosa ha sbagliato.

Due constatazioni su questa lettura delle schermate.

Primo, la suddivisione delle schermate non coincide con quella del codice. Dodici zone dell'interfaccia non avevano zona equivalente lato server. L'accostamento si fa quindi oggetto per oggetto, mai cartella per cartella.

Secondo, un trucco che vale oro nelle parti meno ordinate del codice: i nomi dei messaggi di errore tecnici sono spesso la miglior fonte di regole. Uno sviluppatore che rifiuta un'azione crea un caso di errore, e lo nomina. Un errore chiamato CannotEditInvoicedOrder — «non si può modificare un ordine fatturato» — enuncia una regola da solo. Basta leggere la lista di quei nomi, e non serve saper programmare.

Niente di tutto questo è originale

È forse il punto più utile di questa sezione. Costruire ontologie è una disciplina consolidata, con la sua letteratura, e il metodo qui sopra riprende soltanto risultati noti:

• L'iterativo invece della cascata. I metodi storici incatenavano le tappe in ordine: specificare, concepire, formalizzare, realizzare. Sono stati soppiantati da approcci a piccoli pezzi ricombinabili. Il dibattito è chiuso da una quindicina d'anni.
• L'inquadramento per domande. Scrivere prima le domande a cui il modello di riferimento dovrà rispondere è il dispositivo standard; ha anche un nome, competency question. Andare a cercarle nel supporto invece di scriverle a freddo non sta nei manuali. Non costa nulla, e cambia ciò che trovi.
• Partire dal mezzo. Si comincia dagli oggetti più centrali del business, poi si sale verso le categorie più ampie e si scende verso i casi particolari. Gli altri due modi falliscono: partire dal database equivale a ricopiare la struttura tecnica così com'è, con le sue tabelle che non significano niente per il business; partire da una teoria generale di ciò che esiste dà un edificio fuori misura rispetto al bisogno.
• Rigore proporzionato all'uso. Ci si complica la vita quando serve, non per principio.
• Non reinventare ciò che è già normato. Nella maggior parte dei settori esistono classificazioni di riferimento. Bisogna guardarle — e trattare qualsiasi divergenza tra il proprio modello e loro come una questione da istruire, non come un dettaglio.

Tre criteri di arresto. Tre volte sbagliati.

Ecco la parte per cui questo articolo esiste.

Prima, due strategie scartate

Sapere cosa cercare non dice in quale ordine percorrere il prodotto. Due approcci si presentano naturalmente, e falliscono entrambi.

Leggere tutto, nell'ordine dei file. Senza priorità non c'è né ordine di arrivo né struttura che emerga. L'organizzazione delle cartelle non ha alcun rapporto con l'importanza per il business, e ciò che sta lì solo per ragioni tecniche viene descritto allo stesso livello dei veri oggetti di business. Si ottiene una massa di schede senza sapere quali contano.

Partire dal database e fare una scheda per tabella. Utile, ma insufficiente, e fondato su una confusione: una tabella non è un oggetto di business. Molte tabelle servono solo a collegare due altre tabelle, a tenere una traccia tecnica, a memorizzare token di connessione o risultati temporanei. Non hanno alcun senso per chi parla del prodotto.

Ho quindi scelto una terza via: un'area del prodotto per volta, partendo dal nucleo del business verso la periferia, appoggiandomi alla suddivisione che il codice porta già. Un software un po' grande è diviso in moduli — zone di codice che corrispondono grossomodo ad aree del business: la fatturazione, gli acquisti, i diritti di accesso. Quella suddivisione l'hanno fatta degli sviluppatori, ma costituisce già una descrizione parziale del business, gratuita e validata dall'uso.

Era la decisione giusta. Non ha impedito ciò che è venuto dopo.

Primo criterio: «la rete di schede è chiusa»

Tutte le schede citate esistono, nessun collegamento punta più nel vuoto. Quindi è finito.

È falso, e la ragione è meccanica. Un insieme di schede che si citano solo tra loro chiude la propria rete molto prima di aver coperto il prodotto. La rete si è chiusa da me quando solo dodici moduli su trentadue avevano dato luogo a una scheda.

Cosa provava davvero quel controllo: che l'insieme tiene. Nient'altro. È un buon controllo, va conservato — ma non risponde alla domanda posta.

Il controllo di copertura fatto in seguito ha fatto emergere due oggetti centrali del business che niente, nella rete, stava reclamando.

Secondo criterio: «ho percorso tutte le mie fonti»

Il codice delle due applicazioni, il database, l'API, il glossario, i resoconti di interviste, i ticket di supporto. Niente più da aprire.

È vero, e non prova niente. È un'affermazione su ciò che ho aperto, non su ciò che esiste. «Ho letto tutta la mia pila» non dice niente della biblioteca: finché il prodotto non è enumerato, «tutto» non ha denominatore. Un modulo che non è mai comparso nella mia lista non compare nemmeno nel mio «tutto».

Terzo criterio: «ogni area è stata letta nei quattro posti»

Il nucleo del codice, il database, le schermate, le traduzioni.

Vero anche questo, e insufficiente per la stessa ragione: vale solo per le aree che avevo individuato. Il criterio misura la profondità, non dice niente della larghezza. Si possono leggere quattro posti su dodici moduli e ignorarne venti — è esattamente quello che è successo.

La diagnosi

Riprendiamo i tre, e ciò che ciascuno provava davvero.

Tutti e tre dicono la stessa cosa: ho finito ciò che avevo iniziato. Nessuno dice: non resta niente.

Si sceglie un criterio che si può soddisfare, invece di un criterio che prova il lavoro fatto.

È la differenza tra «ho messo in ordine tutto quello che c'era sulla mia scrivania» e «ecco la lista di quello che dovevo mettere in ordine, tutto spuntato». La prima frase è vera, e non impegna a nulla. La seconda presuppone di aver fatto la lista prima di iniziare.

Non è disonestà, è una questione di costo.

Un criterio che si può soddisfare è già a portata di mano: basta guardare ciò che hai appena fatto e constatare che è fatto. Un criterio che prova, invece, richiede di fabbricare qualcosa in più — la lista di ciò che esiste, un modo di contarla, un numero che un altro potrebbe ricalcolare. È lavoro aggiuntivo, richiesto nel momento preciso in cui credi di aver finito.

Da qui l'unico rimedio che conosco: scegliere il criterio di arresto all'inizio, non alla fine. Cercarlo alla fine significa sceglierlo tra quelli che sei già certo di soddisfare.

L'unico criterio che tiene

Enumerare il prodotto da più angoli indipendenti, e misurare per ciascuno la quota che corrisponde a una scheda.

Ogni angolo vede ciò che gli altri non possono vedere:

E soprattutto: il segnale utile è il disaccordo tra due angoli. Un oggetto presente in uno e assente dagli altri è o un oggetto di business che ci è sfuggito, o infrastruttura tecnica. La questione si decide in una riga — ma si decide esplicitamente, mai di sfuggita.

Gli altri errori

Quattro, più piccoli, tutti costosi.

Leggere una fonte che non era sulla foto. L'esportazione del database di cui disponevo era stata prodotta cinque mesi prima della versione di codice che descrivevo. L'ho letta come se descrivesse lo stesso prodotto. Descriveva un prodotto più vecchio: su un'area intera gli oggetti c'erano nel codice senza alcuna tabella corrispondente nell'esportazione, e ne ho concluso che non esistessero.

La regola è più semplice di quanto credessi allora. Non è «verificare la data prima di concludere» — è che una fonte che non viene dalla foto non è una fonte. La si sostituisce con una versione aggiornata, o se ne fa a meno.

E la precisazione che conta, perché all'inizio l'avevo mancata: quando due parti della stessa foto si contraddicono — il codice da un lato, il database o la schermata dall'altro, nello stesso istante, in produzione — non è uno sfasamento. È un'incoerenza del prodotto. È esattamente ciò che cerchiamo.

Prendere una ricerca per un inventario. Avevo indicizzato tutto il codice in un motore di ricerca per significato — il principio del RAG: fai la domanda in linguaggio corrente, lo strumento riporta i passaggi che più le si avvicinano. È tremendamente efficace per ritrovare una regola sepolta in mezzo a un file, che niente nel nome segnalava.

Ma un motore di questo tipo risponde sempre, e risponde sempre con una classifica: ecco i dieci passaggi più vicini alla tua domanda. Non dice mai «non ce ne sono». Una ricerca che non riporta niente di interessante può quindi significare due cose — la cosa non esiste, oppure ho posto male la domanda. Impossibile decidere.

Da qui la regola: enumerare prima, cercare dopo. Nel senso opposto, ottieni un modello di riferimento fatto di ciò che il motore ha voluto riportare.

Due dettagli che costano caro. Il motore aveva la sua data, una versione dietro il codice. E bisogna porre la domanda nella lingua del codice: una query in italiano su un codice scritto in inglese dà risultati mediocri, anche quando la risposta è lì.

Scrivere la stessa regola in tre posti. Per strada si sono formati tre documenti: - il modello di scheda da compilare, - il documento di metodo, - le istruzioni di lavoro che davo all'agente.

Una stessa regola — per esempio «uno scostamento non modifica mai il corpo della scheda» — è finita scritta in tutti e tre, ogni volta con parole un po' diverse.

Finché non cambia niente, non dà fastidio a nessuno. Il giorno in cui la regola evolve, ne correggi uno, dimentichi gli altri due, e tre documenti si contraddicono senza che nessuno sappia quale fa fede. Un'IA meno di chiunque altro: legge tutti e tre senza vedere che divergono, e fonda la sua analisi su quello che ha aperto per primo.

Ogni regola vive ora in un solo posto. Il modello di scheda descrive unicamente la forma — quali campi, quali valori ammessi — e rimanda al metodo per tutto il resto. Una sola fonte per regola.

L'ironia non mi ha colpito sul momento: costruivo un modello di riferimento destinato a eliminare le definizioni duplicate, duplicando le sue stesse regole in tre file.

Contare male. Volevo sapere quali parole usano davvero i clienti, e con quale frequenza. Ho quindi contato le occorrenze di ogni termine di business in 261 resoconti di interviste.

Primo risultato: una sigla di due lettere appariva 3.525 volte. In realtà erano 2. La ricerca contava tutte le volte in cui quelle due lettere si trovavano dentro un'altra parola. Cerca «CA» in quel modo e raccogli «caso», «casa», «scanner», «applicazione».

Bisogna quindi contare parole intere, e tenere conto delle maiuscole quando il termine è una sigla. Un contatore sbagliato è peggio di nessun contatore: ha l'aria di un dato.

Esiste anche l'errore inverso, ed è più insidioso. Un termine che credevo assente dal prodotto c'era, ma usato in un senso completamente diverso, in un angolo tecnico senza rapporto col business. Verifica un'assenza prima di concluderne una mancanza.

E uno scostamento che non lo era

Avevo registrato uno scostamento che affermava che un certo tipo di collegamento tra oggetti non era descritto correttamente nel prodotto. Fatta la verifica, lo era.

Lo scostamento resta nella scheda, segnato come rifiutato, con il motivo del rifiuto. Sbagliare fa parte del lavoro, a condizione che l'errore lasci una traccia utilizzabile — altrimenti lo stesso verrà rifatto tra sei mesi da qualcun altro.

L'agente cattura. L'essere umano riapre.

Il lavoro è stato condotto da un agente — un'IA a cui si affida un compito lungo — sotto la mia direzione. È probabilmente la parte più trasferibile di questo resoconto, perché non parla soltanto di ontologia.

Una precisazione di metodo: questa sezione non si appoggia sul ricordo di nessuno. Il registro delle decisioni del progetto è il diario dei miei interventi — ogni voce porta il suo motivo, cioè cosa ho corretto e perché. Il diario di avanzamento mostra cosa l'agente ha prodotto tra due arbitraggi. Tutto ciò che segue si legge in quelle due tracce.

Ciò che un agente fa notevolmente bene: enumerare, incrociare, contare, tenere un monitoraggio riga per riga, e leggere le traduzioni della dodicesima area con la stessa applicazione di quelle della prima. Questo lavoro è massicciamente ripetitivo, ed è esattamente ciò che lo rendeva inaffrontabile fino a oggi.

Ciò in cui è scarso: dichiarare il lavoro finito. I tre falsi criteri di arresto non sono venuti dal nulla — ciascuno è stato proposto come prova di completamento, e ogni volta è stato necessario rifiutarlo. Il pregiudizio è lo stesso di un essere umano stanco a fine progetto, solo che lui non ha la stanchezza come scusa: confondere riferire con consegnare.

I miei interventi, così come si leggono nei motivi delle decisioni, si dispongono in tre categorie:

• Allargare una portata che aveva implicitamente ridotto. L'agente leggeva il nucleo del codice e si fermava lì. La regola dei quattro posti, schermate incluse, viene da lì — e proprio nelle schermate si trovano gli scostamenti più interessanti.
• Correggere una struttura che stava per divergere. La stessa regola scritta in tre posti: l'aveva ricopiata per voglia di fare bene, che era esattamente ciò che non andava fatto.
• Rifiutare un criterio di arresto troppo comodo. Tre volte.

Ciò che rende possibile quell'arbitraggio si riduce a quattro dispositivi, e valgono per qualsiasi lavoro delegato — a una macchina come a un'altra persona:

1. Un criterio di arresto verificabile da un terzo. Non «ho letto tutto», ma una lista e un tasso.
2. Una misura che si può rilanciare, invece di un'affermazione. Tra «è coperto» e «ecco il comando che lo verifica» c'è tutta la distanza tra una promessa e un fatto.
3. Un monitoraggio scritto, alla giusta granularità. Una riga per area e per posto da leggere, aggiornata man mano. Sopravvive all'interruzione del lavoro, ed è ciò che evita di fare due volte la stessa cosa.
4. L'enumerazione prima della ricerca. Ciò che è certo prima, ciò che è probabile dopo e come complemento.

52 oggetti, e sette modi di verificare che non ne manchi nessuno

Ecco cosa ha dato, una volta applicato il criterio giusto.

52 oggetti di business descritti. 250 regole. 208 collegamenti tra loro. 124 scostamenti rilevati. Nessun collegamento che punta nel vuoto.

Le venti domande di partenza trovano risposta senza aprire il codice.

La copertura, misurata

Il principio si riduce a tre operazioni. Elenco gli oggetti di un angolo — i moduli, le tabelle, gli eventi, le schermate, le risorse esposte dall'API. Guardo, per ciascuno, se corrisponde a una scheda. Conto.

La misura viene rieseguita da un piccolo programma. È il punto importante: non è un'affermazione, è un controllo che qualcun altro può rilanciare.

Ed è una misura debole, cosa che va detta nella stessa frase. L'accostamento si fa sui nomi: una tabella sales_order viene riconosciuta come la scheda «Sales Order», lasciando da parte maiuscole, trattini e plurali.

Funziona più o meno una volta su due. Per il resto, i nomi non si somigliano per niente — una tabella può chiamarsi so_header dove la scheda si chiama «Sales Order». Ho quindi tenuto accanto una lista di corrispondenze, scritta riga per riga man mano che ci inciampavo: quella tabella è quell'oggetto.

Quella lista è un giudizio, non una regola. Se dimentico una riga, l'oggetto risulta non coperto quando invece lo è. Se ne aggiungo una dubbia — «dai, quella tabella dovrà pur corrispondere a quella scheda» —, gonfio il mio stesso punteggio. E anche quando i nomi coincidono può essere un caso: due cose diverse che portano la stessa parola.

La misura quindi non prova niente. Indica dove andare a guardare.

Perché non cerco di arrivare al 100%

È l'obiezione immediata: se so che mi manca il 19% dei moduli, so quali sono — basta descriverli.

Solo che la casella mancante non è un compito, è una domanda. Ogni oggetto senza scheda è o un oggetto di business che mi è sfuggito, o infrastruttura tecnica senza alcun senso per il business: una coda tecnica, un ridimensionatore di immagini, una tabella di token di connessione, una schermata di navigazione. Arrivare al 100% presupporrebbe creare una scheda «Coda» e una scheda «Token» — cioè inquinare il modello di riferimento per far salire un numero.

Il contatore ha quindi tre stati, e non due:

Ciò che deve arrivare al 100% è la terza riga a zero — niente più che non sia stato esaminato. La percentuale mostrata, invece, non sale fino a 100 e non deve farlo.

Qui il resto è stato passato in rassegna a mano: tecnica, meccanismi interni, schermate senza oggetto di business proprio. Nessun oggetto di business si nascondeva lì. Ma è una verifica manuale, da rifare a ogni evoluzione — ed è la debolezza che resta.

Il numero serve quindi ad altro che a misurare un avanzamento. Serve a confrontare gli angoli tra loro. 69% sugli oggetti dell'applicazione B contro 93% sugli eventi non vuol dire «resta il 31% di lavoro»: vuol dire «l'applicazione B manipola cose che il resto del prodotto ignora, andate a guardare da quel lato». È quel disaccordo che ha fatto emergere le quattro scoperte seguenti.

Cosa hanno riportato gli angoli

Quattro oggetti che nessun'altra via avrebbe trovato:

• Dalle tabelle del database. Un oggetto che il prodotto mostra ma che non appartiene a nessuna area del codice — nell'ERP fittizio sarebbe la scadenza di fatturazione futura: il cliente la vede nel suo piano di pagamento, ma esiste per davvero solo nel momento in cui la fattura viene emessa. Quell'ambiguità spiega un'intera famiglia di reclami dei clienti.
• Dagli eventi. Un sottoinsieme intero di un'area che credevamo coperta, rivelato dagli eventi che emetteva e che nessuno aveva ricollegato a niente.
• Dall'API. Due oggetti distribuiti su cinque moduli diversi — quindi invisibili finché si avanza area per area, e tuttavia esposti contrattualmente all'esterno.
• Dall'applicazione B. Due oggetti che manipola e che l'applicazione A non conosce.

I problemi che tornano dappertutto

Ecco le scoperte, trasposte sull'ERP fittizio. Sono tipi di problema, non casi isolati — e scommetterei che nessuno è assente dal tuo prodotto.

Uno stato ricalcolato dappertutto, definito da nessuna parte. Lo stato di un ordine dedotto da qualche data e dallo stato delle sue righe, ricalcolato in ogni schermata, senza regola centrale. Due schermate finiscono per non dire più la stessa cosa, e nessuno sa quale ha ragione.

Un oggetto che l'utente vede e non riesce a ritrovare. La scadenza di fatturazione di cui parlavo: mostrata nel piano di pagamento, assente dai risultati di ricerca, perché non esiste ancora come documento. L'utente però l'ha vista sullo schermo — quindi la cerca, non la trova e apre un ticket. Il supporto risponde caso per caso da anni senza che la causa sia scritta da nessuna parte.

Un valore che non lo è. Il saldo di un cliente non è un numero riposto da qualche parte: è il risultato di un calcolo su tutte le sue fatture, i suoi pagamenti, le sue note di credito e le sue scritture di rettifica. Finché resta implicito, ogni nuova funzionalità che «legge il saldo» sbaglia oggetto e restituisce un numero leggermente diverso, secondo i movimenti che ha pensato di includere. Tre schermate, tre saldi.

Una regola applicata da un solo lato. Il tetto di sconto controllato nel formulario di inserimento, e da nessun'altra parte — quindi aggirabile con un'importazione di file o con l'API. È la macchina degli scostamenti di cui parlavo sopra, e il suo rendimento è notevole.

Un'autorizzazione calcolata da sei fonti senza un posto che le raccolga. Il ruolo della persona, il piano sottoscritto, le opzioni attivate, la restrizione del periodo di prova, la portata della sua filiale, una lista di eccezioni. Nessun posto del prodotto dice «ecco come si calcola un'autorizzazione». Ogni evoluzione lo riscopre a proprie spese.

Uno stesso oggetto nominato diversamente a ogni piano. «Ordine» sulla schermata, una parola nel codice, un'altra nella seconda applicazione, «affare» sul campo. Quattro vocabolari per l'oggetto più centrale del prodotto.

Una parola che i clienti usano continuamente e che il prodotto ignora. Su 261 resoconti di interviste, una nozione torna 79 volte, un'altra 29. Né l'una né l'altra esiste nel prodotto, sotto nessun nome. Non sono scostamenti di vocabolario, sono mancanze di progettazione — e appaiono solo confrontando ciò che dicono i clienti con ciò che fa il prodotto.

I sottoprodotti

Nessuno era l'obiettivo. Tutti sono caduti dal lavoro.

Bug candidati. Il prodotto contraddice un'aspettativa scritta da qualche parte. Ciascuno arriva con la sua prova e la sua conseguenza, non con un'intuizione.

Un vocabolario cliente, con le sue frequenze. Contando le parole su 261 resoconti di interviste e 365 ticket di supporto, si ottengono per ogni oggetto del prodotto i termini realmente impiegati e il loro peso. Chi parla col cliente sa allora quale parola usare. Un termine torna 168 volte per designare una portata che il prodotto chiama altrimenti; un altro 141 volte per l'oggetto centrale.

E questi due corpus non dicono la stessa cosa. Le interviste dicono cosa i clienti vogliono costruire. I ticket dicono cosa si rompe. Una stessa parola può dominare l'uno ed essere assente dall'altro. Contarli insieme significa dare priorità di traverso.

Uno stato dell'arte delle traduzioni. Il glossario multilingue copre solo 15 dei 52 oggetti. Tra gli assenti, due sono comunque mostrati all'utente in tutte le lingue: per loro non esiste nessuna traduzione di riferimento. E delle diciannove lingue del glossario, solo due sono state rilette.

Quanto costa, e cosa il metodo ancora non dice

Il costo

Meno di sei ore. È il tempo che ha preso l'insieme: le 52 schede, le 250 regole, le misure di copertura. Una sessione, da un capo all'altro.

Prima di iniziare avevo stimato qualche decina di ore, distribuibili area per area. Mi sono sbagliato di un ordine di grandezza — e quell'errore di stima è forse la vera ragione per cui nessuno aveva fatto questo lavoro prima: lo si crede fuori portata, quindi non lo si inizia.

Tre riserve su quel numero, perché resti onesto. È una misura su un prodotto, una volta, non una media. Le fonti erano già raccolte e indicizzate localmente; il tempo di allestimento non è compreso. E dice tanto sugli strumenti quanto sul metodo: lo stesso lavoro a mano avrebbe preso settimane, che è precisamente il motivo per cui non era mai stato fatto.

La condizione di redditività, invece, è chiara: finire un'area prima di aprirne un'altra. Un modello di riferimento completo su un perimetro serve immediatamente a tutti i mestieri di quel perimetro. Un modello di riferimento fatto a metà su cinque perimetri non serve a nessuno.

La manutenzione

È la domanda che si pone sempre per seconda, ed è legittima: un modello di riferimento di cui non si dice come resta vivo non interessa a nessuno.

La versione di riferimento fa da cursore: con un solo comando dà la lista esatta di ciò che si è mosso nel prodotto dall'ultimo aggiornamento — quindi la lista di ciò che resta da registrare.

Ogni scheda porta un diario dove si aggiungono voci senza mai correggere le precedenti. Una voce che cita una versione del codice segnala che il prodotto è cambiato. Una voce che non ne cita nessuna segnala altro: è la nostra comprensione che è cambiata, non il prodotto. La distinzione sembra minore; è quella che permette, sei mesi più tardi, di sapere se abbiamo corretto una scheda o se il software è evoluto.

Due movimenti meritano una menzione perché nessuno strumento li racconta: la fusione di due oggetti che credevamo distinti e la divisione di un oggetto che ne nascondeva due. Sono i movimenti più frequenti quando un modello di riferimento matura.

Infine, quando un oggetto viene ripensato da capo a fondo, non modifichiamo la sua scheda: ne creiamo una nuova, e la vecchia resta. Descrive ciò che il prodotto è stato, e resta necessaria per interpretare i dati e gli scambi anteriori al cambiamento.

Cosa ho deciso di non fare

• Nessuna ricostruzione della storia passata del prodotto.
• Perimetro chiuso sulle esportazioni di dati, che sono viste derivate dal prodotto e non il prodotto stesso.
• Nessuno strumento dotto finché nessun uso lo reclama.

Cosa il metodo non dice ancora

• Fin dove spingere il rigore del formato. Dipende dall'uso, e l'uso non è iniziato.
• Come ricollegare un dato vecchio al giusto stato di un oggetto, quando quell'oggetto è stato ripensato nel frattempo.
• Chi rilegge una scheda, e secondo quali criteri, prima che entri nel modello di riferimento.
• A quale ritmo aggiornare il punto di partenza, e quindi recuperare ciò che si è mosso da allora.

Un documento di metodo che si pretende completo mente. Questo porta una sezione «cosa non dice ancora», e si restringe man mano che le questioni vengono decise.

Conclusione: il criterio di arresto è il vero deliverable

Se dovessi tenere una sola cosa di questo progetto, sarebbe la frase che spiega le tre false partenze:

Si sceglie un criterio che si può soddisfare, invece di un criterio che prova il lavoro fatto.

Non riguarda solo le ontologie. Vale per un audit, una migrazione, una revisione di sicurezza, un rientro dal debito tecnico. Ogni volta che un lavoro finisce con «ho guardato tutto», la domanda da porre è: tutto, cioè? Ne hai la lista?

Due controlli, mai uno solo. Che l'insieme tenga si verifica guardando le schede tra loro. Che sia completo si verifica enumerando il prodotto. Confonderli è costato, qui, un terzo del prodotto.

Resta la parte più interessante, e non è fatta: gli scostamenti. Aspettano tutti di essere istruiti — i bug candidati per primi, poi quelli che una richiesta cliente già sostiene, poi le mancanze, poi il debito di design. Non è più descrizione, è decisione di prodotto.

È un altro articolo, e potrà scriversi solo dopo.

Appendice A — Com'è fatta una scheda

Questa appendice è la parte più tecnica dell'articolo; si può fermarsi prima senza perdere niente del discorso.

La scheda qui sotto è trasposta sull'ERP fittizio. Descrive la forma — le regole che la governano vivono nel documento di metodo, in un solo posto.

Cosa contiene una scheda

La scheda stessa

Il file porta il nome dell'oggetto — è ciò che permette ai collegamenti tra schede di risolversi da soli.

---
concept: Sales Order
definition: Impegno di consegna preso verso un cliente, seguito dalla registrazione alla fatturazione.
parent:
enfants: ["[[Rush Order]]", "[[Standing Order]]"]
attributs:
  - nom: status
    type: enum
    valeurs: [draft, confirmed, shipped, invoiced]
relations:
  - verbe: placed-by
    cible: "[[Customer]]"
    cardinalite: 1..1
  - verbe: contains
    cible: "[[Order Line]]"
    cardinalite: 1..n
axiomes:
  - Un ordine fatturato non può più ricevere righe
lexique:
  fr: [commande, commande client]
  en: [sales order]
  es: [pedido]
  synonymes_terrain: [affaire, dossier]
  deprecies: [bon de commande client]
sources:
  - erp.sql:table `sales_order`
  - fr.json:order.status.draft
ecarts:
  - id: E1
    nature: manque
    portee: relations
    attendu: un collegamento verso "[[Attachment]]", come ne ha "[[Customer]]"
    consequence: impossibile allegare un ordine di acquisto firmato
    statut: confirme
    date: 2026-08-10
historique:
  - date: 2026-08-10
    action: creation
    motif: descrizione iniziale, sulla versione di riferimento
---

# Sales Order

Impegno di consegna preso verso un cliente, seguito dalla registrazione alla fatturazione.

## Collegamenti

- *placed-by* → [[Customer]] (uno solo)
- *contains* → [[Order Line]] (almeno una)
- casi particolari → [[Rush Order]], [[Standing Order]]

## Storico

| Data | Cosa è successo | Versione del codice | Motivo |
|---|---|---|---|
| 2026-08-10 | creazione | — | descrizione iniziale |

Una sola cosa è scritta due volte: i collegamenti. Una volta nell'intestazione, perché gli strumenti possano leggerli; una volta nel corpo, perché appaiano nella vista a rete. Tutto il resto esiste in un solo posto.

Tre criteri di qualità, opponibili a qualsiasi scheda: la definizione sta in una frase e non si mangia la coda; ogni collegamento è nominato da un verbo preciso, mai da «è collegato a»; il vocabolario è multilingue e porta le parole usate dai clienti.

Appendice B — La griglia degli scostamenti

Cosa si annota per ogni scostamento:

Le cinque nature:

Cosa succede quando lo scostamento scompare. Lo si segna come risolto, e resta nella scheda. Il corpo della scheda viene aggiornato per descrivere la nuova realtà, e una riga si aggiunge al diario. I due si rispondono: gli scostamenti portano l'intenzione, il diario porta il movimento.

Un paletto. Uno scostamento descrive una divergenza strutturale, non un incidente. Una riga, un link al ticket. Gli screenshot, i passi di riproduzione e il dettaglio restano nello strumento di tracciamento. Una scheda non è un gestore di bug.

Appendice C — Gli angoli di enumerazione

Da passare tutti, e da confrontare a due a due.

Tre regole d'uso:

1. Il segnale è il disaccordo tra due angoli, non il punteggio di un angolo preso da solo.
2. Ogni oggetto non ricollegato si decide esplicitamente — oggetto di business, o parte tecnica. Mai per omissione.
3. Due corpus cliente, contati separatamente: le interviste dicono cosa i clienti vogliono costruire, i ticket cosa si rompe. Portare entrambe le frequenze nel vocabolario — una orienta la roadmap, l'altra la documentazione e la formazione.

Dove si trovano le regole, in ordine di rendimento decrescente:

1. I nomi dei messaggi di errore tecnici. Nelle parti meno ordinate del codice è spesso la sola fonte — e si legge senza saper programmare.
2. Le verifiche fatte a inizio operazione, prima che qualsiasi cosa venga modificata.
3. I vincoli del database — cosa deve essere unico, cosa non può restare vuoto. A volte contraddicono il business, e quello scostamento è un difetto.
4. I controlli di inserimento nelle schermate — la parte più spesso dimenticata, e quella che produce gli scostamenti più interessanti.

Un oggetto descritto senza nessuna regola segnala una descrizione superficiale, mai un business senza regole.