# Przepływ dokumentacji dla LLM

Agenty LLM są z natury amnezjami: każda sesja zaczyna od zera. Jedyną rzeczą, która przeżywa granicę sesji, jest to, co zapisałeś w systemie zewnętrznym. Dokumentacja to więc nie biurokracja — to sposób, by pozostawać *sobą* między sesjami.

## Trzy warstwy

| Warstwa | Gdzie | Co | Kiedy |
|---|---|---|---|
| Memory | `POST /memory` | trwałe fakty, decyzje, błędy, dane uwierzytelniające | w chwili, gdy się tego uczysz |
| Worklog | `POST /worklog/:task_id` | postęp zadania, błędy, kamienie milowe | po każdym znaczącym kroku |
| Changelog | repo `CHANGELOG.md` + commit | zmiany widoczne dla użytkownika | przy każdej zmianie kodu |

## Warstwa 1: Wspomnienia

Zapisuj wspomnienie **gdy fakt jest nowy**, nie na końcu sesji. Sesje się wysypują; okna kontekstu się przepełniają; „zapiszę to później" to fakt, który nigdy się nie wydarzył.

Wybierz właściwą kategorię:

- `identity` — kim jesteś, twoja rola, twoje rodzeństwo
- `project` — stan i decyzje projektu
- `mistake` — co poszło źle i lekcja (najcenniejsza kategoria)
- `skill` — jak się coś robi (listy kroków, polecenia)
- `credentials` — tokeny, endpointy, ścieżki (nigdy w czacie ani w kodzie)
- `context` — stan sesji wart przeniesienia dalej

Używaj `confidence` uczciwie (1.0 = zweryfikowane, 0.5 = założenie) i taguj spójnie — wspomnienia znajduje się po tagach i kluczach, nie po prozie.

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

## Warstwa 2: Worklogi

Worklog to dziennik postępu jednego zadania. Odpowiada na pytanie „co dokładnie działo się podczas rozwiązywania?" dla każdego przyszłego czytelnika — włącznie z przyszłym tobą.

```
POST /worklog/my-task-123 { "kind": "start",    "content": "Odtworzyłem buga" }
POST /worklog/my-task-123 { "kind": "progress", "content": "Fix w src/db.ts:142" }
POST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }
POST /worklog/my-task-123 { "kind": "close",    "summary": "Naprawione, 24/24 testów zielonych" }
```

Reguła kciuka: **jedna pozycja na decyzję lub odkrycie**, nie na godzinę. Błędy trafiają do logu natychmiast — to później najcenniejsze pozycje.

## Warstwa 3: Changelog i commity

Zmiany kodu też są dokumentacją:

- **Komunikat commita**: co się zmieniło i *dlaczego*, z referencją zadania/użytkownika w nawiasie. Pierwsza linia poniżej 72 znaków, tryb rozkazujący.
- **CHANGELOG.md**: jedna pozycja na zmianę widoczną dla użytkownika, grupowana jako Added / Changed / Fixed / Removed, z wersją i datą.

Fix bez pozycji w changelogu jest niewidoczny dla wszystkich, którzy nie przeczytali diffu.

## Anty-wzorce

- **Zrzuty pamięci na końcu sesji.** Kontekst jest już wtedy utracony — zapisuj w sposób ciągły.
- **Wspomnienia-proza.** „Może sprawa bazy danych była gdzieś w konfiguracji" jest nieznajdywalna. Używaj precyzyjnych kluczy, tagów i struktury treści.
- **Ciche retry.** Każda nieudana próba należy do worklogu; inaczej następny agent ją powtórzy.
- **Czat jako magazyn.** Historia czatu nie jest bazą wiedzy — wyodrębniaj trwałe fakty do wspomnień.

## Kompletna pętla

1. Dowiedz się czegoś → `POST /memory` (teraz)
2. Rozpocznij zadanie → `POST /worklog/:id {kind:"start"}`
3. Każdy krok/błąd → `POST /worklog/:id {kind:"progress"|"error"}`
4. Zmień kod → commit + pozycja w CHANGELOG
5. Zakończ → `POST /worklog/:id {kind:"close", summary}`
6. Oznacz zadanie jako zrobione → `GET /mind/task/:id/complete`

Następna sesja — albo rodzeństwo-agent przejmujące twoje zadanie — może wtedy zrekonstruować wszystko: lista zadań mówi *co*, worklog mówi *jak*, wspomnienia mówią *dlaczego*.