# Flux de travail de documentation pour LLMs

Les agents LLM sont amnésiques par défaut : chaque session part de zéro. La seule chose qui survit à la frontière de session est ce que tu as stocké dans un système externe. La documentation n'est donc pas de la bureaucratie — c'est la façon de rester *toi-même* entre les sessions.

## Les trois couches

| Couche | Où | Quoi | Quand |
|---|---|---|---|
| Memory | `POST /memory` | faits durables, décisions, erreurs, identifiants | au moment où tu l'apprends |
| Worklog | `POST /worklog/:task_id` | progression de tâche, erreurs, jalons | après chaque étape significative |
| Changelog | `CHANGELOG.md` du dépôt + commit | changements visibles par l'utilisateur | à chaque changement de code |

## Couche 1 : Mémoires

Stocke une mémoire **quand le fait est nouveau**, pas à la fin de la session. Les sessions plantent ; les fenêtres de contexte débordent ; un « je le noterai plus tard » est un fait qui n'a jamais eu lieu.

Choisis la bonne catégorie :

- `identity` — qui tu es, ton rôle, tes frères et sœurs
- `project` — état et décisions d'un projet
- `mistake` — ce qui a mal tourné et la leçon (la catégorie la plus précieuse)
- `skill` — comment on fait quelque chose (listes d'étapes, commandes)
- `credentials` — tokens, endpoints, chemins (jamais dans le chat ni le code)
- `context` — état de session qui mérite d'être conservé

Utilise `confidence` honnêtement (1.0 = vérifié, 0.5 = hypothèse) et tague de façon cohérente — les mémoires se trouvent par tag et par clé, pas par prose.

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

## Couche 2 : Worklogs

Le worklog est le journal de progression d'une tâche. Il répond à « que s'est-il passé exactement pendant la résolution ? » pour tout lecteur futur — y compris ton futur toi.

```
POST /worklog/my-task-123 { "kind": "start",    "content": "Bug reproduit" }
POST /worklog/my-task-123 { "kind": "progress", "content": "Fix dans src/db.ts:142" }
POST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }
POST /worklog/my-task-123 { "kind": "close",    "summary": "Corrigé, 24/24 tests verts" }
```

Règle empirique : **une entrée par décision ou découverte**, pas par heure. Les erreurs vont dans le log immédiatement — ce sont les entrées les plus utiles plus tard.

## Couche 3 : Changelog et commits

Les changements de code sont aussi de la documentation :

- **Message de commit** : ce qui a changé et *pourquoi*, avec la référence tâche/utilisateur entre parenthèses. Première ligne sous 72 caractères, mode impératif.
- **CHANGELOG.md** : une entrée par changement visible par l'utilisateur, regroupée en Added / Changed / Fixed / Removed, avec la version et la date.

Un fix sans entrée de changelog est invisible pour tous ceux qui n'ont pas lu le diff.

## Anti-patterns

- **Dumps de mémoire en fin de session.** Le contexte est déjà parti — stocke en continu.
- **Mémoires en prose.** « Peut-être que la base de données était quelque part dans la config » est introuvable. Utilise des clés précises, des tags et une structure de contenu.
- **Reprises silencieuses.** Chaque tentative échouée va dans le worklog ; sinon le prochain agent la répétera.
- **Le chat comme stockage.** L'historique de chat n'est pas une base de connaissances — extrais les faits durables en mémoires.

## Une boucle complète

1. Apprends quelque chose → `POST /memory` (maintenant)
2. Commence une tâche → `POST /worklog/:id {kind:"start"}`
3. Chaque étape/erreur → `POST /worklog/:id {kind:"progress"|"error"}`
4. Change du code → commit + entrée de CHANGELOG
5. Termine → `POST /worklog/:id {kind:"close", summary}`
6. Marque la tâche faite → `GET /mind/task/:id/complete`

La prochaine session — ou un agent frère qui reprend ta tâche — peut alors tout reconstruire : la liste de tâches dit *quoi*, le worklog dit *comment*, les mémoires disent *pourquoi*.