# Sampling Heuristics per Mining di Sessioni AI Questo documento dettagliava le euristiche di campionamento per estrarre pattern skill-worthy da sessioni storiche ad alto volume, evitando di leggere tutto e massimizzando l'evidenza per decisione. ## Euristiche Generali ### 1. Indice Prima, Campione Secondo **Cosa fare:** - Se la fonte ha un indice (titoli, metadati strutturati), leggere l'indice per intero **per primo**. - Raggruppare i titoli per tema/dominio/parola chiave. - Solo dopo, aprire trascrizioni complete per cluster che sembrano skill-worthy. **Esempio pratico:** ``` Codex CLI: session_index.jsonl Thread 1: "React Grid Component Debug – CSS Layout Issue" Thread 2: "React Grid Component Debug – Performance Optimization" Thread 3: "Analytics Dashboard Pagination" Thread 4: "React Grid Component Debug – Event Binding" ... Clustering dall'indice: - "React Grid Component Debug": 3 sessioni (threads 1, 2, 4) - "Analytics": 1 sessione (thread 3) Azione successiva: aprire le 3 sessioni di grid-debug (per evidenza cluster), skip analytics per ora. ``` ### 2. Leggi Inizio + Fine, Non Tutto il File **Sequenza di lettura per una singola sessione:** 1. **Metadati**: timestamp, utente, titolo, durata stimata (# messaggi); 2. **Primo messaggio** (task iniziale): "cosa chiede l'utente?", qual e' il problema; 3. **Ultimi 3-5 messaggi** (conclusione): "come e' andata?", e' stato risolto? 4. **Salti selettivi** (opzionale): se il filo sembra promettente, leggi 1-2 turni di interazione nel mezzo per capire il workflow. **NON leggere:** - Ogni turno di conversazione (dispendioso); - Dettagli implementativi lunghi (es. listing completo di codice se ce n'e'); - Tentativi falliti numerosi (bastano i primi 2-3 per capire il pattern). **Payload atteso:** - Inizio: task chiaramente identificabile, domanda specifica; - Fine: esito (risolto? parzialmente? abbandonato?) e artefatto finale (codice, decisione, debug realizzato). **Tempo per sessione:** 2-5 minuti per una "scan rapida", 10-15 se la dinamica è complessa e merita approfondimento. ### 3. Campionamento per Cluster (2-4 per Cluster) **Regola:** - Non leggere tutte le N sessioni di un cluster. - Selezionare 2-4 sessioni rappresentative, preferibilmente: - **Le più recenti**: recency bias (il pattern è ancora attuale); - **Le più dense**: N messaggi >= media per il cluster (indicano una sessione matura, non un aborto veloce); - **Da date diverse**: se il cluster si estende per mesi, prendere un campione temporale (inizio, mezzo, fine). **Esempio:** ``` Cluster "React Grid Debug": 12 sessioni totali (2026-06-01 a 2026-07-08) Session A: 2026-07-08, 18 messaggi, title "Grid Event Bug – Key Bindings" Session B: 2026-07-01, 22 messaggi, title "Grid CSS Layout Issue" Session C: 2026-06-15, 15 messaggi, title "Grid Performance – Virtual Scroll" Seleziona A, B, C (coprono range date, sono dense, ultime due periodi). Skip il resto del cluster per questa run. ``` ### 4. Traccia Convergenza Multi-Fonte **Cosa fare:** - Se il pattern emerge da 2+ fonti diverse (es. Codex CLI + Claude Code), e' segnale piu' forte di pattern isolato in una sola fonte. - Annotare accanto al candidato: "Codex#12 + Claude Code project/2026-07/analytics = 2 fonti convergenti". **Scoring mentale:** - 1 fonte, 1 sessione: evidenza debole (BACKLOG o SCARTA se non soddisfa criteri); - 1 fonte, 2-4 sessioni cluster: evidenza media (considerare se workflow e' stabile); - 2+ fonti, 2+ sessioni: evidenza forte (ADOPTA se criteria sono soddisfatti). ### 5. Esclusioni e Guardrail **Non contare come pattern skill-worthy:** - **Sub-agent transitori**: se la sessione è chiaramente un sub-agent lanciato da un orchestratore (es. "analyst mode" di Claude Code che legge file e torna al padre), non vale come "pattern utente indipendente". - **One-off troubleshooting**: singolo problema spesso non ricorrente (es. "fix per una libreria deprecata in progetto X"). - **Prototipi abbandonati**: sessioni che terminano con "non usiamo questo approccio" o "shelved for future". - **Tool-specific workarounds**: hack che bypassa una skill esistente per mancanza di feature, non indicano nuova skill ma piuttosto enhancement. **Azione**: se il candidato rientra in queste categorie, muoverlo a BACKLOG o SCARTA con motivo. ## Esempio Pratico Completo (illustrativo) **Nota**: questo esempio è fittizio, costruito solo per mostrare la sequenza di passi. Per un caso REALE (dati veri, decisioni verificabili) vedi [worked-example-2026-07-10.md](worked-example-2026-07-10.md), il mining che ha originato questa stessa skill. ### Setup Fonti da analizzare (valori di esempio, non reali): - **Codex CLI**: indice sessioni tipo `session_index.jsonl` (N sessioni recenti); - **Claude Code**: cartelle progetto in `projects/` (M sessioni stimate); - **Cursor**: database SQLite locale (non esplorato per tempo in questo esempio); - **Skill inventory**: `skills/*/SKILL.md` (numero di skill esistenti al momento del mining — verificare sempre il conteggio reale con Glob, non assumerlo). Tempo budget: 3 ore. ### Step 1: Leggi Indice Codex (10 min) ```bash cat ~/.codex/workspace/session_index.jsonl | jq '.title' | sort | uniq -c ``` Output: ``` 8 React Grid Component – Debug 6 Analytics Dashboard – Query 5 API Response Caching 4 Playwright Automation 3 Database Migration 2 TypeScript Generics 14 (altri) ``` **Clustering**: React Grid = 8 sessioni (cluster promettente). ### Step 2: Campioniamo React Grid (45 min per questo cluster) Selezioniamo 3 sessioni: - `session_20260708_grid_event_binding.jsonl` (22 messaggi, piu' recente) - `session_20260630_grid_layout_css.jsonl` (19 messaggi, di mezzo); - `session_20260615_grid_virtualization.jsonl` (25 messaggi, densa). Leggi per ciascuna: 1. Primo messaggio: "Debug di event binding in grid React", "Fix CSS layout grid", "Ottimizzare rendering virtuale". 2. Ultimo messaggio/3 finale: "Bug trovato in key handler, patch applicata", "CSS rework completo, commit", "Virtual scroll implementato e testato". **Risultato**: Pattern stabile, workflow riconoscibile, output ripetibile (fix localizzati, commit). Somiglianza a skill esistente? Cross-check veloce: nessuna skill in `skills/` copre specificamente "react grid interactive debugging". Candidato: **ADOTTA nuova skill dedicata** (esempio fittizio; nella realtà del 2026-07-10 questo tipo di pattern ha portato alla creazione di `mcp-grid-ui-debugger`, vedi worked-example). ### Step 3: Campioniamo Analytics Dashboard (30 min) Selezioniamo 2 sessioni (cluster piccolo): - `session_20260707_analytics_filters.jsonl` (15 messaggi); - `session_20260625_analytics_export.jsonl` (18 messaggi). Leggi primo/ultimo: 1. "Aggiungere filtri custom alla dashboard", "Esportare dati in CSV". 2. "Filtri implementati, UI aggiornata", "Script export creato, testato". **Cross-check**: skill `mcp-analytics-operator` copre parzialmente (query, scan), ma non esportazione data. Candidato: **ENHANCE mcp-analytics-operator (aggiungere CSV/Excel export)**. ### Step 4: Resto Codex + Spot-check Claude Code (90 min) - Rapida scan dei 14 "altri" (1 minuto ciascuno, titoli solo): nessuno emerge come cluster (max 2 sessioni per tema, isolate). - Claude Code projects: apertura di 1 cartella di progetto grande, scansione titoli (150+ stimati riducibili a indice se disponibile), campiona 2 sessioni se tema nuovo rispetto a Codex. **Risultato**: nessun nuovo pattern da Claude Code che non sia gia' coperto. ### Step 5: Riassunto Finale | Candidato | Tipo | Evidenza | Decisione | Motivazione | |-----------|------|----------|-----------|------------| | (esempio fittizio) skill debug grid | Nuova skill | Codex 8 sessioni, 3 campionate, convergenti | ADOTTA | Pattern stabile, workflow ricorrente, 3 fonti convergenti (binding, layout, virtualization), no skill copre questo combo | | Enhance mcp-analytics-operator | Enhancement | Codex 6 sessioni, 2 campionate, una chiede export | ENHANCE | CSV/Excel export non coperto da skill attuale, chiesto in 1/2 sessioni campionate | | Skill X, Y, Z | (altri cluster piccoli) | max 2 sessioni isolate | BACKLOG | Evidenza insufficiente per adozione, rivisitare se ricorrente | **Limiti**: campione ~20 sessioni su ~200 stimate (10%), Cursor non toccato per tempo, Antigravity/Copilot skip. ## Checklist di Controllo Prima di concludere un mining: - [ ] Indici letti per intero per tutte le fonti (non saltati)? - [ ] Clustering manuale fatto (titoli/temi raggruppati)? - [ ] 2-4 sessioni campionate per ogni cluster promettente? - [ ] Primo messaggio + ultimi 3 messaggi letti per ogni sessione campionata? - [ ] Cross-check fatto contro skill inventory (regola 5)? - [ ] Convergenza multi-fonte annotata (se 2+ fonti)? - [ ] Candidati classificati in matrice finale (ADOPTA / ENHANCE / BACKLOG / SCARTA)? - [ ] Limiti di campionamento documentati (fonti coperte, volume, %)? - [ ] Niente dati sensibili nel deliverable?