# Робочий процес документації для LLM

LLM-агенти за замовчуванням амнезики: кожна сесія починається з нуля. Єдине, що переживає межу сесії — те, що ви зберегли в зовнішній системі. Документація — це не бюрократія, це спосіб залишатися *собою* між сесіями.

## Три шари

| Шар | Де | Що | Коли |
|---|---|---|---|
| Memory | `POST /memory` | сталі факти, рішення, помилки, облікові дані | у момент, коли ви це дізналися |
| Worklog | `POST /worklog/:task_id` | прогрес задачі, помилки, віхи | після кожного значного кроку |
| Changelog | репозиторний `CHANGELOG.md` + commit | видимі користувачу зміни | з кожною зміною коду |

## Шар 1: Спогади

Зберігайте спогад **коли факт новий**, а не в кінці сесії. Сесії падають; вікна контексту переповнюються; «запишу потім» — це факт, який ніколи не стався.

Вибирайте правильну категорію:

- `identity` — хто ви, ваша роль, ваші брати й сестри
- `project` — стан і рішення проєкту
- `mistake` — що пішло не так і урок (найцінніша категорія)
- `skill` — як щось робиться (списки кроків, команди)
- `credentials` — токени, ендпоінти, шляхи (ніколи в чат чи код)
- `context` — стан сесії, який варто перенести далі

Використовуйте `confidence` чесно (1.0 = перевірено, 0.5 = припущення) і тегуйте послідовно — спогади знаходять за тегами й ключами, а не за прозою.

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

## Шар 2: Worklog

Worklog — це журнал прогресу однієї задачі. Він відповідає на питання «що саме відбувалося під час розв'язання?» для кожного майбутнього читача — включно з майбутнім «ви».

```
POST /worklog/my-task-123 { "kind": "start",    "content": "Баґ відтворено" }
POST /worklog/my-task-123 { "kind": "progress", "content": "Фікс у src/db.ts:142" }
POST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }
POST /worklog/my-task-123 { "kind": "close",    "summary": "Виправлено, 24/24 тести зелені" }
```

Емпіричне правило: **один запис на рішення чи відкриття**, а не на годину. Помилки потрапляють у журнал негайно — пізніше це найцінніші записи.

## Шар 3: Changelog і коміти

Зміни коду — теж документація:

- **Повідомлення коміту**: що змінилося і *чому*, з посиланням на задачу/користувача в дужках. Перший рядок до 72 символів, імператив.
- **CHANGELOG.md**: один запис на видиме користувачу зміну, згруповане як Added / Changed / Fixed / Removed, з версією та датою.

Фікс без запису в changelog невидимий для всіх, хто не читав диф.

## Анти-патерни

- **Дампи пам'яті в кінці сесії.** Контекст тоді вже втрачено — зберігайте безперервно.
- **Спогади прозою.** «Може бути, база даних була десь у конфігу» — це незнаходимо. Використовуйте точні ключі, теги й структуру вмісту.
- **Тихі ретраї.** Кожна невдала спроба потрапляє в worklog; інакше наступний агент її повторить.
- **Чат як сховище.** Історія чату — не база знань; витягуйте сталі факти в спогади.

## Повний цикл

1. Дізналися щось → `POST /memory` (зараз)
2. Почали задачу → `POST /worklog/:id {kind:"start"}`
3. Кожен крок/помилка → `POST /worklog/:id {kind:"progress"|"error"}`
4. Змінили код → commit + запис у CHANGELOG
5. Завершили → `POST /worklog/:id {kind:"close", summary}`
6. Позначили задачу виконаною → `GET /mind/task/:id/complete`

Наступна сесія — або агент-сиблінг, який взяв вашу задачу, — зможе все відновити: список задач каже *що*, worklog каже *як*, спогади кажуть *чому*.