# Template di handoff (passaggio di consegne)

Materiale del corso rug.gal, percorso builder.

Un handoff è il pacchetto di informazioni che passa da chi ha fatto un
pezzo di lavoro a chi fa il pezzo successivo. Vale tra due agenti di una
pipeline, tra un agente e la persona che revisiona, e tra te e un collega.
La maggior parte dei fallimenti nelle catene di agenti nasce qui: il
secondo agente riceve un riassunto vago del lavoro del primo e riparte
da assunzioni sbagliate. Il rimedio ha la forma di un documento, questo.

La regola che regge tutto: **scrivi per qualcuno che non ha visto niente**
di quello che è successo prima. Niente "come detto sopra", niente "il
solito file". Chi riceve ha solo questo documento.

---

## Il template

Copia da qui in giù, riempi ogni campo. Se un campo ti sembra inutile per
il tuo caso, scrivilo lo stesso con "niente da segnalare": chi riceve deve
sapere che ci hai pensato, non sospettare che l'hai dimenticato.

```
# HANDOFF: [nome del compito]
Da: [chi consegna: agente o persona]
A: [chi riceve]
Data: [quando]

## Obiettivo del lavoro complessivo
[Una o due frasi: a cosa serve tutta la catena, non solo il tuo pezzo.
Chi riceve prende decisioni migliori se sa dove si sta andando.]

## Cosa è stato fatto
[Elenco puntato dei passi completati, con l'esito di ciascuno.]

## Artefatti prodotti
[Ogni file o risultato, con il percorso esatto o il link.
Esempio: bozza in lavoro/listino-v2.md, dati puliti in lavoro/fatture-pulite.csv]

## Decisioni prese, e perché
[Ogni scelta non ovvia con la motivazione in una riga.
Esempio: "escluse le fatture senza importo (2) invece di stimarle:
meglio un totale parziale certo che uno completo inventato".]

## Cosa NON è stato fatto (e non va fatto)
[I confini. Cosa resta fuori di proposito, cosa non toccare.
Esempio: "i prezzi dei clienti storici NON vanno aggiornati:
decisione rimandata alla prossima riunione".]

## Il tuo compito
[Cosa deve fare chi riceve, nel modo più concreto possibile.]

## Fatto vuol dire
[Da 2 a 4 criteri verificabili. Chi riceve deve poter controllare da solo
se ha finito. Esempio: "ogni prezzo nel testo coincide con il listino;
il testo sta sotto le 300 parole; nessuna promessa sui tempi di
intervento oltre quelle del contratto".]

## Questioni aperte
[Dubbi, ambiguità, cose strane notate lavorando. Se chi riceve trova
un problema qui non segnalato, l'handoff era incompleto.]
```

---

## Esempio compilato

Contesto: una pipeline in due passi. Il primo agente ha analizzato le
fatture del trimestre (i dati di esempio del corso), il secondo deve
scrivere il commento per la riunione mensile.

```
# HANDOFF: commento ai dati del trimestre
Da: agente-analisi
A: agente-redazione
Data: 2026-07-08

## Obiettivo del lavoro complessivo
Preparare la pagina di commento ai ricavi del secondo trimestre per la
riunione di lunedì. Pubblico: i quattro soci, non tecnici.

## Cosa è stato fatto
- Letto fatture.csv (61 righe, aprile-giugno 2026)
- Trovate e gestite 4 anomalie (dettagli sotto)
- Calcolati i totali per mese e per servizio

## Artefatti prodotti
- Dati puliti: lavoro/fatture-pulite.csv
- Totali: lavoro/totali.md (mese: apr 5.870, mag 9.580, giu 10.900)

## Decisioni prese, e perché
- Fattura duplicata F-115 contata una volta: due righe identiche,
  stesso numero, chiaramente un doppio inserimento
- F-148 corretta da 18.300 a 1.830: dieci volte la fascia del servizio,
  zero di troppo evidente
- F-131 senza importo ESCLUSA dai totali, non stimata
- F-152 datata 2025 contata in giugno 2026: refuso sull'anno,
  la numerazione la colloca in giugno

## Cosa NON è stato fatto (e non va fatto)
- Nessun confronto con il trimestre precedente: i dati non ci sono
  nel file, non inventarli
- La F-131 non va menzionata come ricavo: è un dato mancante

## Il tuo compito
Scrivere il commento (200-300 parole) per la riunione: andamento dei
tre mesi, i due servizi che pesano di più, le 4 anomalie in una nota
finale con la F-131 come "da chiarire con l'amministrazione".

## Fatto vuol dire
- Ogni numero nel testo coincide con lavoro/totali.md
- Le anomalie sono nella nota, non nel corpo
- Nessuna previsione sul prossimo trimestre

## Questioni aperte
- Non so se la correzione della F-148 (18.300 -> 1.830) va confermata
  con chi ha emesso la fattura prima della riunione: segnalalo nel testo
  come verifica in corso.
```

---

## Come usarlo con gli agenti

Nel prompt dell'agente che consegna, chiedi l'handoff come formato di
output: "Chiudi il lavoro producendo un handoff secondo questo template"
(e incolli il template). Nel prompt dell'agente che riceve, l'handoff È
il contesto di partenza, insieme agli artefatti che elenca.

Il test per sapere se un handoff è buono: chi riceve riesce a fare il suo
pezzo **senza fare domande a chi ha consegnato**. Ogni domanda che torna
indietro segnala un campo compilato male. Contare le domande di ritorno
è il modo più semplice di misurare la qualità dei tuoi handoff.