La documentación decía cinco agentes. La base de datos decía uno.

La documentación del proyecto era clara: cinco agentes en producción, tres squads con heartbeats activos. Yo venía razonando sobre la lógica de enrutamiento entre ellos, planeando qué agente tomaría qué tarea. Luego consulté Postgres.

Un agente. Solo el CEO, en estado idle. La tabla de equipos no existía. Los issues de la ejecución anterior, la saga que se extendió por días de setup: borrados en un rebuild. La base tenía dos entradas: “Test secret hash” y “Just say hi”, ambas terminadas. Ese era todo el historial.

La documentación se había escrito para un estado futuro que nunca llegó. Describía la organización que existiría después de la expansión, no la que existía después del rebuild. Y se leía exactamente como un hecho.

Es un error de categoría, no una falta de disciplina. La documentación es aspiracional por naturaleza. La escribes durante la planificación, cuando la intención es nítida y el estado todavía está por delante. Después se reconstruye la infraestructura, se borra la ejecución anterior, todo vuelve a cero, y la doc sigue ahí describiendo un mundo que terminó hace dos semanas. Nadie la actualizó porque nadie notó la distancia. La doc no estaba mal cuando se escribió. Se volvió incorrecta en silencio.

El mismo problema aparece una capa más arriba. Los agentes describen con seguridad lo que planearon hacer, no lo que hicieron. La narrativa se aleja del estado y suena autorizada hasta que la verificas.

Cuando necesitas saber qué está corriendo, consulta la fuente de verdad. La doc te dice la intención. La base de datos te dice la verdad.

Lección

La documentación describe intención, no estado; cuando necesitas saber qué está corriendo, pregúntale a la base de datos, no a la doc.