# Ticket Implementation Checklist

Pattern operativo per implementazione guidata da spec ticket con verifica doc-sync obbligatoria e gate finale di build/typecheck.

## Osservazione Empirica

Validato in ~18 sessioni indipendenti (portale claim B2C, stack React/TS), sempre concluse con successo, workflow stabile.

## Workflow

### 1) Acquisizione Spec Ticket

L'utente incolla o riferisce la spec del ticket direttamente in chat, non necessariamente già letta da Mantis. La spec può includere:

* SAL (Specifica Alto Livello)
* feedback tester
* esempi request/response API
* screenshot o mockup
* vincoli tecnici o di performance

**Azione**: Fai convergere la spec in un documento interno coerente prima di implementare; se ambigua, chiedi chiarimento.

### 2) Pianificazione Preliminare (Task Ampi)

Se il task è ampio o copre multiple layer, pianifica la scomposizione con sub-agent a basso costo:

* identifica layer interessati (mapper/API layer, UI, DB, cache, ecc.)
* suddividi in milestone testabili
* indica dipendenze tra fasi
* stima scope e rischi noti

Conserva il piano nel ticket Mantis come nota operativa, riferendoti ad esso nei commit successivi.

### 3) Implementazione nel Layer Corretto

Implementa la feature seguendo l'architettura del progetto:

* mapper/API layer per business logic
* UI layer per presentazione
* database/schema per persistenza
* integrazione con eventuali servizi esterni

Evita implementazioni monolitiche; separa concerns usando le convenzioni del progetto (service layer, controller, ecc.).

### 4) **Aggiornamento Sistematico della Documentazione (Obbligatorio)**

Dopo ogni implementazione logicamente completa (non solo "finita di scrivere il codice"), aggiorna **SIMULTANEAMENTE** la documentazione di progetto associata.

La documentazione non è opzionale; fa parte della definizione di "fatto" (Definition of Done).

Documenti tipici da aggiornare:

* `_documentation/api/*.md` — endpoint nuovo, firma richiesta/risposta, payload, errori
* `_documentation/gui/*.md` — flusso utente, interazioni, stati, transizioni
* `_documentation/database/*.md` o SCHEMA— migrazioni applicate, strutture aggiunte
* `_documentation/architecture/*.md` — pattern usati, decisioni tecniche rilevanti
* README.md — se aggiunto setup o dipendenze nuove

Se il progetto non ha cartella `_documentation`, crea la struttura seguendo la convenzione del repo (ad es. `docs/`, `doc/`, ecc.).

Includi:

* **Cosa**: titolo/breve descrizione della feature
* **Quando**: data implementazione, versione/build
* **Come**: procedura d'uso, configurazione, integrazione con altre feature
* **Perché**: motivazione tecnica se non ovvia (ad es. scelta di libreria, workaround)
* **Test**: comandi per testare manualmente la feature
* **Limitazioni**: edge case, vincoli tecnici noti

### 5) **Gate Finale Obbligatorio: Typecheck + Build Verde**

Prima di dichiarare il task concluso, esegui il gate finale:

```
typecheck + build (o equivalente per lo stack del progetto)
```

Stack tipici:

* **React/TS**: `tsc --noEmit && npm run build`
* **Node.js**: `npm run lint && npm run build` (o `yarn` equivalente)
* **PHP/Yii**: `php -l` su file toccati + `composer validate`
* **Python**: `mypy` + `pylint` o `flake8`
* **.NET**: `dotnet build` in Release mode
* **Java**: `mvn clean verify` o `gradle build`

**Non proseguire finché il gate non è verde**. Se il gate fallisce:

1. correggi il codice o la configurazione
2. esegui nuovamente il gate
3. ripeti fino a verde

Documen­ta nel ticket l'esito del gate (output sintetico ma verificabile).

### 6) Nota Mantis di Chiusura

Dopo gate verde, lascia una nota tecnica nel ticket Mantis che referenzia:

* commit(s) implementate (hash o range)
* file toccati (lista sintetica)
* documentazione aggiornata (percorsi dei file)
* test eseguiti (comandi o risultati)
* rischi residui o limitazioni segnalate in docs

Esempio:

```
Implementazione completata.

Commit: abc1234..def5678
File toccati: src/mapper/ClaimMapper.ts, src/api/claims.controller.ts, _documentation/api/claims.md
Documentazione: _documentation/api/claims.md aggiornata con nuovi endpoint, payload e errori
Test: npm run lint && npm run build (GREEN)
Rischi: None
```

## Checklist di Controllo (Pre-Conclusione)

* [ ] Spec acquisita e ambiguità risolte
* [ ] Implementazione completata nel layer corretto
* [ ] Documentazione di progetto aggiornata (API, UI, architettura)
* [ ] Typecheck/lint verde
* [ ] Build verde (o equivalente per lo stack)
* [ ] Test manuali eseguiti (o smoke test automatizzati)
* [ ] Nota Mantis compilata con link commit e documentazione
* [ ] Nessun file di debug o temporaneo committato

## Note Operative

* La documentazione deve rimanere in sync col codice: se correggi un bug post-implementazione, aggiorna anche la doc se la correzione cambia il comportamento esposto.
* Se il progetto ha CI/CD automatizzato, il gate finale sarà validato dalla pipeline; comunque esegui i check locali prima di pushare per risparmiare cicli di feedback.
* Per task molto complessi, suddividi la documentazione per milestone, non aspettare la fine.