HANDOFF-NNN.md — Template Completo

---
handoff: HANDOFF-[NNN]
project_id: [id canonico del progetto, es. spec-as-source]
date: "[YYYY-MM-DDTHH:MM:SS+HH:MM]"   # ISO con fuso, obbligatorio
continues: HANDOFF-[M]                # un handoff precedente esistente in questa cartella (anche saltando numeri), null per il primo
agent_session: [id agent-registry della sessione, o null]
parent_session: null                  # id agent-registry del parent SOLO se scritto da un subagente
operator:
  person: [persona, o null]
  provider: [claude | codex | ...]
  models: [modello-1, modello-2]
client: null                          # null = nessun cliente
work_context: [sviluppo]              # lista aperta, [] se nessuno
track: null                           # il Filone, se esiste
plan_entry: E[NN]                     # dal piano corrente, null senza openspec/PLAN.md
change: [nome del change attivo, o null]
deadline: null
---
# HANDOFF-[NNN] — [Brand/Progetto]
> Data: [YYYY-MM-DD HH:MM] | Sessione: #[N] | Continua da: HANDOFF-[N-1].md (o —)
> Progetto: [nome] | Operatore: [persona + modello AI es. "Giuseppe + Claude Sonnet 4.6"]
> Cliente: [se applicabile] | Deadline: [se applicabile]

---

## 🎯 Goal
[Se il progetto ha `openspec/PLAN.md`: riporta VERBATIM la riga `goal:` del piano e cita il file
come sorgente — es. "(fonte: openspec/PLAN.md)". Non riscriverlo con parole tue: due obiettivi
formulati in modo indipendente divergono, e la divergenza non si vede.
Altrimenti: obiettivo finale, 2-4 righe. Cosa si sta costruendo/creando, per chi, con quale
deliverable atteso. Questa sezione cambia raramente — solo se lo scope del progetto cambia davvero.]

## 📍 Posizione nel piano
[SOLO se il progetto ha `openspec/PLAN.md`. Se non ce l'ha, ometti l'intera sezione.
Si compila LEGGENDO il file, non a memoria: apri `openspec/PLAN.md` e riporta gli stati reali.

- **Voce corrente**: E<NN> — <titolo> (stato: <draft|approved|in-progress|done|dropped>)
- **Cosa stiamo facendo per il goal**: 1-2 righe — in che modo questa voce avvicina il `done-when` del piano
- **Resta da fare**: E<NN> (stato), E<NN> (stato) — solo le voci non ancora `done` né `dropped`
- **Piano**: `openspec/PLAN.md` — gate: `bash scripts/check-plan-gate.sh`

Se una voce legata a un change già sotto `openspec/changes/archive/` non è `done`,
segnalalo qui: è la stessa staleness che riporta il gate.]

## 🔄 Stato volatile
[Sezione OBBLIGATORIA. Qui NON si scrivono valori: si scrivono **i comandi che li
producono**. Conteggi, stati, numeri di commit, task aperti, esiti dei test e del gate
invecchiano fra il momento in cui scrivi e il momento in cui qualcuno legge — spesso
prima: "16 commit locali" era già sbagliato quando è stato scritto, perché il commit
di questo handoff non esisteva ancora. Chi legge deve **rigenerarli, non ereditarli**.

Regola che generalizza il blocco qui sotto: **ogni conteggio citato altrove in questo
documento ha qui il comando che lo rigenera.** Se un numero non ha il suo comando,
o il comando manca o il numero non andava scritto.

~~~bash
git log --oneline origin/main..HEAD | wc -l        # commit non pushati
bash scripts/verify.sh | tail -2                   # test verdi/rossi
bash scripts/check-plan-gate.sh                    # stato del gate
grep -c '^- \[ \]' openspec/changes/*/tasks.md     # task aperti per change
grep -E '^### E[0-9]+|^- \*\*State\*\*:' openspec/PLAN.md | paste - -   # stati delle voci
~~~

Adatta i comandi al progetto: questo blocco è un esempio funzionante, non una lista fissa.
Un comando che in questo progetto non esiste si toglie, non si lascia per inerzia.

Eccezione, unica: se un valore non è rigenerabile da nessun comando, scrivilo datato —
`3 render approvati dal cliente (al 2026-08-04 17:16 — riverificare)`. È un ripiego,
non la forma normale.]

## ✅ Current Progress

### Completato ✓
- [x] [Task specifico con riferimento a file/asset — es. "Homepage hero generata, salvata in /assets/hero-v3.png"]
- [x] [Task specifico]

### In corso / Sospeso
- [ ] [Task — a che punto è, cosa manca]
- [ ] [Task non iniziato]

## 💡 What Worked
[Approcci, prompt, comandi, decisioni con esito positivo.
Riporta i dettagli tecnici ESATTI — il prossimo operatore deve poterli riusare.]

<!-- Graph export: when present, prefix stable reusable entries with `Decision:` or `Fact:` in this existing section or Current Progress. Omit the label when there is no real entry. -->

- **[Tecnica/Approccio]**: [descrizione] → [risultato] ([perché ha funzionato])
- Esempio: **Prompt NanoBanana hero ESAC**: "single red LED strip, deep ocean black bg, cinematic 4K, product hero shot, no text" → qualità eccellente al primo tentativo (lighting semplice = più controllo in post)

## ❌ What Didn't Work
[Errori, vicoli ciechi, approcci falliti con parametri esatti.
Ogni voce qui è tempo risparmiato al prossimo operatore. MAI lasciare vuota per ottimismo.]

- **[Approccio fallito]**: [cosa è andato storto] → [cosa NON rifare]
- Esempio: **Seedance speed 1.0**: movimento troppo agitato, effetto non premium → usare max 0.6 per contenuti luxury

Se nulla è fallito: "Nessun vicolo cieco rilevante in questa sessione."

<!-- Graph export: every meaningful bullet or paragraph in this existing section becomes a `failure` record; the no-failure sentence above, empty entries and fenced examples do not. -->

## 🚀 Next Steps
[Lista numerata, ordinata per priorità. Item #1 eseguibile subito senza domande.
Se il progetto ha `openspec/PLAN.md`: ogni voce cita l'id della entry che fa avanzare
(es. "[E03]"), oppure dichiara esplicitamente "fuori piano". Un next step che non sa a
quale entry appartiene è il sintomo che il piano va aggiornato, non che la citazione va omessa.]

1. [E<NN>] [Azione concreta — tool, file input, output atteso]
2. [E<NN>] [Azione concreta]
3. [fuori piano] [Azione concreta]

## 📎 Context Importante (opzionale)
[Solo se serve: vincoli cliente, decisioni architetturali con motivazione,
convenzioni di naming, link a file di supporto. Non duplicare sezioni sopra.
Qui va anche il contesto operativo che vive fuori dal repo — un progetto di prova,
una cartella temporanea, un file di scratch: se serve a un Next Step e non è
versionato, o lo scrivi qui con il comando per ricrearlo, o sparisce con la sessione.]
- Credenziali: → vedi .env (mai nel testo)
- Riferimenti: `.handoff/PROMPTS.md`, `.handoff/CLIENTS.md`