# Legacy Pre-Migration Audit

Playbook per l'audit sistematico di un sistema legacy prima di una riscrittura o migrazione verso uno stack nuovo.

## Pattern Osservato

Quando l'obiettivo è comprendere a fondo lo stato attuale di un sistema legacy (database, funzionalità, interfaccia) **prima** di una migrazione, il workflow osservato con successo in più progetti segue una struttura di coordinamento multi-dominio:

- Intake rapido del contesto legacy.
- Pianificazione del fan-out: identificazione dei domini funzionali da analizzare.
- Attivazione di sub-agent paralleli read-only, ciascuno con mandato preciso su un singolo dominio.
- Produzione di output Markdown strutturato, "agent-friendly", riutilizzabile da agenti futuri.
- Chiusura con gap-analysis su quanto rimane non documentato.
- Compilazione del corpus tecnico che diventa base per la successiva fase di riscrittura (fuori scope).

## Sequenza Operativa (5-7 Passi)

### 1. Intake Contesto e Scoping

Raccogli da utente o ticket:

- Tecnologie/framework del legacy (es. PHP/Yii, CFML, database type, client framework, età approssimativa).
- Criticità attuali (performance, maintainability, compliance, security noti).
- Obiettivo di migrazione (stack target, timeline approssimativa, constraint).
- Perimetro funzionale (è tutto il sistema o solo moduli specifici?).

Documenta in un file Markdown iniziale (es. `_documentation/audit-context.md`) con sezioni:
- Tecnologie attuali
- Criticità note
- Obiettivi della riscrittura
- Perimetro di audit

### 2. Pianificazione Domini Funzionali

Mappa i domini che necessitano analisi profonda:

- **Dominio Database**: schema, stored procedure, relazioni, query critiche, dati attuali, integrità vincolata.
- **Dominio Funzionalità X** (ad es. "gestione documenti", "workflow approvazione"): flussi, logica di business, algoritmi chiave, configurazioni.
- **Dominio Interfaccia Utente**: layout, framework, flussi di navigazione, componenti riusabili, validazione client.
- **Dominio Integrazioni** (se rilevanti): API esterne, web service, connettori, protocolli di comunicazione.
- **Dominio Configurazione / Deployment**: variabili di ambiente, asset compilation, build script, automazione.

Registra questo piano in `_documentation/audit-plan.md` come matrice dominio → scope → sub-agent assegnato.

### 3. Attivazione Sub-Agent Database

Se il sistema legacy ha un database criticamente importante:

- Invia a **`mcp-database-expert`** con mandato read-only:
  - Estrai schema completo (tabelle, vincoli, indici).
  - Documenta query critiche trovate nel codice o log.
  - Analizza dati attuali (volumi, distribuzione, integrità).
  - Confronta eventuali versioni di schema tra ambienti (dev/qa/prod).
  - Identifica anti-pattern o debiti tecnici.

- Output atteso: Markdown strutturato in `_documentation/db/` con sezioni:
  - Schema e relazioni (diagramma testuale o tabellare).
  - Query critiche annotate con contesto di uso.
  - Dati attuali e vincoli.
  - Problemi rilevati e note per il porting.

### 4. Attivazione Sub-Agent Funzionalità

Per ogni dominio funzionale prioritario:

- Se il sistema è **PHP/Yii**: invia a **`mcp-sophia-yii-developer`** per analizzare layer FRM/APP/CLI-client, RenderSettings, Cruge, export/script configurabili.
- Altrimenti: usa **`mcp-technical-analyst`** in modalità codice-first con mandato:
  - Traccia flusso di una transazione di business completamente (entry point → DB → return).
  - Documenta logica decisionale critica (if/case/switch pattern).
  - Estrai algoritmi non ovvi o proprietari.
  - Identifica configurazioni che cambiano il comportamento.
  - Raccogli dipendenze verso librerie esterne.

- Output atteso: per ogni funzionalità, un file `.md` in `_documentation/features/{nome}/` con:
  - Descrizione del flusso end-to-end.
  - Codice chiave annotato (o link a specifiche linee nei commit).
  - Configurazioni e parametri.
  - Problemi rilevati e raccomandazioni di refactor.

