Update session-handoff skill description and procedure for clarity and completeness

skills/session-handoff/SKILL.md

@@ -1,28 +1,32 @@
 ---
 name: "session-handoff"
-description: "Scrivere un HANDOFF.md di riassunto a fine sessione per passare il lavoro a un altro agente o a una nuova sessione."
+description: "Scrivere un HANDOFF.md di riassunto su richiesta dell'utente (on-demand) per passare il lavoro a un altro agente o a una nuova sessione, a qualunque punto del lavoro. Chiede sempre all'utente quali punti salienti esportare prima di scrivere il file."
 ---
 
 ## When to Use
-A fine sessione o task, quando il lavoro continuerà con un altro agente (nuova sessione pi, subagent, agente esterno) o quando l'utente chiede un riassunto di quanto fatto per ripartire altrove.
+Quando l'utente lo richiede esplicitamente (es. "prepara un handoff", "scrivi l'handoff") o dichiara che il lavoro continuerà con un altro agente (nuova sessione pi, subagent, agente esterno). Non è vincolato a fine sessione o task: si usa a qualunque punto del lavoro, anche a metà di un task in corso.
 
 ## Procedure
-1. Confermare lo scopo dell'handoff: cosa dovrà fare il prossimo agente e quale stato serve per ripartire.
-2. Scrivere HANDOFF.md nella root del progetto con struttura fissa: Obiettivo, Stato (fatto/in corso), Decisioni prese, File modificati/creati, Verifica, Problemi aperti, Prossimi passi, Comandi utili.
-3. Per ogni file citato riportare solo path + motivo della modifica, non il contenuto. Usare puntatori (path, comandi, commit) invece del contenuto grezzo.
-4. Nella sezione Verifica riportare i comandi già eseguiti con esito (test/build/lint) ed eventuali errori noti o rischi aperti.
-5. Passaggio all'altro agente: nuova sessione pi → pi -p "@HANDOFF.md Continua da qui: ..."; subagent → passare il path del file come istruzione; agente esterno → copia-incolla del markdown (il file è auto-contenuto).
-6. Se la sessione continua oltre il punto di handoff, aggiornare il file invece di crearne un secondo.
-7. Per renderlo ripetibile, riusare questo stesso template in ogni handoff successivo.
+1. Confermare lo scopo dell'handoff: cosa dovrà fare il prossimo agente e quale stato serve per ripartire. Se invocato a metà lavoro, chiarire con l'utente lo scope: l'handoff copre il lavoro svolto finora, non necessariamente un task chiuso.
+2. Elencare all'utente i punti salienti candidati emersi dalla sessione (lavori completati, decisioni, file toccati, problemi aperti, prossimi passi) e chiedere quali esportare nell'handoff. Procedere alla scrittura solo dopo la conferma dell'utente.
+3. Scrivere HANDOFF.md nella root del progetto con struttura fissa: Obiettivo, Stato (fatto/in corso), Decisioni prese, File modificati/creati, Verifica, Problemi aperti, Prossimi passi, Comandi utili. Includere solo i punti confermati dall'utente; se una sezione non ha contenuti selezionati, scriverla vuota con nota "non applicabile".
+4. Per ogni file citato riportare solo path + motivo della modifica, non il contenuto. Usare puntatori (path, comandi, commit) invece del contenuto grezzo.
+5. Nella sezione Verifica riportare i comandi già eseguiti con esito (test/build/lint) ed eventuali errori noti o rischi aperti. Se il lavoro è in corso, segnare esplicitamente cosa non è ancora stato verificato.
+6. Passaggio all'altro agente: nuova sessione pi → pi -p "@HANDOFF.md Continua da qui: ..."; subagent → passare il path del file come istruzione; agente esterno → copia-incolla del markdown (il file è auto-contenuto).
+7. Se la sessione continua oltre il punto di handoff, aggiornare il file invece di crearne un secondo.
+8. Per renderlo ripetibile, riusare questo stesso template in ogni handoff successivo.
 
 ## Pitfalls
+- Non scrivere l'handoff senza aver prima chiesto e ottenuto dall'utente la lista dei punti salienti da esportare.
 - Non esportare l'intera trascrizione: il valore è il riassunto, non il log.
 - Non omettere stato di verifica e rischi aperti: sono ciò che serve davvero al prossimo agente.
+- Se l'handoff è generato a lavoro in corso, non presentare lo stato come completo: marcare chiaramente ciò che è a metà o non verificato.
 - Evitare summary vaghi tipo 'Fatto' o 'Ok': indicare esiti concreti e comandi eseguiti.
 - Non lasciare il file senza sezione Prossimi passi: deve essere eseguibile da un agente che parte da zero.
 - Attenzione al formato del file HANDOFF.md se l'agente di destinazione è esterno (es. niente sintassi specifica di pi).
 
 ## Verification
-1. HANDOFF.md esiste nella root del progetto e contiene tutte le sezioni previste.
-2. Un nuovo agente riesce a ripartire leggendo solo il file: i prossimi passi sono azionabili e i comandi citati esistono.
-3. I path dei file citati nell'handoff sono reali (verificare con ls/read).
+1. Prima della scrittura è stata chiesta all'utente la selezione dei punti salienti e il file riflette la selezione ricevuta.
+2. HANDOFF.md esiste nella root del progetto e contiene tutte le sezioni previste.
+3. Un nuovo agente riesce a ripartire leggendo solo il file: i prossimi passi sono azionabili e i comandi citati esistono.
+4. I path dei file citati nell'handoff sono reali (verificare con ls/read).