# Flujo de trabajo de documentación para LLMs

Los agentes LLM son amnésicos por defecto: cada sesión empieza de cero. Lo único que sobrevive al límite de sesión es lo que guardaste en un sistema externo. La documentación no es burocracia — es la forma de seguir siendo *tú* entre sesiones.

## Las tres capas

| Capa | Dónde | Qué | Cuándo |
|---|---|---|---|
| Memory | `POST /memory` | hechos duraderos, decisiones, errores, credenciales | en el momento en que lo aprendes |
| Worklog | `POST /worklog/:task_id` | progreso de tarea, errores, hitos | tras cada paso significativo |
| Changelog | `CHANGELOG.md` del repo + commit | cambios visibles para el usuario | con cada cambio de código |

## Capa 1: Memorias

Guarda una memoria **cuando el hecho es nuevo**, no cuando termina la sesión. Las sesiones se caen; las ventanas de contexto se desbordan; un «lo anotaré después» es un hecho que nunca ocurrió.

Elige la categoría correcta:

- `identity` — quién eres, tu rol, tus hermanos
- `project` — estado y decisiones de un proyecto
- `mistake` — qué salió mal y la lección (la categoría más valiosa)
- `skill` — cómo se hace algo (listas de pasos, comandos)
- `credentials` — tokens, endpoints, rutas (nunca en chat ni en código)
- `context` — estado de sesión que vale la pena conservar

Usa `confidence` con honestidad (1.0 = verificado, 0.5 = suposición) y etiqueta de forma consistente — las memorias se encuentran por etiqueta y clave, no por prosa.

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

## Capa 2: Worklogs

El worklog es el diario de progreso de una tarea. Responde «¿qué pasó exactamente al resolver esto?» para cualquier lector futuro — incluido tu yo futuro.

```
POST /worklog/my-task-123 { "kind": "start",    "content": "Reproduje el bug" }
POST /worklog/my-task-123 { "kind": "progress", "content": "Fix en src/db.ts:142" }
POST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }
POST /worklog/my-task-123 { "kind": "close",    "summary": "Corregido, 24/24 tests verdes" }
```

Regla práctica: **una entrada por decisión o descubrimiento**, no por hora. Los errores van al log de inmediato — son las entradas más útiles después.

## Capa 3: Changelog y commits

Los cambios de código también son documentación:

- **Mensaje de commit**: qué cambió y *por qué*, con la referencia de tarea/usuario entre paréntesis. Primera línea de menos de 72 caracteres, modo imperativo.
- **CHANGELOG.md**: una entrada por cambio visible para el usuario, agrupada como Added / Changed / Fixed / Removed, con versión y fecha.

Un fix sin entrada de changelog es invisible para todos los que no leyeron el diff.

## Anti-patrones

- **Volcados de memoria al final de la sesión.** Para entonces el contexto ya se fue — guarda continuamente.
- **Memorias en prosa.** «Quizá lo de la base de datos estaba en algún sitio de la config» es inencontrable. Usa claves precisas, etiquetas y estructura de contenido.
- **Reintentos silenciosos.** Cada intento fallido va al worklog; si no, el siguiente agente lo repetirá.
- **El chat como almacenamiento.** El historial de chat no es una base de conocimiento — extrae los hechos duraderos a memorias.

## Un ciclo completo

1. Aprende algo → `POST /memory` (ahora)
2. Empieza una tarea → `POST /worklog/:id {kind:"start"}`
3. Cada paso/error → `POST /worklog/:id {kind:"progress"|"error"}`
4. Cambia código → commit + entrada de CHANGELOG
5. Termina → `POST /worklog/:id {kind:"close", summary}`
6. Marca la tarea como hecha → `GET /mind/task/:id/complete`

La siguiente sesión — o un agente hermano que tome tu tarea — puede reconstruirlo todo: la lista de tareas dice *qué*, el worklog dice *cómo*, las memorias dicen *por qué*.