### 5. Validazione Interfaccia Utente

Se rilevante per il perimetro:

- Usa **`mcp-technical-analyst`** in modalità `functional-exploration` (con Playwright solo se:
  - Comportamenti dinamici o dipendenti da stato.
  - Rendering client-side complesso.
  - Errori browser-side non spiegabili dal codice).
- Alternativa (preferibile se possibile): leggi template/JSX/HTML statico + foglio di stile nel repo.

- Output atteso: file `.md` in `_documentation/ui/` con:
  - Struttura di navigazione principale.
  - Componenti riusabili rilevanti (form, grid, modal).
  - Validazione client (lato browser e possibili by-pass).
  - Accessibilità e UX noti problemi.

### 6. Compilazione e Indexing del Corpus

Quando tutti i sub-agent hanno concluso:

- Raccogli tutti i file `.md` della documentazione generata.
- Usa **`mcp-docs-navigator`** per:
  - Verificare struttura cartelle e naming coerente.
  - Aggiungere tag cross-dominio (es. `#database-dependent`, `#migration-blockerr`, `#refactor-priority`).
  - Creare un indice o tabella dei contenuti centrale in `_documentation/README.md`.
  - Opzionalmente: generare visualizzazioni di dipendenza (ASCII diagram) tra i domini.

### 7. Gap-Analysis Finale

Crea un sub-agent dedicato o self-review per:

- Quali parti del sistema rimangono non documentate?
- Quali dipendenze interdominiu sono critiche ma non ancora spiegate?
- Quali assunzioni su dati, integrazioni o configurazioni rimangono aperte?
- Quanto sforzo stimato è la riscrittura di ogni dominio, basato su documentazione?

Produci un file `.md` in `_documentation/gap-analysis.md` con:
- Lista di vuoti documentali.
- Rischi di riscrittura per ogni dominio (complessità, integrazioni esterne).
- Checklist pre-riscrittura (quali ambienti testare prima di iniziare?).
- Assunzioni chiave da confermare con il team legacy.

## Output Finale

Il corpus documentale generato non è un report monouso: è **Markdown versionato e riutilizzabile da agenti futuri**.

Convenzioni:
- Ogni file `.md` in `_documentation/` è autonomo e referenziabile.
- Link interni usano percorsi relativi o nomi chiari di sezioni.
- Codice citato è attribuito a commit specifici o linee nel repo.
- Dati sensibili sono redatti.
- Diagrammi preferibilmente testuali (Markdown table, ASCII diagram) per portabilità.

Questo corpus diventa la specifica tecnica per la successiva fase di riscrittura; ogni nuova skill o agente può leggerlo senza dover ri-analizzare il sistema legacy da capo.

## Skill di Supporto Espliciti

- **`mcp-database-expert`**: schema, dati, query, confronti ambiente.
- **`mcp-docs-navigator`**: indexing, tagging, scaffale centrale della documentazione.
- **`mcp-sophia-yii-developer`**: se il legacy è PHP/Yii, per approfondimento layer applicativo specifico.
- **`mcp-technical-analyst`** (self): coordinamento multi-dominio, gap-analysis, sintesi finale.

## Criteri di Successo

- [x] Ogni dominio ha almeno un file `.md` dedicato in `_documentation/`.
- [x] Corpus è coeso: i link interni funzionano, la struttura è coerente.
- [x] Ogni file contiene fatti verificabili e referenziati (commit, query, schema).
- [x] Inferenze sono marcate come tali; punti aperti sono espliciti.
- [x] Gap-analysis è chiara e actionable per il team di riscrittura.

## Quando NON usare questo playbook

- Se il legacy e un modulo isolato e la riscrittura e gia stata decisa (usa invece `mcp-database-expert` o lo skill specialistico di dominio).
- Se l'audit serve solo a identificare un bug singolo (usa `ticket-first` semplice).
- Se il team legacy ha già una documentazione completa e verificata (usa `document-first` per validarla, non rifare l'audit).