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

Non è una domanda astratta. Non è una riflessione sulla visione a cinque anni. È una domanda sul campo, a cui bisogna rispondere entro un'ora. Allora 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. La documentazione c'è, 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.

Allora ho provato a scriverlo. Il risultato esiste: diverse decine di oggetti descritti, qualche centinaio di regole, altrettanti collegamenti fra loro. Questo articolo racconta come ci sono arrivato — e soprattutto cosa ho sbagliato lungo la strada, perché è quella la parte che si trasferisce.

Tre avvertenze prima di cominciare.

La prima: questo resoconto riguarda la fabbricazione del repertorio, non il suo utilizzo. Esiste, è misurato, ha già prodotto i suoi primi sottoprodotti. Ma la fase di sfruttamento non è cominciata. Non posso quindi affermare nulla sul ritorno dell'investimento. Chiunque ti venda una cifra a questo punto se la sta inventando.

La seconda: gli esempi sono presi da un caso fittizio — una società che pubblica un SaaS gestionale, un ERP, con i suoi clienti, i suoi ordini, le sue righe e le sue fatture. Quello 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 lato solo, una parola che i clienti usano e che il prodotto ignora. Questi 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 tagliare corto. Se devi leggerne una sola sezione, prendi «Tre criteri di arresto. Tre volte sbagliati.»: il resto è il contesto che le sta intorno. Le appendici, poi, servono solo a chi vorrà rifare il lavoro.

Un'ontologia non è un glossario arricchito

La parola è insidiosa. Ad alcuni evoca la filosofia, ad altri un campo dotto con i suoi strumenti complicati, e alla maggior parte niente del tutto. Tanto vale definirla per bene.

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

Applicata a un software, risponde a cinque domande. Ognuna corrisponde a una cosa che si scrive, e ognuna 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 fanno anche da filtro: quello che non entra in nessuna di esse non ha posto nel repertorio.

Perché un documento in più

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

Quello che li distingue da un'ontologia sta in un punto: i collegamenti contano quanto le definizioni. Un oggetto descritto da solo non insegna granché. Lo stesso oggetto collegato ad altri cinque da verbi precisi — effettuato da, contiene, fatturato in — descrive un prodotto.

Cosa riconcilia

Uno stesso oggetto porta tre nomi in un'azienda. Prendiamo l'ordine cliente:

Questi tre vocabolari evolvono separatamente, e lo scostamento fra loro è un'informazione di valore. Il repertorio lo conserva: la parola ufficiale, le parole usate dai clienti e quelle che si sono abbandonate per strada. È ciò che permette di tradurre la frase di un utente in un oggetto del prodotto — e viceversa.

Cosa non ho fatto

