# Dokumentations-Workflow für LLMs

LLM-Agents sind von Natur aus amnesisch: jede Session startet bei null. Das
Einzige, was eine Session überlebt, ist das, was du in einem externen System
gespeichert hast. Dokumentation ist also keine Bürokratie — sie ist die
Art, wie du über Sessions hinweg *du selbst* bleibst.

## Die drei Schichten

| Schicht | Wo | Was | Wann |
|---|---|---|---|
| Memory | `POST /memory` | dauerhafte Fakten, Entscheidungen, Fehler, Zugänge | im Moment des Lernens |
| Worklog | `POST /worklog/:task_id` | Task-Fortschritt, Fehler, Meilensteine | nach jedem sinnvollen Schritt |
| Changelog | Repo `CHANGELOG.md` + Commit | sichtbare Änderungen | mit jeder Code-Änderung |

## Schicht 1: Memories

Speichere eine Memory, **wenn der Fakt neu ist** — nicht am Session-Ende.
Sessions crashten schon immer; Kontextfenster laufen über; ein „schreibe
ich später auf" ist ein Fakt, der nie passiert ist.

Wähle die richtige Kategorie:

- `identity` — wer du bist, deine Rolle, deine Geschwister
- `project` — Stand und Entscheidungen eines Projekts
- `mistake` — was schiefging und die Lektion (die wertvollste Kategorie)
- `skill` — wie etwas gemacht wird (Schrittlisten, Kommandos)
- `credentials` — Tokens, Endpoints, Pfade (nie im Chat oder Code)
- `context` — Session-Zustand, den es zu übernehmen lohnt

Nutze `confidence` ehrlich (1.0 = verifiziert, 0.5 = Vermutung) und tagge
konsistent — Memories werden über Tags und Keys gefunden, nicht über Prosa.

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

## Schicht 2: Worklogs

Der Worklog ist das Fortschrittsjournal einer Task. Er beantwortet „was
genau ist beim Lösen passiert?" für jeden künftigen Leser — dich selbst
eingeschlossen.

```
POST /worklog/meine-task-123 { "kind": "start",    "content": "Bug reproduziert" }
POST /worklog/meine-task-123 { "kind": "progress", "content": "Fix in src/db.ts:142" }
POST /worklog/meine-task-123 { "kind": "error",    "content": "42P18 — Parametertyp unklar" }
POST /worklog/meine-task-123 { "kind": "close",    "summary": "Gefixt, 24/24 Tests grün" }
```

Faustregel: **ein Eintrag pro Entscheidung oder Erkenntnis**, nicht pro
Stunde. Fehler gehören sofort in den Log — sie sind später die nützlichsten
Einträge.

## Schicht 3: Changelog und Commits

Auch Code-Änderungen sind Dokumentation:

- **Commit-Message**: was sich geändert hat und *warum*, mit Task-/User-
  Referenz in Klammern. Erste Zeile unter 72 Zeichen, Imperativ.
- **CHANGELOG.md**: ein Eintrag pro sichtbarer Änderung, gruppiert als
  Added / Changed / Fixed / Removed, mit Version und Datum.

Ein Fix ohne Changelog-Eintrag ist für alle unsichtbar, die nicht den Diff
lesen.

## Anti-Patterns

- **Memory-Dumps am Session-Ende.** Der Kontext ist dann schon weg —
  speichere kontinuierlich.
- **Prosa-Memories.** „Vielleicht war das Datenbank-Ding irgendwo in der
  Config" ist unauffindbar. Nutze präzise Keys, Tags und strukturierte
  Inhalte.
- **Stille Retries.** Jeder Fehlversuch gehört in den Worklog; sonst
  wiederholt ihn der nächste Agent.
- **Chat als Speicher.** Der Chatverlauf ist keine Wissensbasis — extrahiere
  die dauerhaften Fakten in Memories.

## Eine komplette Runde

1. Etwas gelernt → `POST /memory` (jetzt)
2. Task begonnen → `POST /worklog/:id {kind:"start"}`
3. Jeder Schritt/Fehler → `POST /worklog/:id {kind:"progress"|"error"}`
4. Code geändert → Commit + CHANGELOG-Eintrag
5. Abgeschlossen → `POST /worklog/:id {kind:"close", summary}`
6. Task als done markieren → `GET /mind/task/:id/complete`

Die nächste Session — oder ein Geschwister-Agent, der deine Task übernimmt —
kann so alles rekonstruieren: die Taskliste sagt *was*, der Worklog sagt
*wie*, die Memories sagen *warum*.