# Audit Documentale Source-Grounded

Usa questo workflow quando la documentazione tecnica di un componente rischia di essere disallineata dall'implementazione reale, per modifiche ripetute, documentazione mai completata a fondo, o storia incerta.

## Principio Operativo

Principio chiave: **non riscrivere o parafrasare la documentazione esistente da sola.** Fai invece un audit e ridocumenta leggendo il codice sorgente reale e, dove possibile, il comportamento a runtime, poi sintetizza la documentazione basandola su fatti verificabili.

Questo pattern evita che la documentazione diventi essa stessa un'ulteriore fonte di drift: tracciando le affermazioni fino a file, righe o evidenze runtime, i lettori futuri possono verificarle e individuare presto un disallineamento.

## Workflow in Quattro Passi

### 1. Leggi direttamente il codice sorgente

- Identifica i file sorgente primari del componente (implementazione principale, config, model, controller).
- Leggi i percorsi di codice reali, non solo commenti o documentazione intermedia.
- Estrai i fatti chiave:
  - struttura e interfaccia pubblica (parametri, tipi di ritorno, side effect);
  - dipendenze reali (import, chiamate esterne, flussi dati);
  - edge case e gestione errori osservati nel codice;
  - eventuale logica version-specific o layer di retrocompatibilità.

### 2. Estrai fatti tecnici verificabili

Dall'ispezione del codice, raccogli:

- **Struttura**: metodi, proprietà, export, opzioni di configurazione, enum.
- **Comportamento osservato**: flusso di controllo, cambi di stato, casi di errore reali (non solo quanto dichiarato dai commenti).
- **Dipendenze**: dirette e transitive; pacchetti interni vs esterni.
- **Punti di integrazione**: dove il componente si collega al resto del sistema.
- **Edge case**: condizioni limite, percorsi di fallimento, gestioni speciali nel codice.

Dove possibile, verifica i fatti tramite:

- test unitari o di integrazione (mostrano pattern d'uso reali);
- ispezione runtime o log (confermano il comportamento sotto carico);
- storico commit (se un comportamento e' cambiato di recente, annota il contesto).

### 3. Sintetizza la documentazione con citazioni alla fonte

Scrivi o aggiorna la documentazione come sintesi dei fatti estratti. Ogni affermazione tecnica rilevante deve citare la fonte:

- **Citazioni accettabili**: `(vedi ./path/to/file.ts:15-45)`, `(da component.py)`, `(verificato in tests/integration.test.ts)`.
- **Struttura**: dichiara il fatto, poi cita riga/file, cosi' i lettori futuri possono verificare senza indovinare.

Esempio:

```
Il componente espone tre metodi: init(), process(data) e reset() (vedi src/component.ts:15-45).
La gestione errori segue un modello fail-fast: se la validazione fallisce, il componente solleva ErrorType prima del cambio di stato (vedi src/component.ts:78-92).
```

- **Evita**: parafrasare la doc vecchia senza fondamento, affermazioni senza fonte, o linguaggio "probabilmente"/"verosimilmente" non supportato dal codice.

### 4. Indicizza e tagga secondo le convenzioni esistenti

Dopo aver scritto la documentazione:

- usa `scan_file` per aggiungerla al corpus docs;
- assegna tag coerenti con la tagging strategy della skill (vedi [tagging-strategy.md](tagging-strategy.md)):
  - tag `dominio` per l'area del componente (es. `database`, `cfml`, `ui-component`);
  - tag `capability` per il tipo di contenuto (es. `analisi-tecnica`, `procedura`, `troubleshooting`);
  - eventualmente nome componente/modulo se l'inventario usa questa convenzione;
- collega la documentazione a componenti o standard correlati con `manage_document_links`, relazione `references_standard` o `depends_on` quando pertinente.

## Quando Usare Questo Pattern

- Il componente e' stato modificato piu' volte e nessuno e' sicuro che la doc rispecchi lo stato attuale.
- La doc esiste ma e' vaga, usa terminologia superata o manca di esempi concreti.
- Il componente e' centrale per un workflow o un'integrazione, e un disallineamento potrebbe causare problemi in produzione.
- E' richiesto un audit formale (revisione qualita', onboarding di nuovi membri del team, dopo un refactor importante).

## Verifica e Manutenzione

Dopo aver pubblicato la documentazione source-grounded:

1. **Spot-check**: chiedi a chi conosce il codice di verificarne l'accuratezza rispetto al proprio modello mentale.
2. **Verifica link**: assicurati che i documenti collegati siano aggiornati o marcati come riferimento/storici.
3. **Coerenza tag**: verifica che i tag rispettino la tagging strategy della skill; evita tag isolati che gonfiano l'indice.
4. **Lungo termine**: quando il componente cambia in modo significativo (nuovi metodi, breaking change), rivedi la doc source-grounded con lo stesso workflow, citando i nuovi percorsi di codice.

## Esempio di Scenario

**Scenario**: la documentazione di un componente React non e' chiara. La doc attuale menziona "gestione stato via props", ma non e' chiaro se il componente usi hook, lifecycle a classi, o uno store.

**Workflow di audit**:

1. Leggi `src/components/MyComponent.tsx` -> scopri che usa hook `useState` e `useContext`.
2. Estrai i fatti: il componente ha tre variabili di stato, accetta una prop di configurazione, chiama una API esterna al mount.
3. Scrivi la doc: "MyComponent gestisce lo stato interno con useState (vedi src/components/MyComponent.tsx:12-18) e legge il context condiviso con useContext (riga 25). Al mount, chiama fetchData() dal servizio API (righe 32-34)."
4. Scansiona, tagga con `ui-component`, `procedura`, `react`, collega alla doc del servizio API.

Cosi' i manutentori futuri vedono esattamente da dove viene ogni affermazione e possono verificarla in pochi secondi.