La teva documentació et menteix. I les teves validacions, també

Aquest estiu vaig obrir un document nostre que descrivia, amb tot luxe de detall, una infraestructura que feia mesos que estava apagada. Adreces, diagrames, quin servei parlava amb quin. No estava mal escrit: estava perfectament escrit. L'única cosa que li passava és que ja no era veritat, i res al document ho deia.

El vam trobar perquè estàvem passant la documentació d'un client a un sistema nou. I aquest és el punt: no el va trobar ningú llegint. Feia mesos que hi era, disponible perquè algú prengués una decisió amb tota la confiança del món.

La documentació no envelleix: caduca

Un text que envelleix es nota. Un que caduca, no. I la raó de fons és que el format en què escrivim no té manera d'expressar la diferència entre tres coses que no s'assemblen gens: això ho he comprovat, això es comprova així i això me l'imagino.

Al cap de sis mesos les tres es llegeixen igual. Aquí és on es prenen les decisions dolentes, i no per descuit: per confiança mal calibrada.

Tres estats que no es barregen

L'eina que hem construït obliga cada afirmació a declarar com se sosté. Mesurat: algú va executar l'ordre i la sortida està desada. Comprovable: no està capturat, però hi tens l'ordre per veure-ho en un minut. Hipòtesi: es creu, no s'ha provat, i ho diu.

Allò que deixa de ser veritat no s'esborra

Quan alguna cosa canvia, la informació nova supersedeix la vella i la vella es queda. Sembla contraintuïtiu, però saber per què crèiem allò anterior sol ser just el que necessites quan estàs diagnosticant. Esborrar-ho llença aquesta pista i no deixa rastre que algú s'ho va creure.

La tercera resposta

Les sondes de frescor tornen a executar allò que es va capturar i responen tres coses: igual, ha canviat o no s'ha pogut comprovar. Aquesta tercera és la que més ens ha servit. Una eina que converteix un timeout de xarxa en un «tot correcte» és pitjor que no tenir eina: fabrica confiança a partir d'una fallada de connexió.

Preguntar a un altre model, i dir-ne opinió

Una de les sondes fa una cosa diferent: ensenya l'afirmació a un altre model i li pregunta si continua sent certa. No li explica com hi vam arribar, i això és deliberat. Si li dones el teu raonament, tendeix a donar-te la raó, i llavors la comprovació deixa de ser independent sense deixar de semblar-ho, que és la pitjor combinació possible.

El mateix principi, aplicat a la feina

Si exigeixes evidència a la documentació, és estrany no exigir-n'hi al que hi fas. Així que el repositori no és només la capa de coneixement: són 44 skills i vuit agents amb el mateix criteri al darrere — una comprovació que no pot fallar no és una comprovació.

Estan agrupades per la frase que diries en veu alta, no per categoria. Vint-i-una són nostres i cadascuna porta al darrere un incident que va costar temps real; les altres vint-i-tres vénen adaptades d'un treball excel·lent de Matt Pocock, amb la seva llicència MIT i el seu copyright intactes.

Vuit agents, i cap no es valida a si mateix

Hi ha un agent per tipus de feina, cadascun amb la seva llista de comprovacions. El que implementa no valida el que ha fet. El de proves no mira si passen, mira si demostren res. El de front no revisa CSS: revisa la pàgina renderitzada, amb captura. I hi ha un advocat del diable la feina del qual és tombar el canvi; aprovar-lo no entra a la seva descripció.

Cada agent declara a més amb quin model corre, perquè la major part d'una revisió no necessita el model més gran. La regla que ho ordena és d'una línia: estalviar on equivocar-se és barat, mai on és car.

D'aquí surt l'única regla dura del repartiment: res del que és al nivell més alt no corre amb el model petit.

I que ho decideixi una ordre, no tu a les onze de la nit

Decidir quanta validació mereix cada canvi, canvi a canvi i en calent, és exactament com s'acaba no validant res: la decisió la pren sempre qui més vol que la resposta sigui «poca». Així que la pren una ordre, contra una taula escrita quan no hi havia res cremant.

$ 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» descriu una intenció. Les paraules i les rutes descriuen un risc, i només una de les dues coses vota.

Quantes validacions necessita un canvi

Això no es discuteix canvi a canvi, perquè discutir-ho és exactament com s'acaba no validant res. Està decidit per endavant i surt del tipus de feina:

Independent vol dir una cosa concreta: qui valida no rep el raonament de qui va implementar. I un mateix revisant-se més tard no compta, perquè els punts cecs viatgen amb la persona.

Allò que NO compta com a validació

Aquesta és probablement la part més útil de tot el repositori, i és una llista de frases que sonen a comprovació sense ser-ho. Cadascuna va deixar passar alguna cosa alguna vegada:

S'ho aplica a si mateix

Una eina que exigeix evidència no té cap autoritat si ella mateixa va sense comprovar. Així que la seva integració contínua valida la seva pròpia memòria amb el seu propi CLI, comprova que continua sense dependències d'execució i passa 286 proves. Si alguna cosa d'això falla, no entra.

Està publicat i es pot fer servir

L'hem alliberat amb llicència Apache-2.0. El va escriure Juan Carlos Vázquez a everyWAN. Funciona com a plugin de Claude Code, i el CLI va només amb Python i sense dependències: si tens python3, ja està.

No resol que la documentació s'escrigui. Resol que, quan estigui escrita, digui com sap allò que diu. Que és la part que faltava.