HandoffSkill — Bug Tracker per Test e Upgrade di Skill

Variante di handoff orientata non al passaggio di consegne tra sessioni di progetto, ma al tracciamento dei bug/malfunzionamenti emersi testando una skill o un plugin, in modo che l'upgrade successivo parta da una lista di bug concreta invece che da "qualcosa non andava, non ricordo cosa".

Vive in parallelo a .handoff/ (continuità di progetto) senza mischiarsi: .handoff/ racconta la storia del progetto, .handoffskill/ racconta i bug di una skill specifica sotto test.

Struttura della cartella .handoffskill/

.handoffskill/
└── <nome-skill-testata>/
    ├── BUG-001.md       ← prima sessione di test
    ├── BUG-NNN.md       ← sessione corrente (sempre il numero più alto)
    └── STATUS.md         ← stato aggregato bug aperti/chiusi (rigenerato ad ogni save)

Regola fondamentale: i BUG-NNN.md sono append-only — non si modificano mai le sessioni di test passate. Si aggiorna solo creando un nuovo file numerato. STATUS.md invece si rigenera ad ogni save, perché è una vista derivata (non una sessione).

Una cartella <nome-skill-testata>/ per ogni skill/plugin testato, così i bug di skill diverse non si mescolano.

Comandi riconosciuti

Workflow A — INIT (prima sessione di test su una skill)

Eseguire quando .handoffskill/<nome-skill>/ non esiste ancora.

Step 1 — Crea la struttura

mkdir -p .handoffskill/<nome-skill>

Step 2 — Chiarisci lo scope del test

Prima di iniziare, accertati di sapere (chiedi se manca):

• quale skill/plugin si testa e quale versione/upgrade target;
• se esiste già una lista di scenari da coprire o si parte da zero;
• cosa significa "fatto" per questo giro di test (es. tutti gli scenari core passano, o solo verificare un fix specifico).

Step 3 — Procedi con il Workflow B (SAVE) al termine della sessione di test

Workflow B — SAVE (registra i bug trovati in questa sessione)

Step 1 — Determina il numero progressivo

ls .handoffskill/<nome-skill>/BUG-*.md 2>/dev/null | sort | tail -1

Se non esiste nessun file → creare BUG-001.md. Se esiste l'ultimo → incrementare di 1.

Step 2 — Leggi l'ultimo BUG-NNN.md (se esiste)

Per non riaprire bug già chiusi e per capire quali scenari erano già stati coperti. I bug ancora "Open" nell'ultimo file diventano il punto di partenza del Bug Tracker del nuovo file.

Step 3 — Scrivi il nuovo BUG-NNN.md

Usare la struttura esatta in references/bug-template.md. Le sezioni obbligatorie sono:

1. 🎯 Goal — Quale skill/plugin si sta testando, per quale upgrade/rilascio. Stabile tra sessioni di test della stessa skill.
2. 🧪 Test Scenarios — Scenari coperti in questa sessione, esito pass/fail, con comando o input esatto usato.
3. 🐛 Bug Tracker — Tabella strutturata: ID, scenario, comportamento atteso, comportamento reale, severità, file:riga coinvolto, stato, fix. Mai usare descrizioni vaghe ("non va bene") — sempre atteso vs reale concreto.
4. 💡 Confirmed Behaviors — Cosa è stato verificato corretto in questa sessione (per non testarlo di nuovo per niente al prossimo giro).
5. 🚀 Next Steps — Fix prioritari da applicare, ordinati per severità. Item #1 eseguibile subito senza domande.

Regole di scrittura:

• Lingua del contenuto = lingua della conversazione.
• Ogni bug ha un ID stabile (BUG-<NNN>-<seq>, es. BUG-002-01) che non cambia se il bug viene riportato in sessioni successive — permette di citarlo nei commit di fix.
• Severità su 3 livelli: Blocker (rende la skill inusabile o produce danno), Major (comportamento sbagliato ma la skill resta usabile), Minor (cosmetico, edge case raro).
• Zero segreti nel testo.

Step 4 — Rigenera STATUS.md

Usare references/status-template.md. Aggrega tutti i bug ancora "Open" o "In Progress" da tutti i BUG-NNN.md di quella skill, ordinati per severità. È una vista, non una sessione: si riscrive sempre da zero leggendo tutti i BUG-NNN.md, non si appende.

Step 5 — Quality check

• Ogni bug nel Bug Tracker ha atteso/reale concreti, non vaghi
• Severità assegnata a ogni bug
• Next Steps ordinati per severità, item #1 eseguibile subito
• STATUS.md rigenerato e coerente con l'ultimo BUG-NNN.md

Step 6 — Notifica

✅ Salvato: .handoffskill/<nome-skill>/BUG-00N.md
✅ Aggiornato: .handoffskill/<nome-skill>/STATUS.md (X bug open, Y fixed)

Per riprendere il test in una nuova sessione:
→ "Leggi .handoffskill/<nome-skill>/STATUS.md e riprendi il test"

Workflow C — LOAD (ripresa di una sessione di test)

Step 1 — Trova l'ultimo BUG-NNN.md della skill richiesta

ls .handoffskill/<nome-skill>/BUG-*.md | sort | tail -1

Step 2 — Leggi in ordine

1. STATUS.md della skill — vista rapida di cosa è ancora aperto.
2. L'ultimo BUG-NNN.md completo — contesto degli scenari testati e perché.
3. Solo se serve dettaglio su un bug specifico più vecchio, risali al BUG-NNN.md che lo ha introdotto (citato in STATUS.md).

Step 3 — Conferma comprensione

Rispondi in 3-4 righe: quale skill, quanti bug open/fixed, qual è il prossimo fix o scenario da testare.

Step 4 — Parti dal Next Step #1

Non rifare scenari già in "Confirmed Behaviors" salvo regressione sospetta. Non richiudere un bug come "Fixed" senza aver rieseguito lo scenario che lo aveva fatto emergere.

Relazione con handoff

• handoff racconta la storia di un progetto nel tempo; handoffskill racconta i bug di una skill sotto test. Possono coesistere nello stesso progetto senza sovrapporsi.
• Quando un giro di test produce un fix applicato e mergeato, vale la pena riportarne una riga di sintesi in .handoff/HANDOFF-NNN.md → "What Worked" o "What Didn't Work" (il bug fix concettuale), mentre il dettaglio scenario-per-scenario resta in .handoffskill/.
• Se la skill testata è bundlata in un plugin, considera se i BUG-NNN.md vadano committati nel repo del plugin (utile per traccia storica) o esclusi via .gitignore se contengono dettagli troppo interni.

Note per Claude Code

• Usa bash per creare/leggere file .handoffskill/ direttamente nel filesystem del progetto.
• Questa skill è installata sia globalmente (~/.claude/skills/handoff-skill/) sia, quando bundlata in un plugin, in skills/handoff-skill/ del plugin stesso — le due copie sono indipendenti, aggiornarle separatamente.
• Se .handoffskill/<nome-skill>/ non esiste e l'utente segnala un bug, offrire di fare init prima (Workflow A), poi registrare subito il bug.