keep-the-caveat-with-the-number
Una cifra e la sua precisazione devono essere un solo artefatto. Due paragrafi si allontanano; un componente non può.
Conferita da chi ha letto la scheda, non rivendicata dal file su se stesso. Una scheda che l'agente distilla durante un'esecuzione che ha consumato contenuti non affidabili nasce contaminata e resta in attesa di revisione prima di essere mai recuperata.
Quando viene in mente
- pubblico il risultato di un benchmark
- metto una metrica in una pagina
- il numero richiede contesto
- riassumo una misurazione
Il valore di solito sta in Evita e Verifica. Fai è la sezione che scrivono tutti.
Il corpo della scheda qui sopra è una traduzione. L'originale inglese è ciò che la CLI importa, ciò che l'agente legge in esecuzione e ciò che l'hash qui sotto attesta.
Trigger
Stai mettendo una cifra misurata in un punto dove un lettore la vedrà: un README, una landing page, delle note di rilascio, una dashboard, un report. La cifra è vera e ha bisogno di una frase accanto per non fuorviare — il campione era piccolo, il sottoinsieme era facile, l'effetto non era significativo, il benchmark era nostro.
Non si applica a una cifra il cui significato è completo di per sé. "La build ha impiegato 41 secondi" non ha bisogno di nulla.
Fai
- Scrivi prima la clausola di cautela, prima del numero. Se non riesci a formulare il limite in una sola frase, non capisci ancora abbastanza bene la misurazione per pubblicarla.
- Rendi la clausola di cautela strutturalmente attaccata. Mettila nello stesso componente, nella stessa riga di tabella, nello stesso valore di ritorno di funzione — qualcosa che non può renderizzare la cifra senza di essa.
- Mettila sopra il numero, o accanto. Non sotto.
- Rendi il numero stesso derivato: leggilo dall'artefatto prodotto dalla misurazione, così si aggiorna quando si aggiorna la misurazione.
Evita
Il numero nel titolo e la clausola di cautela in una nota a piè di pagina, un asterisco, una sezione comprimibile, o il paragrafo successivo. Sono tutti lo stesso bug con uno styling diverso: il lettore si forma prima la convinzione, e una correzione che arriva dopo deve superare una convinzione già esistente.
Evita anche la versione di secondo ordine — un componente che può renderizzare la cifra con la clausola di cautela omessa. Se la qualificazione è un argomento opzionale, verrà omessa, e verrà omessa da qualcuno che sta stringendo un paragrafo senza alcuna intenzione di cambiarne il significato.
E non parafrasare una clausola di cautela scritta con cura. È nella riformulazione che "non significativo di per sé" diventa "vicino alla significatività".
Verifica
Prova a scrivere il numero senza la clausola di cautela e osserva il fallimento. Elimina l'argomento di qualificazione, oppure metti una cifra nuda in una pagina, ed esegui la build.
Se compila, l'abbinamento è una convenzione e non un meccanismo, e le convenzioni sopravvivono esattamente finché nessuno ha fretta.
Rischio
Applicato in eccesso, questo appesantisce la reportistica ordinaria: non ogni numero è un benchmark, e una clausola di cautela su una cifra che non ne ha bisogno insegna alle persone a saltare le clausole di cautela.
Il rischio più difficile è che un meccanismo sembri la risposta completa. Un componente che renderizza sempre una qualche clausola di cautela non verifica se quella clausola è quella giusta. La frase deve comunque essere scritta onestamente da una persona; questo impedisce solo che venga tolta in seguito.
Come usarla
La scheda è un dato. Clona il repository e importala per percorso — ciò che arriva dalla rete è trattato come contaminato e trattenuto in attesa di approvazione, che è il comportamento desiderabile e il motivo per cui qui non c'è un installatore in una riga.
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/keep-the-caveat-with-the-number/SKILL.mdIntegrità
SHA-256 del file così com'è pubblicato. Chi lo importa può verificare che ciò che ha ricevuto sia ciò che questa pagina mostrava.
98a524b60de3f913785f477d03a8a49b428afe7f31d9996b72563f17f8b287d6