Esistono modi molto dotti di fare tutto questo: linguaggi dedicati, strumenti che deducono conclusioni a partire dalle regole che gli si danno, norme che vanno con essi. È un campo vero e proprio, e non ci sono andato (fra l'altro, per mancanza di competenze).

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

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

Intorno a questo prodotto, una parte crescente di ciò che descrive il prodotto viene rigenerata a partire dal codice. Il ragionamento è semplice: la verità di un prodotto è quello che gira, non quello che si era previsto.

Questo ribaltamento elimina un lavoro intero — quello di 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 significato, invece, si costruisce sopra.

Prendiamo 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 di esse si trova lì:

• la regola — un ordine fatturato non accetta 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 qualche vincolo 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 ognuna mette il proprio significato dietro la stessa parola.

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

Il costo vero si paga altrove

La domanda dell'inizio è solo un caso fra 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 si tratta di eliminare. Non compare in nessun budget, il che spiega perché la si paga da anni senza vederla.

Un'IA non può chiedere. Indovina.

Finora, ciò che il prodotto è davvero si trasmetteva a voce. Si chiedeva alla persona giusta, si otteneva la regola, si ripartiva. Il modello del prodotto viveva in qualche testa, e reggeva perché si poteva sempre bussare alla porta.

Un'IA non bussa a nessuna porta.

Quando le si affida un'evoluzione, la si descrive 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ù quello che riesce a leggere nel codice. Il resto lo riempie lui — in modo plausibile, coerente e a volte falso.

Lo scostamento fra quello che volevamo e quello che ci ritroviamo è esattamente la parte del nostro modello mentale che non abbiamo scritto.

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

Chiedere un'evoluzione senza rispiegare il prodotto. «Aggiungi uno sconto sugli ordini.» Con il repertorio nel contesto, l'agente sa che un ordine fatturato non accetta più righe, che uno sconto ha un tetto massimo e che «ordine» comprende anche gli ordini urgenti e gli ordini permanenti. Senza, scoprirà una di queste tre cose in fase di rilettura — 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 sola, si legge in qualche secondo. E qualche centinaio di schede sta dentro un contesto là dove migliaia di file di codice non ci stanno: l'agente legge quello che serve invece di frugare a caso.

Scrivere i test e decidere sulle segnalazioni. Una regola è un'affermazione verificabile. «Un ordine fatturato non accetta più righe» è un test, così com'è, formulato nel linguaggio del business. Qualche centinaio di regole sono altrettanti test candidati che nessuno ha bisogno di dedurre dal codice. E davanti a una segnalazione di un cliente la domanda diventa meccanica: questa cosa contraddice una regola scritta — allora è un bug; oppure è una regola che nessuno aveva mai posto — allora è una decisione di prodotto, non un difetto. Oggi questo verdetto lo dà l'esperienza, cioè la persona più anziana della squadra.

Niente di tutto questo è misurato, in linea con l'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 repertorio nel contesto e l'altra metà senza, 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 pone subito. Senza un modello, anche grossolano, non si sa quale materiale raccogliere — e si passa accanto a informazioni importanti senza saperlo. Senza materiale, non si sa quale modello reggere.

Iterare, non sequenziare. Si abbozza quel tanto che basta per sapere cosa cercare, si cerca, si riprende il modello con quello che si è imparato. Un vincolo attraversa tutti questi andirivieni: quello che si raccoglie viene immagazzinato nella forma più semplice possibile, e sempre con l'indicazione di dove viene. Un cambio di modello non deve mai costringere a tornare a cercare quello che si ha già.

Da dove cominciare: una ventina di 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 repertorio 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 quello che crediamo importante.

Quindi non le ho scritte. Sono andato a cercarle.

Le domande sul prodotto che ci arrivano sono archiviate con la loro risposta. Le ho rilette tutte, poi le ho condensate in una ventina di domande generiche. Nessuna esce dalla mia immaginazione: ognuna copre un insieme di domande realmente poste.

Trasposte sull'ERP fittizio, assomigliano a questo:

• Quali sono gli stati di un ordine, e quali passaggi sono permessi dall'uno all'altro?
• Cosa si può ancora annullare, e da quale momento non lo si può più fare?
• Cos'è il saldo di un cliente, e con quali movimenti evolve?
• A chi spetta un ordine generato automaticamente, e cosa ne è se quella persona lascia l'azienda?
• In quali casi l'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, diverse volte al mese.

Cosa dà immediatamente: l'ordine di lavoro. Ogni domanda tocca una o più aree del prodotto; basta contare. Più della metà delle domande cadeva sulla stessa — è diventata la prima. Il resto si distribuiva su altre due. L'ordine non è più una preferenza, è un conteggio.

E servono una seconda volta, all'arrivo. Una volta finita un'area, si riprendono le sue domande e si verifica che il repertorio risponda senza aprire il codice. Il controllo fatto a metà percorso ha lasciato solo due domande senza risposta completa. Le due mancanti lo erano allo stesso modo: una regola scritta in generale là dove la domanda si aspettava il dettaglio — «certe operazioni richiedono questo» senza mai dire quali.

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

Una scheda per oggetto, e collegamenti fra loro

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

Questo dettaglio sembra cosmetico. Non lo è. Le schede e i loro collegamenti formano una rete, e questa rete si visualizza: 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 un oggetto resta da descrivere.

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

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

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

Tengo entrambe, in due posti distinti della stessa scheda. Il corpo della scheda descrive la realtà, com'è nel codice. Un blocco separato, in fondo alla scheda, elenca gli scostamenti: ogni punto in cui questa realtà diverge da quello 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ò buttarlo e rifarlo senza perdere niente. Gli scostamenti, invece, portano un giudizio — non si ritrovano da nessuna parte se li si perde. Separarli significa proteggere la parte che costa cara da produrre.

Un punto che spesso si fraintende: quando tutto va bene non si scrive niente. Se il prodotto fa quello 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, ed è un'informazione di per sé.

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

Il punto di partenza: un'istantanea, presa in un momento dato

Si descrive il prodotto com'è in un momento dato. Una versione del codice, e tutto ciò che gira insieme a essa: la base com'è a quella versione, le schermate di quella versione, le traduzioni di quella versione. È l'istantanea.

Quello che ci figura sopra è lo stato iniziale, senza data di nascita: non cerco di sapere quando è comparso ogni campo. Ricostruire la storia del prodotto richiederebbe di frugare anni di archivi per un beneficio nullo.

Più avanti si prende una nuova istantanea, e si aggiornano le schede con quello che è cambiato fra le due. È tutto qui il meccanismo.

L'unica cosa da sorvegliare, e ci sono cascato: una fonte che non viene dall'istantanea non è una fonte. Ci torno più avanti.

Quattro posti da leggere, nessuno facoltativo

Uno stesso oggetto è descritto in quattro posti del prodotto, e ognuno dice quello che gli altri tacciono:

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

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

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

O è una vera regola di business, messa nel posto sbagliato — un attrito. Oppure è aggirabile passando accanto alla schermata, con un import di file o attraverso l'interfaccia che il prodotto espone agli sviluppatori esterni — la sua API. E allora è un difetto, con implicazioni di sicurezza: quello che la schermata vieta, un altro percorso lo consente.

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

Due constatazioni su questa lettura delle schermate.

Prima di tutto, la suddivisione delle schermate non coincide con quella del codice. Diverse zone dell'interfaccia non avevano una zona equivalente lato server. Il raffronto si fa quindi oggetto per oggetto, mai cartella per cartella.

Poi, un trucco che vale oro nelle parti del codice meno ordinate: i nomi dei messaggi d'errore tecnici sono spesso la migliore fonte di regole. Uno sviluppatore che rifiuta un'azione crea un caso d'errore, e gli dà un nome. Un errore chiamato CannotEditInvoicedOrder — «non si può modificare un ordine fatturato» — enuncia una regola da solo. Basta leggere la lista di questi nomi, il che non richiede di saper programmare.

Niente di tutto questo è originale

È forse il punto più utile di questa sezione. Costruire ontologie è un mestiere costituito, con la sua letteratura, e il metodo qui sopra non fa che riprendere risultati già consolidati:

• L'iterativo invece della cascata. I metodi storici incatenavano le fasi in ordine: specificare, progettare, formalizzare, realizzare. Sono stati soppiantati da approcci a piccoli pezzi ricombinabili. Il dibattito è chiuso da una quindicina d'anni.
• L'inquadramento tramite domande. Scrivere prima le domande a cui il repertorio dovrà rispondere è lo strumento standard; ha perfino un nome, competency question. Andarle a cercare nel supporto invece di scriverle a freddo non è nei manuali. Non costa niente, e cambia quello che si trova.
• Partire dal mezzo. Si comincia dagli oggetti più centrali del business, poi si risale verso le categorie più ampie e si scende verso i casi particolari. Gli altri due modi di procedere falliscono: partire dalla base di dati equivale a ricopiare la struttura tecnica così com'è, con le sue tabelle che non vogliono dire niente per il business; partire da una teoria generale di ciò che esiste dà un edificio sproporzionato rispetto al bisogno.
• Il rigore proporzionato all'uso. Ci si complica la vita quando serve, non per principio.
• Non reinventare ciò che è normato. Nella maggior parte dei settori esistono classificazioni che fanno da riferimento. Bisogna guardarle — e trattare ogni scostamento fra il proprio modello ed esse come una questione da analizzare, 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 spontaneamente, ed entrambi falliscono.

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

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

Ho quindi scelto una terza via: un'area del prodotto alla volta, partendo dal cuore del business verso la periferia, appoggiandomi alla suddivisione che il codice porta già con sé. Un software un po' grosso è suddiviso in moduli — zone di codice che corrispondono grossolanamente ad aree del business: la fatturazione, gli acquisti, i diritti di accesso. Questa 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 quello che è successo dopo.

Primo criterio: «la rete di schede è chiusa»

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

È falso, e la ragione è meccanica. Un insieme di schede che si citano solo fra loro chiude la propria rete molto prima di aver coperto il prodotto. Da me la rete si è chiusa quando una minoranza dei moduli aveva dato luogo a una scheda.

Cosa dimostrava davvero questo controllo: che l'insieme sta in piedi. Nient'altro. È un buon controllo, va tenuto — ma non risponde alla domanda posta.

Il controllo di copertura fatto dopo ha fatto emergere due oggetti centrali del business che niente, nella rete, reclamava.

Secondo criterio: «ho percorso tutte le mie fonti»

Il codice delle due applicazioni, la base di dati, l'API, il glossario, i resoconti delle interviste, i ticket del supporto. Non c'è più niente da aprire.

È vero, e non dimostra niente. È un'affermazione su quello che ho aperto, non su quello che esiste. «Ho letto tutta la mia pila» non dice nulla sulla biblioteca: finché il prodotto non è enumerato, «tutto» non ha denominatore. Un modulo che non è mai figurato sulla mia lista non figura nemmeno nel mio «tutto».

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

Il cuore del codice, la base di dati, le schermate, le traduzioni.

Vero anche questo, e insufficiente per la stessa ragione: vale solo per le aree che avevo identificato. Il criterio misura la profondità, non dice niente sull'ampiezza. Si possono leggere quattro posti su una minoranza dei moduli e ignorare tutto il resto — è esattamente quello che è successo.

La diagnosi

Riprendiamo i tre, e quello che ognuno dimostrava davvero.

Tutti e tre dicono la stessa cosa: ho finito quello che avevo cominciato. Nessuno dice: non resta niente.

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

È la differenza fra «ho messo via tutto quello che stava in giro sulla scrivania» e «ecco la lista di quello che dovevo mettere via, è tutto spuntato». La prima frase è vera, e non impegna a niente. La seconda presuppone di aver fatto la lista prima di cominciare.

Non è disonestà, è una questione di costo.

Un criterio che si può soddisfare è già a portata di mano: basta guardare quello che si è appena fatto e constatare che è fatto. Un criterio che dimostra, invece, richiede di fabbricare qualcosa in più — la lista di quello che esiste, un modo di contarla, una cifra che qualcun altro potrebbe ricalcolare. È lavoro in più, richiesto nel momento preciso in cui si crede 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 fra quelli che si è già certi di soddisfare.

L'unico criterio che regge

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

Ogni angolo vede quello che gli altri non possono vedere:

E soprattutto: il segnale utile è il disaccordo fra due angoli. Un oggetto presente in uno e assente dagli altri o è un oggetto del business che si è mancato, o è infrastruttura tecnica. La questione si decide in una riga — ma si decide esplicitamente, mai passandoci accanto.

Gli altri errori

Quattro, più piccoli, tutti costosi.

Leggere una fonte che non era sull'istantanea. L'export della base di dati di cui disponevo era stato prodotto diversi mesi prima della versione di codice che stavo descrivendo. L'ho letto come se descrivesse lo stesso prodotto. Descriveva un prodotto più vecchio: su un'area intera gli oggetti c'erano nel codice senza nessuna tabella corrispondente nell'export, e ne ho concluso che non esistessero.

La regola è più semplice di quello che credevo sul momento. Non è «verificare la data prima di concludere» — è che una fonte che non viene dall'istantanea non è una fonte. La si sostituisce con una versione aggiornata, oppure se ne fa a meno.

E la precisazione che conta, perché all'inizio l'avevo mancata: quando due parti della stessa istantanea si contraddicono — il codice da un lato, la base o la schermata dall'altro, nello stesso momento, in produzione — non è uno sfasamento. È un'incoerenza del prodotto. È esattamente quello che si sta cercando.

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

Ma un motore di questo genere 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 voler dire due cose — la cosa non esiste, oppure ho posto male la domanda. Impossibile decidere.

Da qui la regola: prima enumerare, poi cercare. Nel senso opposto si ottiene un repertorio fatto di quello che il motore ha voluto riportare.

Due dettagli che costano cari. Il motore aveva una sua data, una versione di ritardo sul codice. E bisogna porre la domanda nella lingua del codice: una domanda posta in francese su un codice scritto in inglese dà risultati mediocri, anche quando la risposta c'è.

Scrivere la stessa regola in tre posti. Strada facendo si sono costituiti 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 si cambia niente, non dà fastidio a nessuno. Il giorno in cui la regola evolve se ne corregge uno, ci si dimentica degli altri due, e tre documenti si contraddicono senza che nessuno sappia quale fa fede. Un'IA meno degli altri: legge tutti e tre senza vedere che divergono, e fonda la sua analisi su quello che ha aperto per primo.

Ogni regola vive ormai in un posto solo. 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: stavo costruendo un repertorio 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 diverse centinaia di resoconti di interviste.

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

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

Esiste anche l'errore inverso, ed è più subdolo. Un termine che credevo assente dal prodotto c'era, ma usato in tutt'altro senso, in un angolo tecnico senza rapporto con il business. Verificare 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 fra oggetti non era descritto correttamente nel prodotto. Verifica fatta, lo era.

Lo scostamento resta nella scheda, segnato come respinto, con il motivo del rifiuto. Sbagliarsi fa parte del lavoro, a patto che l'errore lasci una traccia utilizzabile — altrimenti fra sei mesi lo stesso errore lo rifarà qualcun altro.

L'agente raccoglie. L'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 solo di ontologia.

Precisazione di metodo: questa sezione non si basa sul ricordo di nessuno. Il registro delle decisioni del cantiere è 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 fra una mia decisione e l'altra. Tutto quello che segue si legge in queste due tracce.

Cosa fa notevolmente bene un agente: enumerare, incrociare, contare, tenere traccia 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 finora lo rendeva inaffrontabile.

Ciò in cui sbaglia: dichiarare il lavoro finito. I tre falsi criteri di arresto non sono venuti dal nulla — sono stati proposti, ognuno, come prova di completamento, e ogni volta è stato necessario rifiutarli. La distorsione è la stessa che si vede in un umano stanco a fine progetto, con la differenza che lui non ha la stanchezza come scusa: confondere riferire e consegnare.

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

• Allargare un perimetro che aveva implicitamente ristretto. L'agente leggeva il cuore del codice e si fermava lì. La regola dei quattro posti, schermate comprese, viene da lì — ed è proprio nelle schermate che si trovano gli scostamenti più interessanti.
• Correggere una struttura destinata a divergere. La stessa regola scritta in tre posti: l'aveva ricopiata per il desiderio di fare bene, che era esattamente quello che non bisognava fare.
• Rifiutare un criterio di arresto troppo comodo. Tre volte.

Ciò che rende possibili queste decisioni sta in quattro accorgimenti, e valgono per qualunque lavoro delegato — a una macchina come a un'altra persona:

1. Un criterio di arresto verificabile da terzi. Non «ho letto tutto», ma una lista e una percentuale.
2. Una misura che si può rilanciare, invece di un'affermazione. Fra «è coperto» ed «ecco il comando che lo verifica» c'è tutta la distanza fra 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 è lui a evitare di rifare due volte la stessa cosa.
4. L'enumerazione prima della ricerca. Quello che è certo prima, quello che è probabile dopo e in aggiunta.

Il risultato, e sette modi per verificare che non manchi niente

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

Diverse decine di oggetti del business descritti. Qualche centinaio di regole. Altrettanti collegamenti fra loro. Numerosi scostamenti rilevati. Nessun collegamento che punti più nel vuoto.

Le domande di partenza trovano la loro risposta senza aprire il codice.

La copertura, misurata

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

I sette angoli scelti: i moduli dell'applicazione A, le tabelle della base di dati, gli eventi emessi dal software, le schermate dell'applicazione A, i moduli e gli oggetti dell'applicazione B, le risorse esposte dall'API.

Le percentuali ottenute si scaglionano fra il 70 e il 95 % a seconda dell'angolo.

La misura si rigioca con un piccolo programma. È questo 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'abbinamento si fa sui nomi: una tabella sales_order viene riconosciuta come la scheda «Sales Order», maiuscole, trattini e plurali messi da parte.

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

Questa lista è un giudizio, non una regola. Se dimentico una riga, l'oggetto risulta non coperto mentre lo è. Se ne aggiungo una dubbia — «dai, questa tabella deve pur corrispondere a questa 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 dimostra niente. Indica dove andare a guardare.

Perché non cerco di arrivare al 100 %

È l'obiezione immediata: se conosco la quota di moduli che non hanno una scheda, so quali sono — basta descriverli.

Solo che la casella mancante non è un compito, è una domanda. Ogni oggetto senza scheda o è un oggetto del business che ho mancato, o è infrastruttura tecnica senza nessun 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 di creare una scheda «Coda» e una scheda «Token» — cioè di inquinare il repertorio per far salire una cifra.

Il contatore ha quindi tre stati, e non due:

Quello che deve arrivare al 100 % è la terza riga a zero — più niente 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: elementi tecnici, meccanismi interni, schermate senza un oggetto di business proprio. Nessun oggetto del business ci si nascondeva. Ma è una verifica manuale, da rifare a ogni evoluzione — ed è la debolezza che rimane.

La cifra serve quindi a qualcos'altro che misurare un avanzamento. Serve a confrontare gli angoli fra loro. La più bassa delle sette percentuali, sugli oggetti dell'applicazione B, contro la più alta, sugli eventi: lo scarto non vuol dire «resta tutto questo lavoro da fare», vuol dire «l'applicazione B manipola cose che il resto del prodotto ignora, andate a guardare da quella parte». È questo disaccordo che ha fatto emergere le quattro scoperte seguenti.

Cosa hanno riportato gli angoli

Quattro oggetti che nessun'altra via avrebbe trovato:

• Dalle tabelle della base. 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 scadenzario, ma esiste davvero solo nel momento in cui la fattura viene emessa. Questa ambiguità spiega un'intera famiglia di reclami dei clienti.
• Dagli eventi. Un sottoinsieme intero di un'area che si credeva coperta, rivelato dagli eventi che emetteva e che nessuno aveva collegato a niente.
• Dall'API. Alcuni oggetti distribuiti su più moduli — quindi invisibili finché si avanza area per area, eppure 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 di essi è 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 una regola centrale. Due schermate finiscono col 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 nello scadenzario, 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 valore non è. Il saldo di un cliente non è un numero conservato 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 dà una cifra leggermente diversa, a seconda dei movimenti che ha pensato di includere. Tre schermate, tre saldi.

Una regola applicata da un lato solo. Il tetto massimo dello sconto controllato nel modulo di inserimento, e da nessun'altra parte — quindi aggirabile con un import di file o attraverso l'API. È la macchina per scostamenti di cui parlavo più sopra, e il suo rendimento è notevole.

Un diritto calcolato a partire 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, il perimetro della sua filiale, una lista di eccezioni. Nessun posto del prodotto dice «ecco come si calcola un diritto». Ogni evoluzione lo riscopre a proprie spese.

Uno stesso oggetto chiamato 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 in continuazione e che il prodotto ignora. Su questo corpus di interviste una nozione torna diverse decine di volte, un'altra un po' meno. Né l'una né l'altra esiste nel prodotto, sotto nessun nome. Non sono scostamenti di vocabolario, sono mancanze di progettazione — e compaiono solo confrontando quello che dicono i clienti con quello che fa il prodotto.

I sottoprodotti

Nessuno era l'obiettivo. Sono tutti caduti dal lavoro.

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

Un vocabolario dei clienti, con le sue frequenze. Contando le parole su un corpus importante di resoconti di interviste e di ticket del supporto si ottengono, per ogni oggetto del prodotto, i termini realmente usati e il loro peso. Chi parla con il cliente sa allora quale parola usare. Un termine torna più di cento volte per designare un perimetro che il prodotto chiama in un altro modo; un altro quasi altrettante 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 stabilire le priorità in modo sbagliato.

Una ricognizione dello stato delle traduzioni. Il glossario multilingue copre solo una minoranza degli oggetti descritti. Fra gli assenti, alcuni sono però mostrati all'utente in tutte le lingue: per loro non esiste nessuna traduzione di riferimento. E sull'insieme delle lingue del glossario ne è stata riletta solo una piccola parte.

Quanto costa, e quello che il metodo continua a non dire

Il costo

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

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

Tre riserve su questa cifra, perché resti onesta. È una misura su un prodotto, una volta, non una media. Le fonti erano già raccolte e indicizzate in locale; il tempo di preparazione non è compreso. E dice tanto sull'attrezzatura quanto sul metodo: lo stesso lavoro a mano avrebbe richiesto 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 repertorio completo su un perimetro serve immediatamente a tutte le funzioni aziendali di quel perimetro. Un repertorio fatto a metà su cinque perimetri non serve a nessuno.

La manutenzione

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

La versione di riferimento fa da cursore: dà, con un semplice comando, la lista esatta di quello che è cambiato nel prodotto dall'ultimo aggiornamento — quindi la lista di quello 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 a essere cambiata, non il prodotto. La distinzione sembra minore; è lei che permette, sei mesi dopo, di sapere se si è corretta una scheda o se il software è evoluto.

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

Infine, quando un oggetto viene ripensato da cima a fondo, non si modifica la sua scheda: se ne crea una nuova, e la vecchia resta. Descrive quello 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 sugli export di dati, che sono viste derivate dal prodotto e non il prodotto stesso.
• Nessuno strumento sofisticato finché un uso non lo richiede.

Cosa il metodo non dice ancora

• Fino a che punto spingere il rigore del formato. Dipende dall'uso, e l'uso non è cominciato.
• Come collegare un dato vecchio allo stato giusto di un oggetto, quando quell'oggetto è stato ripensato nel frattempo.
• Chi rilegge una scheda, e secondo quali criteri, prima che entri nel repertorio.
• Con quale ritmo aggiornare il punto di partenza, e quindi recuperare quello che è cambiato 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 domande vengono decise.

Conclusione: il criterio di arresto è il vero risultato da consegnare

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

Si sceglie un criterio che si può soddisfare, invece di un criterio che dimostra 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 si conclude con «ho guardato tutto», la domanda da porre è: tutto, cioè? Ne hai la lista?

Due controlli, mai uno solo. Che l'insieme stia in piedi si verifica guardando le schede fra loro. Che sia completo si verifica enumerando il prodotto. Confonderli è costato, qui, una parte importante del prodotto.

Resta la cosa più interessante, e non è fatta: gli scostamenti. Aspettano tutti di essere analizzati — prima i bug candidati, poi quelli che una richiesta di un cliente già sostiene, poi le mancanze, poi il debito di progettazione. Non è più descrizione, è decisione di prodotto.

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

Appendice A — Com'è fatta una scheda

Questa appendice è la più tecnica dell'articolo; ci si può fermare 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 posto solo.

Cosa contiene una scheda

La scheda in sé

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

---
concetto: Sales Order
definizione: Impegno di consegna preso verso un cliente, seguito dalla registrazione fino alla fatturazione.
genitore:
figli: ["[[Rush Order]]", "[[Standing Order]]"]
attributi:
  - nome: status
    tipo: enum
    valori: [draft, confirmed, shipped, invoiced]
relazioni:
  - verbo: placed-by
    destinazione: "[[Customer]]"
    cardinalita: 1..1
  - verbo: contains
    destinazione: "[[Order Line]]"
    cardinalita: 1..n
assiomi:
  - Un ordine fatturato non può più ricevere righe
lessico:
  it: [ordine, ordine cliente]
  en: [sales order]
  es: [pedido]
  sinonimi_campo: [affare, pratica]
  deprecati: [buono d'ordine cliente]
fonti:
  - erp.sql:table `sales_order`
  - it.json:order.status.draft
scostamenti:
  - id: E1
    natura: mancanza
    ambito: relazioni
    atteso: un collegamento verso "[[Attachment]]", come ne ha "[[Customer]]"
    conseguenza: impossibile allegare un buono d'ordine firmato
    stato: confermato
    data: 2026-08-10
storico:
  - data: 2026-08-10
    azione: creazione
    motivo: descrizione iniziale, sulla versione di riferimento
---

# Sales Order

Impegno di consegna preso verso un cliente, seguito dalla registrazione fino 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 cosa sola è scritta due volte: i collegamenti. Una volta nell'intestazione, perché gli strumenti possano leggerli; una volta nel corpo, perché compaiano nella vista a rete. Tutto il resto esiste in un posto solo.

Tre criteri di qualità, vincolanti per qualunque scheda: la definizione sta in una frase e non si morde la coda; ogni collegamento è chiamato con un verbo preciso, mai con «è 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 sparisce. 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 collegamento al ticket. Gli screenshot, i passi di riproduzione e il dettaglio restano nello strumento di tracciamento. Una scheda non è uno strumento di gestione dei bug.

Appendice C — Gli angoli di enumerazione

Da passare tutti, e da confrontare due a due.

Tre regole d'uso:

1. Il segnale è il disaccordo fra due angoli, non il punteggio di un angolo preso da solo.
2. Ogni oggetto non collegato si decide esplicitamente — oggetto del business, oppure infrastruttura tecnica. Mai per omissione.
3. Due corpus dei clienti, contati separatamente: le interviste dicono cosa i clienti vogliono costruire, i ticket cosa si rompe. Portare entrambe le frequenze nel vocabolario — l'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 d'errore tecnici. Nelle parti del codice meno ordinate è spesso l'unica fonte — e si legge senza saper programmare.
2. Le verifiche fatte all'inizio di un'operazione, prima che qualunque cosa venga modificata.
3. I vincoli della base di dati — cosa deve essere unico, cosa non può restare vuoto. A volte contraddicono il business, e questo 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.