La differenza fra una skill che dice cosa è rotto e una che lo aggiusta
Una skill che rileva problemi è utile. Una che classifica le issue per priorità, propone i comandi e li esegue automaticamente cambia il modo in cui lavoro. La differenza non è cosmetica, è strutturale.
Sto costruendo un sistema di knowledge base AI multi-brand: cinque fornitori, sette categorie merceologiche, regole tecniche per ogni dominio, eval RAGAS per misurare la qualità delle risposte. Il punto di partenza era una skill di manutenzione che eseguisse audit sistemici cross-brand prima di onboardare un nuovo fornitore.
La prima versione era un classico detector: dieci layer di verifica (coverage estrazione, integrità schema, populator, routing), un report markdown con tabelle di ✅/⚠️/❌. Funzionava: al primo run ha scovato tre bug invisibili che il sistema portava silenziosamente da settimane. Però il flusso reale era: leggi report, capisci la priorità, vai a leggere la documentazione del pattern, esegui il comando di fix manualmente. Bottleneck umano in mezzo.
Il salto qualitativo è stato passare a detector → prescriber → fixer. Per ogni codice di finding (es. L9-LOADER-DROP) ho aggiunto un ActionSpec strutturato:
ActionSpec(
code="L9-LOADER-DROP",
priority=1, effort="low", auto_fixable=True,
fix_command="python -m health_check.fixers.fix_loader_drop --apply",
fix_fn=lazy_import,
reference="anti-pattern bool/boolean (3 settimane silenti)",
)
Il report ora ha una sezione "Prescription" ordinata per priorità, separa auto-fixable da manual review, e un flag --fix all-auto applica tutto in pipeline. Il primo test reale: trenta regole prive di pagine PDF di riferimento (blocker per il context_precision RAGAS) sistemate in cinque secondi. Stima manuale dello stesso lavoro: un'ora e mezza.
La lezione sui bug invisibili è separata e merita una nota. Il pattern era questo: il loader Python accettava i tipi schema solo se in una whitelist (measurement, select, boolean, freeform), ma i file MD nuovi usavano bool, poi multiselect, poi text. Il loader scartava silenziosamente. Risultato: attributi dichiarati nello schema, mai popolati nel database, mai riempiti nelle risposte. Il bug è rimasto invisibile tre settimane perché nessun test cross-layer collegava il dichiarato al popolato. Il cross-check sistematico l'ha catturato in trenta secondi al primo run.
L'ultima osservazione riguarda la skill come asset. Sono passato da v1.0 a v1.6 in pochi giorni: ogni caso reale onboardato ha aggiunto due o tre anti-pattern documentati, oggi sono trentuno. La stima di effort per il prossimo brand è scesa del 33% rispetto al precedente, non perché il sistema sia più semplice ma perché la skill cattura preventivamente quello che prima richiedeva debug a posteriori. La conoscenza accumulata si chiude in artefatti eseguibili, non in note sparse.