Tu documentación te miente. Y tus validaciones, también

Este verano abrí un documento nuestro que describía, con todo lujo de detalle, una infraestructura que llevaba meses apagada. Direcciones, diagramas, qué servicio hablaba con cuál. No estaba mal escrito: estaba perfectamente escrito. Lo único que le pasaba es que ya no era verdad, y nada en el documento lo decía.

Lo encontramos porque estábamos pasando la documentación de un cliente a un sistema nuevo. Y ese es el punto: no lo encontró nadie leyendo. Llevaba meses ahí, disponible para que alguien tomara una decisión con toda la confianza del mundo.

La documentación no envejece: caduca

Un texto que envejece se nota. Uno que caduca, no. Y la razón de fondo es que el formato en el que escribimos no tiene forma de expresar la diferencia entre tres cosas que no se parecen en nada: esto lo he comprobado, esto se comprueba así y esto me lo imagino.

A los seis meses las tres se leen igual. Ahí es donde se toman las decisiones malas, y no por descuido: por confianza mal calibrada.

Tres estados que no se mezclan

La herramienta que hemos construido obliga a cada afirmación a declarar cómo se sostiene. Medido: alguien ejecutó el comando y la salida está guardada. Comprobable: no está capturado, pero ahí tienes el comando para verlo en un minuto. Hipótesis: se cree, no se ha probado, y lo pone.

Lo que deja de ser verdad no se borra

Cuando algo cambia, la información nueva supersede a la vieja y la vieja se queda. Parece contraintuitivo, pero saber por qué creíamos lo anterior suele ser justo lo que necesitas cuando estás diagnosticando. Borrarlo tira esa pista y no deja rastro de que alguien lo creyó.

La tercera respuesta

Las sondas de frescura vuelven a ejecutar lo que se capturó y responden tres cosas: igual, cambió o no se ha podido comprobar. Esa tercera es la que más nos ha servido. Una herramienta que convierte un timeout de red en un «todo correcto» es peor que no tener herramienta: fabrica confianza a partir de un fallo de conexión.

Preguntar a otro modelo, y llamarlo opinión

Una de las sondas hace algo distinto: le enseña la afirmación a otro modelo y le pregunta si sigue siendo cierta. No le cuenta cómo llegamos a ella, y eso es deliberado. Si le das tu razonamiento, tiende a darte la razón, y entonces la comprobación deja de ser independiente sin dejar de parecerlo, que es la peor combinación posible.

El mismo principio, aplicado al trabajo

Si exiges evidencia a la documentación, es raro no exigírsela a lo que haces con ella. Así que el repositorio no es sólo la capa de conocimiento: son 44 skills y ocho agentes con el mismo criterio detrás — una comprobación que no puede fallar no es una comprobación.

Están agrupadas por la frase que dirías en voz alta, no por categoría. Veintiuna son nuestras y cada una lleva detrás un incidente que costó tiempo real; las otras veintitrés vienen adaptadas de un trabajo excelente de Matt Pocock, con su licencia MIT y su copyright intactos.

Ocho agentes, y ninguno se valida a sí mismo

Hay un agente por tipo de trabajo, cada uno con su lista de comprobaciones. El que implementa no valida lo suyo. El de pruebas no mira si pasan, mira si demuestran algo. El de front no revisa CSS: revisa la página renderizada, con captura. Y hay un abogado del diablo cuyo trabajo es tumbar el cambio; aprobarlo no entra en su descripción.

Cada agente declara además con qué modelo corre, porque la mayor parte de una revisión no necesita el modelo más grande. La regla que ordena eso es de una línea: ahorrar donde equivocarse es barato, nunca donde es caro.

De ahí sale la única regla dura del reparto: nada de lo que está en el nivel más alto corre con el modelo pequeño.

Y que lo decida una orden, no tú a las once de la noche

Decidir cuánta validación merece cada cambio, cambio a cambio y en caliente, es exactamente cómo se acaba no validando nada: la decisión la toma siempre quien más quiere que la respuesta sea «poca». Así que la toma una orden, contra una tabla escrita cuando no había nada ardiendo.

$ validated-memory route "small tweak to the checkout flow" \
      --path src/billing/refund.py

Level 3 — 3 validations

  matched money: billing, checkout, refund
  matched touched path: billing

  model   : opus
  effort  : high
  agents  : security-reviewer, data-reviewer, devils-advocate

«Small tweak» describe una intención. Las palabras y las rutas describen un riesgo, y sólo una de las dos cosas vota.

Cuántas validaciones necesita un cambio

Esto no se discute cambio a cambio, porque discutirlo es exactamente cómo se acaba no validando nada. Está decidido de antemano y sale del tipo de trabajo:

Independiente quiere decir algo concreto: quien valida no recibe el razonamiento de quien implementó. Y uno mismo revisándose más tarde no cuenta, porque los puntos ciegos viajan con la persona.

Lo que NO cuenta como validación

Ésta es probablemente la parte más útil de todo el repositorio, y es una lista de frases que suenan a comprobación sin serlo. Cada una dejó pasar algo alguna vez:

Se lo aplica a sí mismo

Una herramienta que exige evidencia no tiene ninguna autoridad si ella misma va sin comprobar. Así que su integración continua valida su propia memoria con su propio CLI, comprueba que sigue sin dependencias de ejecución y pasa 286 pruebas. Si algo de eso falla, no entra.

Está publicado y se puede usar

Lo hemos liberado con licencia Apache-2.0. Lo escribió Juan Carlos Vázquez en everyWAN. Funciona como plugin de Claude Code, y el CLI va solo con Python y sin dependencias: si tienes python3, ya está.

No resuelve que la documentación se escriba. Resuelve que, cuando esté escrita, diga cómo sabe lo que dice. Que es la parte que faltaba.