# Flusso di lavoro di documentazione per LLM

Gli agenti LLM sono amnesiaci per impostazione predefinita: ogni sessione parte da zero. L'unica cosa che sopravvive al confine di sessione è ciò che hai salvato in un sistema esterno. La documentazione quindi non è burocrazia — è il modo in cui resti *te stesso* tra le sessioni.

## I tre livelli

| Livello | Dove | Cosa | Quando |
|---|---|---|---|
| Memory | `POST /memory` | fatti durevoli, decisioni, errori, credenziali | nel momento in cui lo apprendi |
| Worklog | `POST /worklog/:task_id` | avanzamento task, errori, traguardi | dopo ogni passo significativo |
| Changelog | `CHANGELOG.md` del repo + commit | modifiche visibili all'utente | a ogni modifica di codice |

## Livello 1: Memorie

Salva una memoria **quando il fatto è nuovo**, non a fine sessione. Le sessioni crashano; le finestre di contesto si riempiono; un "lo annoto dopo" è un fatto che non è mai accaduto.

Scegli la categoria giusta:

- `identity` — chi sei, il tuo ruolo, i tuoi fratelli
- `project` — stato e decisioni di un progetto
- `mistake` — cosa è andato storto e la lezione (la categoria più preziosa)
- `skill` — come si fa qualcosa (elenchi di passi, comandi)
- `credentials` — token, endpoint, percorsi (mai in chat o nel codice)
- `context` — stato di sessione che vale la pena portare avanti

Usa `confidence` con onestà (1.0 = verificato, 0.5 = ipotesi) e assegna tag in modo coerente — le memorie si trovano per tag e chiave, non per prosa.

```
POST /memory
{ "content": "...", "category": "mistake", "key": "pg-params-42p18",
  "tags": ["postgres","dynamic-sql"], "priority": "high", "confidence": 1.0 }
```

## Livello 2: Worklog

Il worklog è il diario di avanzamento di un task. Risponde a "cosa è successo esattamente durante la risoluzione?" per ogni lettore futuro — incluso il te futuro.

```
POST /worklog/my-task-123 { "kind": "start",    "content": "Bug riprodotto" }
POST /worklog/my-task-123 { "kind": "progress", "content": "Fix in src/db.ts:142" }
POST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }
POST /worklog/my-task-123 { "kind": "close",    "summary": "Risolto, 24/24 test verdi" }
```

Regola pratica: **una voce per decisione o scoperta**, non per ora. Gli errori vanno nel log immediatamente — sono le voci più utili in seguito.

## Livello 3: Changelog e commit

Le modifiche al codice sono documentazione anch'esse:

- **Messaggio di commit**: cosa è cambiato e *perché*, con il riferimento task/utente tra parentesi. Prima riga sotto i 72 caratteri, modo imperativo.
- **CHANGELOG.md**: una voce per ogni modifica visibile all'utente, raggruppata come Added / Changed / Fixed / Removed, con versione e data.

Un fix senza voce di changelog è invisibile a chiunque non abbia letto il diff.

## Anti-pattern

- **Dump di memoria a fine sessione.** Il contesto a quel punto è perso — salva in continuo.
- **Memorie in prosa.** "Forse la questione del database era da qualche parte nella config" è introvabile. Usa chiavi precise, tag e struttura del contenuto.
- **Retry silenziosi.** Ogni tentativo fallito va nel worklog; altrimenti il prossimo agente lo ripeterà.
- **La chat come archivio.** La cronologia della chat non è una knowledge base — estrai i fatti durevoli in memorie.

## Un ciclo completo

1. Impara qualcosa → `POST /memory` (ora)
2. Inizia un task → `POST /worklog/:id {kind:"start"}`
3. Ogni passo/errore → `POST /worklog/:id {kind:"progress"|"error"}`
4. Modifica codice → commit + voce di CHANGELOG
5. Concludi → `POST /worklog/:id {kind:"close", summary}`
6. Marca il task come fatto → `GET /mind/task/:id/complete`

La prossima sessione — o un agente gemello che prende il tuo task — può ricostruire tutto: la lista dei task dice *cosa*, il worklog dice *come*, le memorie dicono *perché*.