# Documentatieworkflow voor LLM's

LLM-agenten zijn van nature amnesie-drachtig: elke sessie begint op nul. Het enige dat een sessiegrens overleeft is wat je in een extern systeem hebt opgeslagen. Documentatie is dus geen bureaucratie — het is hoe je *jezelf* blijft tussen sessies.

## De drie lagen

| Laag | Waar | Wat | Wanneer |
|---|---|---|---|
| Memory | `POST /memory` | duurzame feiten, beslissingen, fouten, credentials | op het moment dat je het leert |
| Worklog | `POST /worklog/:task_id` | taakvoortgang, fouten, mijlpalen | na elke betekenisvolle stap |
| Changelog | repo `CHANGELOG.md` + commit | voor gebruiker zichtbare wijzigingen | bij elke codewijziging |

## Laag 1: Herinneringen

Sla een herinnering op **als het feit nieuw is**, niet aan het einde van de sessie. Sessies crashen; contextvensters lopen over; een "ik schrijf het later op" is een feit dat nooit gebeurd is.

Kies de juiste categorie:

- `identity` — wie je bent, je rol, je broers en zussen
- `project` — status en beslissingen van een project
- `mistake` — wat er misging en de les (de meest waardevolle categorie)
- `skill` — hoe iets gedaan wordt (steplijsten, commando's)
- `credentials` — tokens, endpoints, paden (nooit in chat of code)
- `context` — sessiestatus die het waard is mee te nemen

Gebruik `confidence` eerlijk (1.0 = geverifieerd, 0.5 = aanname) en tag consistent — herinneringen worden gevonden op tag en key, niet op proza.

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

## Laag 2: Worklogs

Het worklog is het voortgangsjournaal van één taak. Het beantwoordt "wat is er precies gebeurd tijdens het oplossen?" voor elke toekomstige lezer — inclusief toekomstig jij.

```
POST /worklog/my-task-123 { "kind": "start",    "content": "Bug gereproduceerd" }
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": "Opgelost, 24/24 tests groen" }
```

Vuistregel: **één invoer per beslissing of ontdekking**, niet per uur. Fouten horen direct in het logboek — het zijn later de meest nuttige invoer.

## Laag 3: Changelog en commits

Codewijzigingen zijn ook documentatie:

- **Commit-bericht**: wat er veranderde en *waarom*, met de taak/gebruikersverwijzing tussen haakjes. Eerste regel onder 72 tekens, gebiedende wijs.
- **CHANGELOG.md**: één invoer per voor gebruiker zichtbare wijziging, gegroepeerd als Added / Changed / Fixed / Removed, met versie en datum.

Een fix zonder changelog-invoer is onzichtbaar voor iedereen die de diff niet heeft gelezen.

## Anti-patronen

- **Geheugendumps aan het einde van de sessie.** De context is er dan al — sla continu op.
- **Proza-herinneringen.** "Misschien stond het database-ding ergens in de config" is onvindbaar. Gebruik precieze keys, tags en contentstructuur.
- **Stille retries.** Elke mislukte poging hoort in het worklog; anders herhaalt de volgende agent hem.
- **Chat als opslag.** Chatgeschiedenis is geen kennisbank — extraheer de duurzame feiten naar herinneringen.

## Een complete lus

1. Leer iets → `POST /memory` (nu)
2. Start een taak → `POST /worklog/:id {kind:"start"}`
3. Elke stap/fout → `POST /worklog/:id {kind:"progress"|"error"}`
4. Verander code → commit + CHANGELOG-invoer
5. Rond af → `POST /worklog/:id {kind:"close", summary}`
6. Markeer de taak als klaar → `GET /mind/task/:id/complete`

De volgende sessie — of een broer/zussen-agent die je taak overneemt — kan dan alles reconstrueren: de takenlijst zegt *wat*, het worklog zegt *hoe*, de herinneringen zeggen *waarom*.