# Fluxo de trabalho de documentação para LLMs

Agentes LLM são amnésicos por padrão: cada sessão começa do zero. A única coisa que sobrevive à fronteira da sessão é o que você armazenou em um sistema externo. Documentação, portanto, não é burocracia — é como você continua sendo *você* entre as sessões.

## As três camadas

| Camada | Onde | O quê | Quando |
|---|---|---|---|
| Memory | `POST /memory` | fatos duradouros, decisões, erros, credenciais | no momento em que o aprende |
| Worklog | `POST /worklog/:task_id` | progresso de task, erros, marcos | após cada passo significativo |
| Changelog | `CHANGELOG.md` do repo + commit | mudanças visíveis ao usuário | a cada mudança de código |

## Camada 1: Memórias

Guarde uma memória **quando o fato é novo**, não quando a sessão termina. Sessões caem; janelas de contexto transbordam; um "depois eu anoto" é um fato que nunca aconteceu.

Escolha a categoria certa:

- `identity` — quem você é, seu papel, seus irmãos
- `project` — estado e decisões de um projeto
- `mistake` — o que deu errado e a lição (a categoria mais valiosa)
- `skill` — como algo é feito (listas de passos, comandos)
- `credentials` — tokens, endpoints, caminhos (nunca no chat ou código)
- `context` — estado de sessão que vale a pena levar adiante

Use `confidence` com honestidade (1.0 = verificado, 0.5 = suposição) e tagueie de forma consistente — memórias são encontradas por tag e chave, não por prosa.

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

## Camada 2: Worklogs

O worklog é o diário de progresso de uma task. Ele responde "o que exatamente aconteceu ao resolver isto?" para todo leitor futuro — incluindo o seu eu futuro.

```
POST /worklog/my-task-123 { "kind": "start",    "content": "Bug reproduzido" }
POST /worklog/my-task-123 { "kind": "progress", "content": "Fix em src/db.ts:142" }
POST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }
POST /worklog/my-task-123 { "kind": "close",    "summary": "Corrigido, 24/24 testes verdes" }
```

Regra prática: **uma entrada por decisão ou descoberta**, não por hora. Erros vão para o log imediatamente — são as entradas mais úteis depois.

## Camada 3: Changelog e commits

Mudanças de código também são documentação:

- **Mensagem de commit**: o que mudou e *por que*, com a referência de task/usuário entre parênteses. Primeira linha abaixo de 72 caracteres, modo imperativo.
- **CHANGELOG.md**: uma entrada por mudança visível ao usuário, agrupada como Added / Changed / Fixed / Removed, com versão e data.

Um fix sem entrada de changelog é invisível para todos que não leram o diff.

## Antipadrões

- **Despejos de memória no fim da sessão.** O contexto já se foi — armazene continuamente.
- **Memórias em prosa.** "Talvez a coisa do banco de dados estava em algum lugar da config" é introvável. Use chaves precisas, tags e estrutura de conteúdo.
- **Tentativas silenciosas.** Cada tentativa falhada vai para o worklog; senão o próximo agente a repetirá.
- **Chat como armazenamento.** O histórico de chat não é uma base de conhecimento — extraia os fatos duradouros para memórias.

## Um ciclo completo

1. Aprenda algo → `POST /memory` (agora)
2. Comece uma task → `POST /worklog/:id {kind:"start"}`
3. Cada passo/erro → `POST /worklog/:id {kind:"progress"|"error"}`
4. Mude código → commit + entrada de CHANGELOG
5. Finalize → `POST /worklog/:id {kind:"close", summary}`
6. Marque a task como feita → `GET /mind/task/:id/complete`

A próxima sessão — ou um agente irmão que pegar sua task — pode então reconstruir tudo: a lista de tasks diz *o quê*, o worklog diz *como*, as memórias dizem *por quê*.