<!--
Mini-manuale per l'uso efficace dell'estensione "Todos" (VS Code)
Posiziona questo file in `manual/` per consultazione rapida.
-->

# Guida rapida: Estensione "Todos" in Visual Studio Code

Questo mini-manuale spiega come installare, configurare e sfruttare al massimo
l'estensione "Todos" (o estensioni simili che indicizzano checkbox/annotazioni nei
file) per gestire il file `todo.md` del progetto. È pensato per essere pratico e
immediatamente applicabile.

---

## 1) Obiettivo

- Centralizzare task e micro-attività nel repository in un file leggibile (`todo.md`).
- Usare l'estensione per: filtrare, navigare, assegnare e trasformare rapidamente i task.

## 2) Installazione e attivazione

1. Apri VS Code.
2. Marketplace → cerca `Todos` (o `todo tree`, `todo+` ecc.).
3. Installa l'estensione che preferisci (es. "Todos" by Alexandru Duma o simile).
4. Dopo l'installazione, apri la Command Palette (`Ctrl+Shift+P`) e cerca comandi come:
   - `Todos: Show` o `Todos: Toggle` per visualizzare la vista globale dei todo.
5. (Opzionale) Aggiungi impostazioni di workspace per includere/escludere percorsi.

Esempio `.vscode/settings.json` (opzionale):

```json
{
  "todos.include": ["**/todo.md", "**/*.md"],
  "todos.exclude": ["**/node_modules/**", "**/.venv/**"]
}
```

---

## 3) Convenzioni consigliate per `todo.md`

Usare una convenzione coerente rende la ricerca e il filtering più potenti.

- Ogni task su una riga, checkbox Markdown:
  - `- [ ]` per aperto, `- [x]` per completato.
- Aggiungere tag e metadati inline:
  - `#feature`, `#bug`, `#test`, `#docs` — permette filtri tematici.
  - `@owner` — persona responsabile.
  - `prio:high|medium|low` — priorità.
  - `est:30m|1h|2h` — stima.
  - `target_id:<id>` — utile per tracciare target nel CSV o riferimenti interni.

Esempio di riga completa:

```
- [ ] Implementare MathLab CSV export #feature @marco prio:high est:3h target_id:all
```

---

## 4) Struttura consigliata del file

Usa sezioni per organizzare lo stato del lavoro:

- `# TODOs` (header principale con note sulle convenzioni)
- `## Inbox` — cattura rapida di idee e richieste
- `## Backlog` — attività pianificate ma non prioritarie
- `## Sprint` — attività previste nel prossimo ciclo
- `## Doing` — attività in corso (opzionale)
- `## Done` — attività completate

Esempio di template:

```md
# TODOs - convenzioni: #tag @owner prio:<high|med|low> est:<time>

## Inbox
- [ ] Aggiungere MathLab export dialog #feature @marco prio:high est:2h
- [ ] Creare unit tests per add_mathlab_state #test @marco prio:medium est:1h

## Backlog
- [ ] Refactor logger CSV #chore @team prio:low est:4h

## Sprint W01
- [ ] Fix heading calculation #bug @luca prio:high est:30m

## Done
- [x] Aggiornare SimulationEngine per chiamare archive.add_mathlab_state #feature @marco
```

---

## 5) Workflow raccomandato

1. **Capture** — aggiungi immediatamente la riga in `todo.md` quando nasce un task.
2. **Triage (giornaliero)** — assegna tag/owner/estimate alle voci nuove (#bug/prio).
3. **Plan (settimanale)** — sposta le voci in `## Sprint` se da fare nella settimana.
4. **Work** — mentre lavori, aggiorna la riga (`- [ ]` → `- [x]`) e nel commit/PR metti riferimento alla riga.
5. **Archive** — sposta voci completate nella sezione `## Done` o elimina dopo verifica.

Consiglio: nel PR/commit message includi una riga che faccia riferimento al task, es.: `Fixes TODO: Implementare MathLab CSV export`.

---

## 6) Come usare l'estensione (operazioni tipiche)

- Aprire la vista Todos: Command Palette → `Todos: Show`.
- Filtrare per tag: usa la ricerca integrata dell'estensione o il filtro `#bug`.
- Creare task dalla UI: molte estensioni permettono di creare righe direttamente dalla vista (prova `Todos: Create Task`).
- Cliccare per navigare alla riga nel file quando la vista elenca i task.

---

## 7) Best practices e consigli avanzati

- Mantieni le voci piccole e atomiche.
- Non usare `todo.md` come backlog di alto livello (usa invece issue/board), ma per micro-task.
- Standardizza i tag del team e scrivili in testa al file in `# conventions`.
- Se lavori in team, aggiungi una sezione `Contributors` con le convenzioni condivise.
- Evita duplicati: prima di aggiungere, cerca parole chiave nel file.

Automazioni possibili:
- Script che convertono `todo.md` in issue GitHub (CI/CD)
- Hook che rimuovono voci `- [ ]` obsolete quando la PR viene unita (con commento di audit)

---

## 8) Esempi pratici (rapidi)

- Aggiungere un bug:
  - `- [ ] Correggere crash all'avvio #bug @luca prio:high est:1h`
- Assegnare un task in triage:
  - trova `#bug` nella vista `Todos`, apri e aggiungi `@owner prio:high est:30m`.
- Segnare completato:
  - modifica la riga in `- [x]` o usa la UI dell'estensione.

---

## 9) Esercizi rapidi (per padroneggiare)

1. Apri `todo.md` e aggiungi 3 task di esempio con tag/owner/estimate.
2. Filtra la vista dell'estensione per `@tuo_nome` e verifica che compaiano solo i task assegnati a te.
3. Crea una PR che risolve un task e, nel messaggio, inserisci `Closes TODO: <descrizione>`.

---

## 10) Risorse utili e next steps

- Se vuoi, posso:
  - popolare `todo.md` con il template che preferisci;
  - aggiungere uno script che esporta `todo.md` in CSV o in issue GitHub;
  - aggiungere esempi di automazione CI.

Salva questa guida come riferimento in `manual/todos_extension_manual.md`.

Buon lavoro — se vuoi che inserisca il template direttamente in `todo.md`, lo faccio ora.