--- name: edilcrm-ui-audit description: Use when l'utente chiede revisione interfaccia, debug visivo, accessibility audit, consistency check fra pagine, dice "non torna" / "lampeggia" / "spinner appeso" / "label confusa", o cita le rotte /finanza, /finanza/programmazione, /scadenze, /cantieri, /personale, /clienti, /anagrafiche, /impostazioni della webapp EDIL CRM. --- # edilcrm-ui-audit Punto d'ingresso per il debugging UI/UX della webapp EDIL CRM. Orchestra agenti specializzati, mantiene memoria delle sessioni precedenti tramite log strutturati, e dispone di un quadro aggiornato della struttura dell'app. ## Quando usare questa skill Trigger espliciti: - "Audit pagina X", "rivedi UI di X", "guarda l'interfaccia di X" - "Debug visivo", "verifica accessibilita", "tasto Tab non funziona" - "Le date non tornano fra /finanza e /scadenze" (coerenza dati cross-page) - "Spinner appeso", "doppio render", "layout shift" - Menzione esplicita di una rotta: `/finanza`, `/finanza/programmazione`, `/scadenze`, `/cantieri`, `/cantieri/[id]`, `/personale`, `/clienti`, `/impostazioni`, `/anagrafiche` - "Microtesto poco chiaro", "label confusa", "toast non parla italiano coerente" Non usare per: - Implementazione di fix (vedi sezione "Limiti") - Modifiche al DB - Decisioni di prodotto su quali feature aggiungere ## Architettura Karpathy: raw → wiki → output La skill si articola su tre livelli con semantica differente: - **`raw/`** — osservazioni grezze. Un file per sessione, datato. Niente interpretazione: screenshot, log console, errori riprodotti, descrizione dei passi. Sorgente primaria. - **`wiki/`** — conoscenza distillata che PERSISTE tra sessioni. Mappa dell'app, convenzioni di design, glossario, flussi critici, pattern di bug ricorrenti. Si aggiorna SOLO a partire da `raw/`, mai inventato. - **`output/`** — artefatti finali per l'utente: report di audit, action items prioritizzati pronti per essere passati a un altro task Claude (es. "fixa scroll su CashflowTable"). ### Regola di flusso (non negoziabile) Una sessione di audit produce **SEMPRE** un file in `raw/sessions/`, e **SOLO DOPO** eventualmente aggiorna `wiki/` e produce `output/`. Mai scrivere direttamente in `wiki/` o `output/` senza un raw di supporto. Ogni aggiornamento del wiki cita la fonte raw da cui deriva (link relativo). ## Workflow standard di una sessione ``` (a) Leggi wiki/ per orientarti (sempre). └─ Almeno: app-structure.md, routes-map.md, design-conventions.md, known-issues.md per non duplicare audit già fatti. (b) Decidi quali agent dispatchare in parallelo (vedi agents/README.md per la tabella decisionale). (c) Dispatcia via Task tool, in PARALLELO quando indipendenti. └─ Esempio: visual-critic + a11y-auditor + content-critic sulla stessa rotta possono girare insieme. (d) Aggrega i loro report. (e) Scrivi raw/sessions/YYYY-MM-DD-HHMM-.md con il format definito in raw/README.md. (f) Se emergono pattern nuovi o conferme di pattern esistenti → aggiorna wiki/known-issues.md (o wiki/design-conventions.md se è una nuova convenzione consolidata). Cita sempre il file raw da cui viene l'aggiornamento. (g) Produci output/reports/YYYY-MM-DD-.md (riepilogo per l'umano) e aggiungi righe a output/action-items.md con priorita P/M/B. ``` ## Convenzioni di logging ### Naming file - `raw/sessions/`: `YYYY-MM-DD-HHMM-.md` - Esempio: `2026-05-19-1545-finanza-programmazione.md` - `` è la rotta principale dell'audit con `/` sostituiti da `-`, lowercase, senza accenti. - `output/reports/`: `report-YYYY-MM-DD-.md` - Esempio: `report-2026-05-19-finanza-programmazione.md` - Screenshot: `raw/screenshots/YYYY-MM-DD-HHMM-.png` - Riferiti dal raw con link relativo `../screenshots/...`. ### Frontmatter YAML I file in `raw/sessions/` e `output/reports/` iniziano con frontmatter YAML. Vedi i template in `raw/README.md` e `output/README.md`. ## Agenti disponibili Dispatch tramite `Task` tool con `subagent_type=general-purpose`. Il prompt vive in `agents/.md` e viene passato verbatim al subagent. | Agent | Scope | Quando usarlo | Parallelo? | |---|---|---|---| | [user-simulator](agents/user-simulator.md) | Simula percorsi utente reali sul dev server | Audit di flusso end-to-end | Solo, blocca le altre | | [visual-critic](agents/visual-critic.md) | Critica visiva (gerarchia, spazi, contrasto) | Schermata "non torna" visivamente | Sì | | [content-critic](agents/content-critic.md) | Microtesti, label, toast, stati vuoti | Coerenza testuale e di tono | Sì | | [a11y-auditor](agents/a11y-auditor.md) | Tab order, focus, aria, contrasti | Verifica accessibilita | Sì | | [data-consistency](agents/data-consistency.md) | Coerenza dati cross-page | "Numeri diversi fra pagine" | Sì | | [perf-watcher](agents/perf-watcher.md) | Lentezza, layout shift, doppi fetch | UX percepita lenta o "lampeggia" | Sì | Tabella decisionale completa in [agents/README.md](agents/README.md). ## Quick reference | Cosa devo fare | Vai a | |---|---| | Capire la struttura dell'app prima di iniziare | [wiki/app-structure.md](wiki/app-structure.md) | | Sapere quale rotta tocca quale file/data | [wiki/routes-map.md](wiki/routes-map.md) | | Verificare se uso label/colori giusti | [wiki/design-conventions.md](wiki/design-conventions.md) | | Capire un termine di dominio (es. "consolidata in piano") | [wiki/glossary.md](wiki/glossary.md) | | Sapere se il flusso e' critico | [wiki/critical-flows.md](wiki/critical-flows.md) | | Verificare se il bug e' gia noto | [wiki/known-issues.md](wiki/known-issues.md) | | Scegliere quale agent dispatchare | [agents/README.md](agents/README.md) | | Loggare la sessione | `raw/sessions/YYYY-MM-DD-HHMM-.md` (template in [raw/README.md](raw/README.md)) | | Produrre output finale | `output/reports/report-YYYY-MM-DD-.md` + righe in [output/action-items.md](output/action-items.md) | ## Wiki — punti d'orientamento Prima di qualsiasi dispatch, leggi: - [wiki/app-structure.md](wiki/app-structure.md) — stack e organizzazione codice. - [wiki/routes-map.md](wiki/routes-map.md) — tutte le rotte con file, auth, dati. - [wiki/design-conventions.md](wiki/design-conventions.md) — toast, dialog, colori, formati. - [wiki/glossary.md](wiki/glossary.md) — termini di dominio EDIL CRM. - [wiki/critical-flows.md](wiki/critical-flows.md) — flussi che non devono rompersi. - [wiki/known-issues.md](wiki/known-issues.md) — bug noti e pattern ricorrenti. ## Common mistakes e rationalizations Pattern di violazione della regola di flusso "raw → wiki → output" e contro-argomenti pronti. | Excuse | Reality | |---|---| | "E' una sessione veloce, salto raw e vado dritto a output" | Senza raw non c'e' tracciabilita: il prossimo audit non saprà cosa hai gia verificato. Scrivi raw anche se e' di 10 righe. | | "Aggiorno wiki/known-issues al volo, lo verifico dopo" | Wiki che cita una fonte raw inesistente diventa speculazione. Prima il raw, poi il wiki. | | "Tanto so gia cosa rispondere, riassumo subito all'utente" | Senza dispatch di agent il report e' opinione tua, non audit. Almeno un agent va dispatchato. | | "user-simulator e visual-critic li dispatcho insieme, vado piu veloce" | user-simulator blocca il browser. Gli altri agent che usano il browser falliscono o danno screenshot inconsistenti. Serializza. | | "Il dato e' ovvio, lo scrivo in wiki senza citare la fonte" | Wiki = conoscenza distillata da osservazioni reali. Senza citation diventa folklore. | | "Action item P/M/B troppo soggettivo, lo metto tutto M" | Priorita assenti = backlog inutilizzabile. P = blocca un flusso critico ora. B = polish. Decidi. | | "Aggiorno wiki/app-structure.md perché ho scoperto un componente nuovo, ma non c'e' raw correlato" | OK SOLO se la modifica e' un fatto verificabile leggendo il codice (es. "il file X ora si chiama Y"). Niente speculazione. | | "L'audit e' troppo ampio, chiedo all'utente su cosa focalizzarmi" | Default: dispatcha 3-4 agent in parallelo (visual + content + a11y + data-consistency se ha senso) sulla rotta. Il filtro lo applichi al report, non al dispatch. Restringere a priori = audit superficiale. | | "L'utente ha chiesto solo a11y, dispatcho solo a11y-auditor" | OK, ma includi sempre un giro veloce di `chrome-devtools-mcp:a11y-debugging` in coda — sono complementari, non duplicati. | | "Browser/MCP non disponibile, salto user-simulator e perf-watcher senza dire niente" | Sbagliato: dichiara la **modalita** (statica vs interattiva) nel frontmatter del raw (`agenti_skippati: [...]` + motivo). Cosi il prossimo audit sa cosa manca e puo coprirlo. | | "data-consistency lo faccio io a mano, non dispatcho l'agent" | Tentazione tipica: "lo so, vado veloce". Il dispatch e' valore anche quando sai la risposta — l'output dell'agent va nel raw verbatim, e' tracciabile, riusabile. Se proprio salti l'agent, scrivilo in "Steps" e motiva (es. "mini-check su KI gia nota, non serve full dispatch"). | | "Il sub-agent ha citato una KI esistente, non so se aggiornarla o ignorarla" | Aggiornare. Se un agent rileva una KI gia in `wiki/known-issues.md`, aggiungi alla voce esistente: `**Conferma**: audit del YYYY-MM-DD, vedi raw/sessions/...`. La KI sale di confidenza, non resta bootstrap a vita. | | "Aggrego i report degli agent riassumendoli nel raw, sono prolissi" | No: verbatim. Il raw e' sorgente primaria. Sintesi e priorita vanno in `output/reports/...md`. Riassumere nel raw perde dettaglio che servira al prossimo audit. | | "Dispatcho 3 agent in parallelo, se uno crasha gli altri continuano" | Accettabile, ma annotalo: nel raw header dichiara se uno dei dispatch e' fallito o e' stato re-dispatchato. Nessun silent skip. | | "`durata_min` del frontmatter lo stimo, tanto e' approssimativo" | Stima onesta accettabile, ma annota `~18 min stimati` invece di un numero secco. Pattern di scappatoia: i timing diventano spazzatura se nessuno li misura. | | "Trovo un termine nuovo di dominio, lo aggiungo direttamente a `wiki/glossary.md`" | No: prima va in `output/action-items.md` come voce `B` (es. "formalizzare termine X in glossary"), poi in audit successivo viene promosso. Il glossary non si aggiorna senza una sessione raw che lo motiva. | ## Red flags — STOP e correggi Se ti sorprendi a pensare una di queste cose, fermati: - "Scrivo direttamente in output/, il raw lo faccio dopo se serve" - "Aggiorno known-issues con un'intuizione che mi è venuta" - "Salto wiki/ perché lo conosco gia a memoria" - "Dispatcho un solo agent perché tanto e' una verifica veloce" - "Aggrego i report degli agent in un mio sommario invece di metterli verbatim in raw" - "Non riempio l'header YAML perché tanto si capisce dal nome file" Ognuna di queste rompe la tracciabilita o l'affidabilita della knowledge base. ## Limiti La skill NON: - Implementa fix nel codice dell'app. Produce action items che vengono passati a un task separato (vedi `output/action-items.md`). - Tocca il database (no migration, no UPDATE/INSERT/DELETE). - Fa decisioni di prodotto: non decide se una feature serve, valuta solo la qualità di esecuzione di feature già esistenti. - Avvia il dev server: assume `npm run dev` già attivo su `localhost:3000` (verifica con probe HTTP). - Modifica file fuori da `.claude/skills/edilcrm-ui-audit/` durante il proprio funzionamento.