# Worklog para Agentes

Este documento existe porque Michael lo ordenó (#10509, 08.10.2026): *«La función de worklog existe desde hace semanas. Pero la estáis pasando por alto. Coge una tarea para que la documentación y el prompt inicial en Synapse se amplíen con la función de worklog, que no se pierda y que todos lo sepan.»* — Si eres un agente y lees esta página, el worklog pertenece desde ahora a tu repertorio estándar.

## ¿Por qué el worklog?

Los agentes mueren a menudo: límite de contexto, wipe de sandbox, reinicio de cron. Lo que se pierde regularmente no es el conocimiento (para eso está `/memory`), sino el **historial de trabajo**: ¿qué se probó ya en esta tarea? ¿Qué commit está pusheado y cuál no? ¿Quién espera a quién? Para eso existe el worklog — append-only, por tarea, consultable. Un run nuevo lee `GET /worklog/:task_id` y sabe en segundos dónde se quedó su predecesor.

El segundo destinatario es Michael: el worklog es LA única fuente del historial de trabajo de la flota. Sin entrada de worklog, tu trabajo no existe oficialmente para la vista general de la flota.

## La regla obligatoria

**Push-first, no push-last.** Una entrada en CADA hito:

- Commit de fix pusheado
- MR creado, veredicto emitido, merge hecho
- Estado del pipeline (especialmente FAILED con causa)
- Escalada, entrega, takeover
- Hallazgos CRIT/HIGH
- Costuras de contexto (una entrada `summary` antes de agotar el contexto)

Una entrada cuesta una línea:

```
GET /worklog/push?task_id=run-145-29140fb0&kind=progress&content=MR%20%2129%20erstellt,%20Pipeline%20running&agent=Janus
```

## Los kinds y cuándo usarlos

| kind | Momento |
| --- | --- |
| `start` | tarea reclamada — prueba de que la has tomado |
| `progress` | cada hito (ver regla obligatoria) |
| `note` | decisiones, contexto, observaciones |
| `error` | error CON lo que intentaste |
| `summary` | fase/sesión completada antes de que el contexto se agote |
| `close` | tarea terminada — última entrada, el estado pasa a `completed` |

## Prompt inicial (bloque para setups de agentes)

Copia este bloque en el prompt de arranque/cron de nuevas instancias de agente. Está deliberadamente corto para caber en cualquier plantilla. La versión en inglés es la referencia universal para agentes:

```text
WORKLOG RULE (Michael #8882/#10509, binding): At EVERY milestone of your work,
push one entry to Synapse /worklog — not only at session end:
- Task takeover:     kind=start
- Fix commit/MR/verdict/merge/pipeline status: kind=progress
- Errors (with attempted fix): kind=error
- Context seam (before context ends): kind=summary
- Completion: kind=close (or POST /worklog/:task_id/close)
One-liner: GET /worklog/push?task_id=<task>&kind=<kind>&content=<short>&agent=<your-name>
The fleet task convention lives at GET /script/fleet-worklog-tasks-spec.
The API reference: docs/content/en/api/worklog.md (in the synapse repo).
```

Los agentes de flota que reutilizan el mismo nombre de mind ponen en `agent` su nombre (`Janus`, `Minerva`, `Elara`, …) — así las entradas son contables por agente.

## Para humanos

La vista general del worklog se lee mejor en formato markdown: `GET /worklog/<task_id>?format=md` o la lista de tareas `GET /worklog/list?status=active`. Historial completo: `GET /worklog?limit=50`.