Los contratos de peldaño

Un archivo por peldaño. Todos tienen el mismo esqueleto, y lo tienen a propósito, para que puedas compararlos y para que, con el tiempo, el reflejo de leerlos sea automático: el encabezado con el tramo, el cuándo, la forma y el tamaño (obligatorio o proporcional); para qué sirve; (1) el contexto requerido, nombrado en forma genérica; (2) los prompts, en inglés, cada uno precedido por un bloque "Antes de enviar el prompt" (los archivos y los insumos que tenés que tener hechos vos antes de pegarlo, con su contenido y su estado mínimo), seguido de su traducción y, debajo, de la explicación de qué le estoy pidiendo al modelo y por qué cada cláusula está ahí; (3) el resultado esperado, con sus características; (4) la verificación de completitud, que hacés sin leer código; (5) las señales de alarma, los síntomas de un peldaño mal subido.

Los prompts en inglés son una sola pieza, idéntica en las ocho versiones del documento; node build/build.mjs los extrae a prompts/ y verifica que ninguna traducción los haya alterado. La traducción que acompaña a cada prompt es para que lo entiendas; al modelo se le pega el inglés.

Los escribí a partir de lo que hice en tres sistemas que hoy están en producción, no los ejecuté tal cual todavía. El primer proyecto que los use de punta a punta va a corregir varios; eso es parte del peldaño 23. Cuando un contrato cita un caso real, lo hace con una marca [Ref. N] que enlaza al documento de referencias; el procedimiento queda limpio y el detalle sigue a un clic.

Tramos: arranque se sube una vez por proyecto; bucle se repite con cada cambio; operación cuando el sistema ya está vivo. El 23 vuelve al 0 para el proyecto siguiente. La línea de tiempo completa, con lo que pasa entre peldaño y peldaño, está en la Parte B del documento principal.

Peldaño 0 — ¿Este proyecto se puede encarar así? (contrato del peldaño)

Tramo: arranque. Cuándo: una sola vez, antes de abrir el repositorio y antes de cualquier otra cosa. Forma: conversación: el agente evalúa y pregunta; vos decidís. Tamaño: obligatorio en todo proyecto, por chico que sea. Estado: los criterios excluyentes X1 y X2 están cerrados; los criterios que ponderan (D1 a D10) todavía los estoy calibrando y los marco como hipótesis.

Para qué sirve

No te metas en un proyecto donde el método no puede funcionar. Si el agente no va a poder verificarse solo de punta a punta, o si no hay un dueño del dominio que decida, el método se degrada a "programar con IA" y vos terminás leyendo código. Este peldaño es la puerta de entrada: se cruza una vez, y si no se cruza, mejor saberlo antes que después.

Y una idea de fondo que quiero que tengas clara: el método no sirve para cualquier proyecto, y eso no es un defecto. Un método que promete servir para todo no está diciendo nada. Lo que este peldaño hace es poner la frontera por escrito, para que la decisión de entrar o no entrar sea una decisión y no una esperanza. Los dos criterios excluyentes salen de proyectos que rechacé, no de los que acepté Ref. 46.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

Nombrado en forma genérica; el agente evalúa si alcanza y pide lo que falte.

• Relevamiento del pedido: qué quiere el cliente, para quién, y qué pasa hoy sin el sistema.
• Relevamiento tecnológico: qué tecnología hay o se propone, si existe un sistema anterior, si ese sistema tiene repositorio y cómo está manejado.
• Relevamiento de testeabilidad: si las pantallas se pueden ejecutar por programa y si cada elemento de la interfaz es accesible con sus distintos métodos (clic, tipeo, lectura de estado), de modo que un test recorra la pantalla y verifique el efecto en el backend.
• Quién es el dueño del dominio y cuánto tiempo tiene para decidir.
• Qué consecuencia tiene un error (plata, salud, operación, nada).
• Entornos y accesos: si va a haber un entorno de prueba, si el agente puede acceder, si hay producción consultable en solo lectura.

2. Prompts

Los prompts van en inglés, que es el idioma en el que los modelos siguen instrucciones con más precisión y menos tokens. Cada uno trae su traducción (en el HTML, con un botón), y debajo la explicación de qué le estoy pidiendo y por qué cada cláusula está ahí. Al modelo se le pega el inglés.

Inicial:

Qué le estoy pidiendo: que lea los dos insumos (el relevamiento y la ficha de criterios); que antes de responder evalúe si el relevamiento alcanza y, si no alcanza, pregunte en vez de suponer (esta es la cláusula central de todos los prompts del método); que complete la ficha con la fuente de cada respuesta, para que después se pueda rastrear; que marque los excluyentes en verde o rojo; y que no decida, porque la elegibilidad la decido yo. La última línea le pide que conteste en mi idioma, porque el prompt está en inglés pero la conversación no tiene por qué estarlo.

De cierre:

Qué le estoy pidiendo: que deje la decisión escrita con fecha y dueño (peldaño 6), con las condiciones si las hay, y con el rastro de preguntas y respuestas, que es la evidencia de que no supuso nada.

3. Resultado esperado

Un archivo docs/ELIGIBILITY.md (o el nombre que use tu proyecto), de una página, con:

• Fecha y quién decidió.
• Los dos criterios excluyentes con su respuesta y su fuente:
• X1: hay repositorio accesible y manejado de forma estándar (o el proyecto es nuevo).
• X2: la interfaz se puede ejecutar por programa y cada elemento es accesible con sus distintos métodos, con verificación del efecto en el backend.
• Los criterios que ponderan, cada uno con respuesta, fuente y peso (cuando el peso esté calibrado).
• La decisión: va, no va, o va con condiciones, y las condiciones escritas.
• Las preguntas que el agente hizo y las respuestas, para que quede el rastro.

4. Verificación de completitud (la hacés vos, sin leer código)

• ¿Los dos excluyentes tienen respuesta explícita y fuente? Si alguno está en rojo, ¿la decisión es "no va" o tiene una condición que lo resuelve?
• ¿Hay algún criterio respondido con "supongo que sí" o "probablemente"? Si lo hay, el peldaño no está subido: el agente tenía que preguntar.
• ¿La decisión está escrita con fecha y con nombre?
• ¿Las condiciones (si las hay) son verificables? ("Tener acceso de lectura a producción antes del peldaño 3" sí; "que el cliente colabore" no.)

5. Señales de alarma

• El agente completó la ficha entera sin hacer una sola pregunta. O el relevamiento era perfecto (nunca lo es) o supuso.
• La decisión es "va con condiciones" y las condiciones son más de tres. Probablemente es un "no va" que no se quiere decir.
• El criterio X2 se respondió "sí, con un poco de trabajo". Si las pantallas no se pueden operar por programa hoy, ese "poco de trabajo" es el proyecto entero.

Peldaño 1 — El contrato de convivencia (contrato del peldaño)

Tramo: arranque. Cuándo: una sola vez, inmediatamente después de la elegibilidad; se revisa cuando un golpe lo exige. Forma: un solo tiro, con una vuelta de ajuste tuya. Tamaño: obligatorio en todo proyecto. Es el peldaño más barato de todos y el que más frustración evita.

Para qué sirve

Poné por escrito, antes de la primera línea de código, cómo van a trabajar vos y el agente. Parece una formalidad y no lo es: es lo que evita que el agente "ayude" expandiendo el alcance, deje deuda para después, o reporte como hecho lo que cree que hizo. En mi herramienta este archivo se llama SQ.md (estándares de calidad); el nombre no importa, el contenido sí.

Pensalo así: el agente es un colaborador nuevo que llega cada mañana sin memoria de ayer. El contrato es lo que le decís el primer día, y lo que va a releer cada día. Si no lo escribís, se lo vas a tener que decir cada vez, y lo vas a decir distinto cada vez. Yo lo escribí por primera vez cuando llevaba dos semanas repitiendo lo mismo en cada sesión Ref. 1, y nada de lo que puse era nuevo en ingeniería de sistemas; lo nuevo era tener que escribirlo para alguien sin memoria.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• Ninguno del proyecto: es el primer archivo.
• Tuyo: tus preferencias de trabajo (idioma, cómo querés que te pregunten, qué considerás una pérdida de tu tiempo, qué nivel de autonomía le das al agente).

2. Prompts

Inicial:

Qué le estoy pidiendo: las seis reglas mínimas, cada una con el fallo que evita (eso es lo que las vuelve reglas y no consejos); que proponga reglas propias del proyecto pero las marque como propuestas, para que vos las aceptes o rechaces; y que pregunte lo que necesite saber sobre vos. Un contrato redactado sin una sola pregunta es sospechoso: el agente no conoce a la persona con la que va a trabajar.

De cierre:

Qué le estoy pidiendo: que cierre el contrato con fecha y versión, y que lo enganche al archivo de proyecto para que se lea en cada sesión. Sin ese enganche el contrato existe pero no actúa.

3. Resultado esperado

Un archivo docs/WORKING_AGREEMENT.md (o SQ.md, o CONTRATO.md) con:

• Fecha y versión.
• Cada regla numerada, en una o dos frases, con el fallo que evita.
• Las reglas propias del proyecto, marcadas como tales.
• Una línea al pie que diga que el agente propone cambios pero no edita el contrato solo.

Y una línea en el archivo de proyecto (PROJECT.md o CLAUDE.md) que ordene leerlo al empezar cada sesión.

4. Verificación de completitud

• ¿Están las seis reglas mínimas, cada una con el fallo que evita?
• ¿Hay alguna regla escrita como aspiración ("tratar de…", "en lo posible…")? Si la hay, no sirve: las reglas se cumplen o no.
• ¿El archivo de proyecto ordena leerlo en cada sesión?
• ¿El agente te hizo al menos una pregunta sobre cómo trabajás? Si redactó todo sin preguntar nada, es sospechoso: no te conoce.

5. Señales de alarma

• El contrato tiene más de veinte reglas. Nadie, ni humano ni modelo, respeta veinte reglas; se respetan seis u ocho.
• Una regla dice "el agente puede modificar este contrato cuando lo considere necesario". No.
• Dos semanas después, el agente hace algo que el contrato prohíbe y nadie lo nota. El contrato no se está leyendo: revisá el enganche en el archivo de proyecto.

Peldaño 2 — La definición del proyecto, el árbol semántico y la lectura obligatoria (contrato del peldaño)

Tramo: arranque. Cuándo: se escribe una vez, después del contrato; el árbol semántico y el estado vivo se mantienen al día durante todo el proyecto, con cada bloque y cada decisión nueva. Forma: conversación: el agente redacta, pregunta lo que falta, vos corregís. Tamaño: obligatorio en todo proyecto. En uno chico, el archivo de proyecto puede tener cincuenta líneas y el árbol semántico veinte nodos; lo que no pueden es no existir.

Para qué sirve

Cada sesión del agente arranca de cero: no se acuerda de ayer. Dale un mapa, corto, que le diga qué es el proyecto, en qué estado está y qué decisiones ya se tomaron, y obligalo a leerlo antes de tocar nada. El fallo que evita es doble: trabajo descartable por no leer el mapa Ref. 9, y el mapa que crece hasta volverse ilegible Ref. 41. La regla práctica: el archivo de proyecto es el programa, no el historial. Lo que pasó va a otro lado.

El mapa tiene dos piezas, y la segunda es la que más trabajo hace. La primera es el archivo de proyecto: qué es el sistema, para quién, qué NO es, las decisiones tomadas. La segunda es el árbol semántico: el sistema descompuesto como un árbol, con los dominios, y debajo de cada uno sus actores, sus procesos (los casos de uso), sus entidades con sus estados, sus pantallas y sus integraciones; y de cada nodo cuelgan los pendientes y las decisiones que lo tocan. El árbol sale del relevamiento que hiciste con los métodos clásicos de la ingeniería de requerimientos (entrevistas, casos de uso, modelo de dominio), lo construye el agente, lo corregís vos, y es lo que le da al modelo el contexto exacto del nodo que va a tocar sin tener que leer todo el proyecto. Y es lo que te permite a vos verificar, sin leer código, que el sistema que el agente entiende es el que el negocio pidió.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• Relevamiento del negocio: qué hace el cliente, quiénes usan el sistema, qué problema resuelve, qué no tiene que hacer. Con las entrevistas, los casos de uso o historias de usuario que puedas nombrar, y las entidades del negocio con sus estados, aunque estén incompletos.
• El contrato de convivencia (peldaño 1).
• Si existe un sistema anterior: acceso de lectura a su código o a su documentación.
• Las decisiones ya tomadas, si las hay, aunque sea de palabra.

2. Prompts

Inicial:

Qué le estoy pidiendo: que evalúe el relevamiento y pregunte antes de redactar; que el archivo de proyecto sea corto (el tope de trescientas líneas es arbitrario pero necesario: sin tope, crece); que diga explícitamente qué no es el sistema, porque lo que no está dicho es lo que el modelo va a inventar; que las decisiones tengan fecha; que construya el árbol semántico con la estructura completa (dominios, actores, casos de uso con sus partes, entidades con estados y transiciones, pantallas, integraciones), que es el modelo de dominio de la ingeniería de requerimientos puesto en forma de árbol; que marque lo que infirió, porque es ahí donde se esconden las invenciones; y que separe el estado vivo en otro archivo, para que el mapa no se convierta en historial.

De cierre:

Qué le estoy pidiendo: tus correcciones (sobre todo a los nodos que marcó como inferidos), la fecha, y dos reglas nuevas en el contrato: la que protege al archivo de proyecto de volverse historial, y la que ata cada pendiente a un nodo del árbol, que es lo que mantiene el árbol vivo y lo que te permite detectar en diez segundos un pendiente fuera de alcance.

3. Resultado esperado

• PROJECT.md (o CLAUDE.md): corto, de lectura obligatoria, con qué es, para quién, qué no es, módulos, decisiones con fecha, y la orden de leerlo junto con el árbol. Máximo trescientas líneas.
• docs/SEMANTIC_TREE.md: el árbol semántico, con los nodos inferidos marcados hasta que los confirmes, y, desde el primer bloque, los pendientes y decisiones colgando de sus nodos.
• docs/STATUS.md: estado vivo, separado de los anteriores.
• En los tres, una fecha de última actualización.
• En el contrato, las dos reglas nuevas.

4. Verificación de completitud

• ¿PROJECT.md cabe en una lectura de cinco minutos? Si no, está mal: es el programa, no el historial.
• ¿Dice explícitamente qué NO hace el sistema? (Lo que falta es lo que el agente va a inventar.)
• Recorré el árbol semántico como si fueras el cliente: ¿están todos los actores que vos conocés? ¿Cada entidad tiene los estados que el negocio usa, ni más ni menos? ¿Hay algún nodo que no reconozcas? Ese es un invento: corregilo ahora.
• ¿Los nodos inferidos están marcados? ¿Los confirmaste o corregiste todos?
• ¿Cada decisión tiene fecha y quién la tomó?
• ¿El agente preguntó algo sobre el negocio antes de redactar? Si no preguntó nada, revisá qué supuso.
• ¿El estado vivo está en otro archivo?
• La prueba de lectura: cerrá la sesión, abrí una nueva, y preguntale qué NO hace el sistema y de qué nodo del árbol cuelga tal pantalla. Si contesta con el mapa, el enganche funciona.

5. Señales de alarma

• El archivo de proyecto creció más de un 20 % en un mes. Algo que no es programa está entrando.
• El agente empieza una sesión proponiendo algo que ya se decidió y está escrito. No leyó el mapa: el enganche de lectura obligatoria falló.
• La sección "qué no es" está vacía o dice "nada en particular". Todo sistema tiene límites; si no están escritos, el modelo los va a cruzar.
• Hay pendientes que no cuelgan de ningún nodo del árbol. O el árbol quedó viejo o esos pendientes están fuera de alcance; las dos cosas hay que mirarlas.
• Una entidad del árbol tiene un estado que el negocio nunca nombró. El modelo lo inventó porque le pareció lógico, y va a construir sobre él.

Peldaño 3 — Dimensionar antes de diseñar la arquitectura (contrato del peldaño)

Tramo: arranque. Cuándo: una vez, después de la definición y antes de armar el esqueleto; se rehace si el negocio cambia de escala. Forma: conversación: el agente calcula y presenta opciones; vos elegís. Tamaño: obligatorio siempre, pero proporcional: en un proyecto chico el dimensionamiento puede ser media página y una sola decisión ("cabe en SQLite durante años"). Lo que no puede es no hacerse, porque la pregunta "¿cuánto va a crecer?" cuesta cinco minutos y la respuesta equivocada cuesta semanas.

Para qué sirve

Tomá las decisiones estructurales —qué motor de base de datos, si la interfaz es sincrónica o asincrónica, cuánta concurrencia— con números y no con gusto. Es el peldaño que más caro cuesta saltearse, y lo digo con conocimiento de causa: en uno de mis sistemas arranqué con archivos JSON y cuando medí resultó que iba a generar 3,4 millones de filas por año; cambiar la interfaz después costó una etapa entera de reingeniería Ref. 15.

Hay un punto clave que vale la pena que tengas presente: hay datos que solo el negocio tiene (cuántas entidades, cuántos eventos por entidad, cuántos operadores en el pico, cuánto hay que conservar) y el modelo no los puede inferir. Lo que sí puede inferir es lo derivado. Por eso el prompt le exige evaluar si los datos primarios están completos y pedir los que falten, en vez de estimarlos con cara de seguro. El que sabe qué le falta para calcular es el modelo, no un formulario.

Y una segunda idea que quiero que te lleves: las decisiones asimétricas. Hay decisiones que cuestan muy poco si las tomás y resultan innecesarias, y muchísimo si no las tomás y resultan necesarias. La interfaz de persistencia asincrónica desde la línea uno es el ejemplo canónico: si el motor termina siendo sincrónico, sobró un await; si termina siendo asincrónico y no lo previste, hay que reescribir todo. Esas decisiones tomalas siempre que sean baratas, aunque hoy no hagan falta.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• Relevamiento de datos de volumetría del negocio, nombrado así en forma genérica: entidades principales y su crecimiento, eventos por entidad, operadores simultáneos y horario del pico, tiempo de conservación de los datos, cargas excepcionales (campañas, cierres), crecimiento esperado. El relevamiento es por naturaleza incompleto; el agente evalúa y pide.
• Si hay un sistema anterior: acceso de lectura a su base para sacar números reales en vez de estimados.
• PROJECT.md y el árbol semántico (peldaño 2): las entidades del árbol son las que hay que dimensionar.

2. Prompts

Inicial:

Qué le estoy pidiendo, cláusula por cláusula: distinguir primarios de derivados (es la distinción que evita el invento); pedir los primarios que falten y no estimarlos nunca; usar números reales del sistema anterior cuando exista, con su fuente; calcular lo derivado con la cuenta a la vista, para que vos puedas rehacerla; el escenario "por diez", que es lo que revela qué se rompe primero; tres opciones con el costo de migrar entre ellas, porque la decisión no es solo "cuál" sino "cuánto cuesta equivocarse"; y que no elija ni escriba código, porque este peldaño es de decisión, no de construcción.

De cierre:

Qué le estoy pidiendo: el registro completo, con fuentes y cuentas; la elegida y la razón; y las decisiones asimétricas escritas, porque si quedan implícitas no se respetan.

3. Resultado esperado

Un archivo docs/SIZING.md con:

• Fecha y quién decidió.
• Tabla de datos primarios: valor, fuente (informado por el negocio / medido en el sistema anterior), fecha. Ninguno con fuente "supuesto".
• Tabla de datos derivados: valor, de qué primarios sale, la cuenta.
• El escenario "por diez": qué se rompe primero.
• Las tres opciones numeradas, con el costo de migrar entre ellas.
• La elegida y la razón, en una o dos frases.
• Las decisiones asimétricas, listadas.
• Las preguntas que el agente hizo y las respuestas.

4. Verificación de completitud

• ¿Hay algún dato primario con fuente "supuesto" o sin fuente? Si lo hay, el peldaño no está subido: el agente tenía que pedirlo.
• ¿Cada dato derivado muestra de qué primarios sale y con qué cuenta? ¿Podés rehacer una cuenta a mano y te da?
• ¿Hay tres opciones y una elegida con razón escrita?
• ¿Dice qué pasa si la volumetría se multiplica por diez?
• ¿Las decisiones asimétricas están escritas, o quedaron implícitas?
• ¿El agente preguntó? Si presentó números sin haber hecho una sola pregunta, desconfiá.

5. Señales de alarma

• Los tres escenarios de opciones llevan a la misma conclusión. El agente ya había elegido y armó las otras dos para cumplir.
• Un número derivado tiene más precisión que los primarios de los que sale ("1.234.567 filas" a partir de "unas 5.000 familias"). La precisión es falsa.
• El escenario "por diez" dice "no pasa nada". Siempre pasa algo; si no lo encontró, no lo buscó.

Peldaño 4 — El esqueleto con sus compuertas (contrato del peldaño)

Tramo: arranque. Cuándo: una vez, al cierre del arranque, después del dimensionamiento y antes de cualquier funcionalidad. Es acá donde se hace toda la infraestructura inicial y la cadena de integración y despliegue. Forma: un solo tiro largo, con aprobación visual tuya al final. Tamaño: obligatorio en todo proyecto que vaya a tener usuarios. En un prototipo descartable se puede saltear; pero si el prototipo sobrevive (siempre sobreviven), este peldaño es lo primero que hay que pagar.

Para qué sirve

Hacé que el sistema arranque, se pruebe y se despliegue VACÍO antes de tener funcionalidad. Descubrir el despliegue al final es carísimo: en uno de mis sistemas llegó un mes después del arranque y costó cinco pendientes seguidos Ref. 32. Si el esqueleto se despliega en el arranque, esos golpes se dan con cero funcionalidad en juego.

La idea general detrás: el camino a producción es parte del producto, no un trámite del final. Un sistema que funciona en la máquina del programador y no se puede desplegar no es un sistema; es una demo. Y la única forma de saber que el camino funciona es recorrerlo cuando todavía no hay nada que perder. Por eso en este peldaño se monta todo lo que después va a usar el bucle: el repositorio con su estructura, el entorno de prueba, la integración continua que corre la batería en cada push, y el despliegue automático al entorno de prueba.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• docs/SIZING.md (peldaño 3): la opción elegida define el esqueleto.
• Relevamiento de entornos: dónde va a correr (nube, servidor propio), si hay un entorno de prueba y uno de producción, quién tiene acceso, cómo se despliega hoy si hay algo.
• Las credenciales del lugar donde se va a desplegar, aunque sea un servicio gratuito.
• El tipo de proyecto: nuevo, corrección o evolución de algo existente.

2. Prompts

Inicial:

Qué le estoy pidiendo: que verifique que tiene los accesos antes de empezar (sin eso el esqueleto se queda en la máquina del agente); la lista exacta de lo que es un esqueleto (estructura, arranque, un test, integración continua, despliegue a prueba); las compuertas escritas; una captura real del entorno de prueba, que es la única evidencia válida de que se desplegó; y la prohibición explícita de agregar funcionalidad, porque el modelo tiende a "ya que estoy" y eso rompe el alcance exacto.

De cierre:

Qué le estoy pidiendo: dejar los tres comandos donde la próxima sesión los encuentre, y probar que el despliegue es repetible (correrlo dos veces sin romper nada). Esa segunda corrida es la prueba de que el procedimiento es un procedimiento y no una suerte.

3. Resultado esperado

• El repositorio con la estructura, el servidor y la pantalla arrancando.
• Un test de humo en verde y la batería corriendo en integración continua (con el enlace a la corrida en verde).
• El despliegue al entorno de prueba funcionando, con la URL, y corrido dos veces.
• docs/GATES.md: la lista de compuertas, cada una con la condición para pasar.
• Una captura de pantalla del sistema vacío corriendo en el entorno de prueba.
• docs/STATUS.md actualizado con los tres comandos (correr, testear, desplegar).

4. Verificación de completitud

• ¿Podés abrir la URL del entorno de prueba y ver la pantalla vacía? (Lo hacés vos, no el agente.)
• ¿Hay un enlace a una corrida de integración continua en verde?
• ¿El despliegue se corrió dos veces y la segunda no rompió nada?
• ¿Las compuertas están escritas con una condición verificable cada una?
• ¿Hay alguna funcionalidad que no pediste? Si la hay, el agente violó el alcance exacto.

5. Señales de alarma

• El esqueleto "funciona en local" pero el despliegue "lo vemos después". No: el despliegue es el esqueleto.
• La captura de pantalla es de la máquina del agente, no del entorno de prueba. Pedí la URL.
• Las compuertas dicen cosas como "el código tiene buena calidad". Una compuerta es una condición verificable: "la batería está en verde", "el despliegue a prueba funcionó".

Peldaño 5 — El plan son los pendientes: la especificación detallada vive en cada uno (contrato del peldaño)

Tramo: bucle. Cuándo: el registro se crea al abrir el primer bloque funcional, apenas termina el arranque; cada bloque nuevo arranca convirtiendo el pedido del cliente en pendientes especificados; la rutina se usa en cada sesión durante todo el proyecto; la documentación del pendiente hecho se escribe al cerrarlo, en la misma sesión. Forma: un solo tiro al abrir cada bloque; después, rutina de cada sesión. Tamaño: obligatorio en todo proyecto. Es el peldaño que hace que todos los demás se puedan seguir: sin pendientes numerados y especificados no hay dónde colgar ni la especificación ni la evidencia.

Para qué sirve

Tené una sola cola de trabajo, con orden y con compuerta, que sea la verdad del proyecto. No hay "plan" por un lado y "tareas" por otro: la lista de pendientes ES el plan. Evita la especificación larga que se supera a las dos semanas y queda obsoleta Ref. 17, y el trabajo del que nadie sabe por qué se hizo Ref. 7.

Pero hay más, y es lo que distingue a este peldaño de una lista de tareas cualquiera. En el método clásico existía un documento de especificación de requerimientos, largo, que describía todo lo que el sistema tenía que hacer y que envejecía antes de terminarse. Acá ese documento se descompone: la especificación detallada vive en cada pendiente. Un pendiente bien escrito trae: el nodo del árbol semántico del que cuelga; la historia de usuario o caso de uso que lo origina, con las palabras del cliente; la descripción detallada; las reglas de negocio aplicables, con su decisión y su fecha; los datos que entran y salen; las pantallas afectadas, con el prototipo si lo hay; los casos borde y las excepciones; los criterios de aceptación en la forma "dado, cuando, entonces"; y cómo se verifica. La suma de los pendientes es la especificación del sistema, y la trazabilidad (requerimiento → pendiente → test → commit) no es una matriz aparte: es el pendiente mismo.

Y lo tercero, que cierra el círculo: los pendientes cerrados son documentación. Cuando un pendiente se cierra, no se borra ni se archiva vacío: queda con su especificación, la decisión que lo originó, la evidencia con la que se cerró (los números del rojo y del verde, la captura, el número medido), el commit y la fecha. La cola de pendientes cerrados es el historial funcional del sistema: qué se construyó, por qué, cuándo y cómo se probó. De ahí salen el diario de cambios, las secciones nuevas del manual, y la respuesta a "¿por qué el sistema hace esto?" seis meses después.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• El pedido del cliente para el bloque, en prosa, tal como lo diría él, con sus ambigüedades. Si hiciste casos de uso o historias de usuario en la ingesta, mejor: son la unidad natural de un bloque.
• El árbol semántico (peldaño 2), para colgar cada pendiente de su nodo.
• Las auditorías y los hallazgos de las pruebas humanas, si ya hubo.
• PROJECT.md y docs/STATUS.md.

2. Prompts

Para abrir un bloque:

Qué le estoy pidiendo: que convierta el pedido en ítems verificables y que pregunte cuando el pedido no da para escribir uno verificable (la ambigüedad se resuelve preguntando, no eligiendo); la especificación completa de cada pendiente, campo por campo, que es la ingeniería de requerimientos clásica descompuesta en unidades chicas; el nodo del árbol del que cuelga, que es lo que te permite detectar un pendiente fuera de alcance; las reglas de negocio con su decisión o marcadas como faltantes, que es el enganche con el peldaño 6; los criterios de aceptación en la forma clásica, que son el guion del test de punta a punta del peldaño 8; y un orden propuesto con su razón, para que vos lo confirmes o lo cambies.

Rutina de cada sesión (va en el contrato de convivencia):

Qué le estoy pidiendo: la disciplina de cada sesión: anunciar qué se toma y releer la especificación (el agente arranca sin memoria, y la especificación es su memoria del pendiente), citar el pendiente en cada commit, cerrar con evidencia, documentar el pendiente hecho en el mismo registro, y anotar en vez de hacer lo que aparezca fuera de la lista. Esa última cláusula es la que protege el alcance exacto cuando el modelo "ve algo más".

3. Resultado esperado

docs/PENDING.md (o la herramienta que use tu proyecto) con, por pendiente:

• Número, título, estado (abierto / en curso / cerrado), fecha de apertura y de cierre.
• El nodo del árbol semántico.
• La historia o caso de uso de origen, con las palabras del cliente.
• La especificación detallada: descripción, reglas de negocio con decisión y fecha, datos, pantallas, casos borde, criterios de aceptación, cómo se verifica.
• Al cerrarse: la evidencia, el commit, la fecha, las decisiones tomadas en el camino.

Y la rutina en el contrato de convivencia.

4. Verificación de completitud

• Leé la especificación de un pendiente al azar como si fueras el cliente: ¿describe lo que pediste, con tus palabras de origen? ¿Los criterios de aceptación son los que vos usarías para decir "está bien"? ¿Hay un caso borde que vos conocés y no está?
• ¿Cada pendiente cuelga de un nodo del árbol? ¿Hay alguno colgado de un nodo que no reconocés?
• ¿Cada pendiente dice cómo se verifica? Un pendiente sin verificación no se puede cerrar.
• ¿Hay reglas de negocio marcadas como "faltante, preguntada" que no te preguntaron?
• ¿Hay pendientes "cerrados" sin evidencia ni commit? Si los hay, reabrilos. ¿Los cerrados conservan su especificación y su documentación de cierre?
• Tomá tres commits al azar: ¿citan su pendiente?
• ¿Apareció en el código algo que no tiene pendiente? Ahí el agente se salió del alcance.

5. Señales de alarma

• Un pendiente lleva más de tres sesiones "en curso". O es tres pendientes, o está trabado por una decisión que nadie tomó (peldaño 6).
• Hay más pendientes cerrados en un día que commits ese día. Se están cerrando sin evidencia.
• Las especificaciones son de una línea. El agente las escribió para cumplir, no para construir sobre ellas; va a inventar lo que falta en el momento de construir.
• La lista tiene más de cincuenta pendientes abiertos. No es un plan, es un inventario de ansiedades: hay que priorizar y archivar.
• Alguien pregunta por qué el sistema hace algo y la respuesta no está en ningún pendiente cerrado. La documentación del hecho no se está escribiendo.

Peldaño 6 — Las decisiones se escriben junto al código (contrato del peldaño)

Tramo: bucle. Cuándo: en cada sesión del bucle, cada vez que el agente se topa con una regla de negocio no escrita o con una bifurcación que cambia lo que el usuario ve. Suelen ser dos o tres por bloque. También en el arranque (peldaños 0 y 3) y en la salida a producción (14 y 15). Forma: conversación corta: el agente detecta que hay una decisión, pregunta, y la deja escrita. Tamaño: obligatorio en todo proyecto. En uno chico el registro puede ser una tabla de diez filas; lo que importa es que las reglas de negocio tengan dueño.

Para qué sirve

Hacé que cada regla de negocio y cada decisión estructural tenga dueño, fecha y lugar. Si no, en seis semanas nadie sabe si "aprobada más saldo vuelve a la cola" fue una decisión del cliente o una ocurrencia del agente. Y evitá lo peor: el agente inventando reglas de dominio porque le parecieron razonables.

Esto tiene una consecuencia que quiero decir en voz alta: el modelo, cuando se encuentra con un hueco en las reglas, lo llena. No se detiene; completa con lo que le parece más probable, y lo hace con la misma naturalidad con que escribe lo demás. Por eso la rutina de este peldaño no es "escribí las decisiones" sino "frená y preguntá cuando falte una". Lo segundo es lo difícil, y es lo que hay que exigir en el contrato. La práctica de dejar la regla escrita en el commit, con mis palabras y la fecha, la impuse en la Obra Social Ref. 29, y la de congelar las decisiones antes de construir viene de mi herramienta Ref. 5.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• La conversación con el dueño: es el único contexto. El agente no puede decidir reglas de negocio.
• Un lugar acordado donde se escriben las decisiones: el mensaje del commit, la especificación del pendiente, y un registro docs/DECISIONS.md.

2. Prompts

Rutina (va en el contrato de convivencia):

Qué le estoy pidiendo: que frene ante una regla no escrita o una bifurcación visible; que pregunte con recomendación y alternativa (para que vos decidas en diez segundos, no en diez minutos); que registre la decisión con tus palabras textuales en los tres lugares (el commit, el pendiente, el registro), no con una paráfrasis "mejorada"; y, para cuando no contestás, la opción más reversible marcada como "por omisión", que es lo que permite seguir sin que la decisión desaparezca.

De cierre (cada decisión):

Qué le estoy pidiendo: el formato mínimo de una decisión: la regla textual, quién, cuándo. Tres cosas; sin ninguna de las tres no es una decisión registrada.

3. Resultado esperado

• docs/DECISIONS.md: una línea o un párrafo por decisión, con fecha, quién decidió, la frase textual, el pendiente o commit donde se aplicó, y si fue "por omisión".
• En la especificación de cada pendiente afectado: la regla con su decisión y fecha.
• En cada commit que implementa una regla de negocio: la frase de origen.

4. Verificación de completitud

• Abrí tres commits que toquen reglas de negocio: ¿cada uno cita quién decidió y cuándo?
• ¿Hay decisiones "por omisión" sin confirmar? Confirmalas o revertilas; no las dejes.
• ¿Hay alguna regla en el sistema que no reconocés como tuya? Si la hay, el agente la inventó: es un fallo del peldaño, se escribe como pendiente y se revisa.
• ¿Las frases están textuales o "mejoradas" por el agente? Tienen que ser las tuyas.

5. Señales de alarma

• Pasó una semana de trabajo y el registro de decisiones no creció. O el trabajo fue puramente mecánico (raro) o el agente decidió solo.
• Las decisiones registradas están todas redactadas con el mismo estilo pulido. Son paráfrasis del agente, no tus palabras.
• Un usuario del sistema pregunta "¿por qué hace esto?" y nadie encuentra la decisión.

Peldaño 7 — Medir antes de construir, con un instrumento que también se verifica (contrato del peldaño)

Tramo: bucle. Cuándo: cada vez que un pendiente depende de un número o de una hipótesis de causa, ANTES de construir. En el arranque, el dimensionamiento es el primer caso. En un proyecto chico, "medir" es contar con un comando y anotar el número con la fecha. Forma: un solo tiro por medición; a veces una conversación cuando la hipótesis es tuya. Tamaño: proporcional. El trinquete y el presupuesto de consultas son para sistemas con volumen. Lo que no cambia con el tamaño: ningún número que decide algo sale de una impresión.

Para qué sirve

Hacé que todo número que alimenta una decisión salga de un programa con test, y no de una búsqueda de texto, de una impresión, ni de "me parece que son como cien". Y hacé que el instrumento mismo se audite, porque los medidores mienten: uno de los míos no veía 84 llamadas con el contador en cero, y otro decía 27 cuando eran 44 Ref. 35, Ref. 36. Las cinco reglas que escribí después de eso son: medidor con guarda; si el instrumento no existe se construye; se audita en dos direcciones; lo aproximado se marca; y el que ejecuta verifica los números del que planificó.

Este peldaño es el que más tardé en formalizar, y por una razón que vale la pena contar: daba por sentado que un modelo aplicaría solo algo tan básico de la ingeniería como "medí antes de tocar". No lo aplica. El modelo es muy bueno produciendo afirmaciones con número ("hay unos 120 bucles de ese tipo") y esas afirmaciones suenan exactamente igual cuando están medidas y cuando están estimadas. No tenés forma de distinguirlas por el tono. La única forma es exigir el instrumento: "¿con qué lo mediste? mostrame el comando". Si no hay comando, es una impresión, por más decimales que tenga. Las reglas las impuse yo en sesión, corrigiendo al agente, antes de que fueran doctrina Ref. 45.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• La hipótesis, tuya o del agente: "creo que el problema es X", "deben ser como cien".
• Acceso a lo que se quiere medir: el código, la base en solo lectura, el log.
• Los medidores que ya existen en el repositorio, si los hay.

2. Prompts

Inicial:

Qué le estoy pidiendo, cláusula por cláusula: el medidor en el repositorio (no un comando suelto que se pierde); el test del medidor contra un caso conocido (la guarda); la cláusula de completitud en su forma para medir (pedir el acceso, no aproximar en silencio); marcar lo aproximado con su margen; el número con el comando que lo produce, para que vos puedas correrlo; la auditoría en dos direcciones, que es lo que desenmascaró a mis dos medidores que mentían; y el orden: primero medir, después proponer.

Cuando hay un presupuesto:

Qué le estoy pidiendo: que el presupuesto sea lo medido más poco, no un número redondo, y que tenga un test que falle si se supera. Así una regresión de rendimiento aparece en la batería y no en producción Ref. 37.

Cuando el que planificó dio números (regla cinco):

Qué le estoy pidiendo: que el que ejecuta no confíe en los números del que planificó, aunque sea el mismo modelo en otra sesión. En mi caso, tres de cuatro aseveraciones del plan estaban mal; donde había instrumento, el número era exacto.

3. Resultado esperado

• El medidor en el repositorio (tools/measure_*.py, scripts/meter-*.mjs o similar), con su test.
• El número, con el comando que lo produce y la fecha.
• La auditoría en dos direcciones, escrita en dos o tres líneas.
• Lo aproximado marcado como tal, con su margen.
• Si hay presupuesto: el valor, el margen, y el test que lo protege.
• En el commit: "measured: [number] with [meter]".

4. Verificación de completitud

• ¿Podés correr vos el comando del medidor y te da el mismo número? (Lo corrés vos; no hace falta entenderlo, solo ejecutarlo.)
• ¿El medidor tiene test? ¿Contra qué caso conocido?
• ¿Hay algún número en el reporte sin medidor atrás? Preguntá de dónde salió.
• ¿Lo aproximado está marcado?
• Si el plan traía números, ¿el agente los verificó antes de ejecutar y te dijo cuáles no daban?

5. Señales de alarma

• Un número cambió entre dos reportes sin que el código cambiara. Uno de los dos no se midió.
• El medidor da cero. Casi nunca es cero; casi siempre el medidor no está viendo algo.
• El agente propone construir "mientras mide", para ganar tiempo. El orden es el método: primero el número, después el plan.

Peldaño 8 — Tests como candados, probados en rojo (contrato del peldaño)

Tramo: bucle. Cuándo: con cada pendiente, al cerrarlo: el test en rojo y en verde, la regresión de los vecinos y la prueba de punta a punta del flujo tocado. La batería completa de punta a punta de todos los flujos, al cierre de cada bloque y antes de cada despliegue a producción. Forma: un solo tiro; el agente ejecuta y reporta, vos leés el reporte. Tamaño: obligatorio en todo proyecto. Es el corazón del método: si hay un peldaño que no se puede negociar, es este.

Para qué sirve

Un test que nunca viste fallar no sabés si prueba algo. La regla acá no es "escribí tests": es "demostrá que el test se pone en rojo contra el código viejo, y después en verde con el nuevo". Evita los tests que pasan porque no prueban nada, y el verde que esconde un bug Ref. 44.

Por qué esto es más importante con un modelo que con un programador humano: el modelo escribe el código y el test en la misma sesión, con el mismo entendimiento. Si entendió mal el pedido, el test va a probar lo que entendió, y va a pasar. El rojo contra el código viejo es la única forma barata de comprobar que el test está mirando lo que importa: si el código viejo lo pasa, el test no distingue el antes del después, y entonces no sirve. El caso que mejor lo muestra es el de los contadores que no coincidían Ref. 26.

Hay una objeción seria a este peldaño, y la quiero dejar escrita porque la van a usar en contra: el mismo agente que escribe el test y el código puede fingir el rojo. Un estudio publicado en agosto de 2026 midió que, cuando a un agente se le pide el ciclo de test primero, a veces se saltea el rojo, lo cuenta sin haberlo corrido, o implementa antes del test para que pase de entrada (está en la Parte F del documento principal, la de los trabajos relacionados). Mi respuesta tiene tres piezas, y las tres están en la escalera. La primera, acá: el rojo no es un relato, es un recibo: el comando exacto, el identificador de la versión contra la que corrió, la cantidad de tests que fallan y el código de salida, todo pegado tal como salió, de manera que vos puedas volver a correrlo con un solo comando sin entender lo que hace. La segunda, en el peldaño 13: la auditoría por otra sesión vuelve a correr una muestra de esos recibos. La tercera, en el peldaño 9: las pruebas de mutación, que plantan errores a propósito y cuentan cuántos atrapan los tests; es la única medida que, en ese mismo estudio, distinguió a los tests que vigilan de los que decoran.

Y la segunda mitad: las pruebas de punta a punta. Un test que verifica desde la pantalla (hace clic, tipea, lee) y comprueba el efecto en el backend (la fila quedó, el estado cambió) es el que reemplaza tu lectura del código. Los criterios de aceptación del pendiente ("dado, cuando, entonces") son su guion. Y se corren tres veces en tres escalas: el flujo tocado con cada pendiente, todos los flujos al cierre de cada bloque, y todos los flujos con la versión exacta antes de producción.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• El cambio ya implementado (por defecto los tests van después de implementar; "primero el test" queda como opción para alcances chicos y bien definidos).
• El pendiente que origina el cambio, con sus criterios de aceptación y su "cómo se verifica".
• La batería existente y el comando para correrla (peldaño 4).

2. Prompts

Rutina (va en el contrato de convivencia; se aplica en cada cambio):

El rojo del primer bloque. En el primer bloque de un proyecto nuevo no hay código anterior: el test nuevo falla porque el módulo no existe, y ese fallo no demuestra que el test distinga comportamiento. Por eso, cuando la versión anterior no tiene el módulo, el rojo se prueba por mutación: el agente planta un defecto a propósito en la función que acaba de escribir, muestra el test en rojo contra ese defecto (el recibo lleva el diff del defecto, para que vos veas que no fue trivial), lo revierte y muestra el verde. Es un solo mutante por pendiente, ejecutado y registrado como cualquier otro recibo; las pruebas de mutación sobre toda la base siguen siendo el refuerzo opcional del peldaño 9. (Decisión D-037, a partir de la práctica Turnera: seis recibos de rojo que solo decían "el archivo no carga".)

Qué le estoy pidiendo, cláusula por cláusula: (1) el test, guiado por los criterios de aceptación del pendiente; (2) el rojo demostrado como recibo (comando, versión, números, código de salida), que es la cláusula que distingue este método de "escribí tests" y la que impide que el rojo sea un relato; (3) el verde; (4) la regresión de los vecinos en la misma sesión, porque un cambio rompe cosas al lado; (5) la prueba de punta a punta del flujo tocado, con el efecto en el backend a la vista; (6) no simular justamente lo que se prueba; y la cláusula de completitud adaptada a este peldaño: si falta algo para probar de punta a punta, pedirlo, no simularlo. El mensaje de commit con los números deja la evidencia donde vive el código.

Al cierre de cada bloque y antes de cada despliegue a producción:

Qué le estoy pidiendo: la segunda y la tercera escala de las pruebas de punta a punta, con la versión exacta (no "la última"), con el efecto en el backend por flujo, y con la cláusula de completitud: lo que no está cubierto se declara y se vuelve pendiente, no se pasa por cubierto.

Cuando el agente dice que no se puede probar:

Qué le estoy pidiendo: que "no se puede probar" no sea el final de la conversación sino el principio de un pendiente. La no-testeabilidad es deuda, y la deuda se registra.

3. Resultado esperado

• El test nuevo en el repositorio, nombrado con el pendiente que cierra.
• En el reporte del agente y en el mensaje del commit: la salida en rojo como recibo (el comando, la versión contra la que corrió, cuántos fallan, el código de salida), la salida en verde, y la regresión en verde con sus números.
• La prueba de punta a punta del flujo tocado, con la evidencia de que el backend cambió (la fila, el registro, el estado).
• Al cierre de cada bloque y antes de producción: la batería completa de punta a punta en verde, por flujo, con la versión exacta.

4. Verificación de completitud

• ¿El reporte muestra el rojo? Con números: "4 de 8 fallan contra el criterio viejo". Si solo muestra verde, el peldaño no está subido.
• ¿El rojo es un recibo o un relato? Tiene que tener el comando exacto, la versión contra la que corrió, los números y el código de salida. Una vez por bloque, elegí un pendiente al azar y corré vos ese comando: el rojo tiene que volver a aparecer.
• ¿La regresión corrió en la misma sesión? ¿Cuántos tests, cuántos en verde?
• ¿Hay alguna parte "simulada" (mock) justo donde está el cambio? Preguntale al agente qué simuló y por qué.
• ¿El commit cita el pendiente y dice "probado en rojo"?
• ¿La prueba de pantalla verifica también el efecto en el backend?
• Al cierre del bloque: ¿están todos los flujos en la batería de punta a punta, o hay alguno que "se cubre con los unitarios"?

5. Señales de alarma

• Todos los tests nuevos de la semana pasaron en verde a la primera, y nunca se mostró un rojo. O el agente está omitiendo el paso o los tests no prueban nada.
• La batería tarda cada vez más y nadie sabe por qué. Suele ser que los tests de punta a punta se fueron reemplazando por simulaciones "para que corra rápido".
• El agente reporta "los tests pasan" sin decir cuántos. Siempre con números.
• El rojo viene contado en prosa ("el test falló como se esperaba") sin comando, sin versión y sin números. Un rojo sin recibo vale lo mismo que ninguno.
• Llegás a la salida a producción y la batería completa de punta a punta se corre por primera vez. Faltaron los cierres de bloque.

Peldaño 9 — Calidad del código verificada por máquina, con compuerta (contrato del peldaño)

Tramo: bucle. Cuándo: se monta una vez, al abrir el primer bloque funcional (apenas termina el arranque), y desde entonces corre solo en cada commit, como compuerta de la integración continua; cada pendiente se cierra con la calidad en verde, después del test en rojo (8) y antes del caso de prueba manual (10). Al cierre de cada bloque y antes de cada despliegue, el reporte de calidad se lee con el dueño. En un legado, la primera corrida es la línea base y los hallazgos entran al backlog con su marca de velocidad. Forma: un solo tiro para montar; después, rutina de cada cambio y lectura por bloque. Tamaño: obligatorio en su nivel mínimo en todo proyecto (un linter y un límite de tamaño en la cadena); completo, con pruebas de mutación incluidas, en cualquier proyecto con usuarios. Las pruebas de mutación quedan como refuerzo opcional solo cuando no hay usuarios reales (una herramienta interna, un prototipo que nadie más corre).

Para qué sirve

El dueño no lee el código, y ese es el punto del método. Pero el código existe, lo va a mantener alguien (el próximo agente, el próximo desarrollador), y un código que funciona hoy y es ilegible mañana es deuda que se cobra en el mes tres. Si nadie lo lee, lo tiene que mirar una máquina: herramientas que, en cada commit, miden lo que un revisor humano miraría y lo convierten en un número con un límite. Yo lo hice en todos mis proyectos, sin nombrarlo como peldaño, y una auditoría de calidad me devolvió un componente de más de dos mil líneas y un archivo de proyecto de casi diez mil Ref. 41: ninguno de los dos habría pasado un límite de tamaño escrito. El trinquete estático, que impide que un número de calidad empeore Ref. 35, es la forma que le doy a este peldaño.

Lo que se mide por máquina, en orden de importancia: que el código respete un estilo único (el linter y el formateador); que ninguna función ni ningún archivo pase de un tamaño; que la complejidad de cada función quede bajo un límite; que no haya código duplicado ni código muerto; que las dependencias estén declaradas y usadas; que la cobertura de los tests no baje nunca (el trinquete); y, si el lenguaje lo permite, que los tipos cierren. Nada de esto reemplaza el test en rojo: un código impecable puede estar equivocado. Lo que evita es el código correcto que nadie puede volver a tocar.

Y la pieza que dejo de tratar como refuerzo opcional en cualquier proyecto con usuarios: las pruebas de mutación. Las dejé como "opcional, recomendado" en una versión anterior de este documento, y una evaluación externa del método me hizo notar la contradicción: si la Parte F dice que la mutación es, hasta donde sé, la única medida que distinguió en los estudios de 2026 los tests que vigilan de los que decoran, no tiene sentido dejarla afuera de "completo" justo en los proyectos donde un test decorativo más le hace daño a alguien. Una herramienta planta errores a propósito en el código (cambia un "mayor" por "mayor o igual", borra una línea, invierte una condición) y corre los tests; cada error que los tests no atrapan es un mutante que sobrevive, y la proporción de atrapados es el puntaje. Es la medida que complementa al rojo demostrado del peldaño 8: el rojo prueba que un test vigila el cambio de hoy; la mutación mide cuánto vigila la batería entera. Y es, hasta donde sé, la única que en los estudios de 2026 distinguió los tests que prueban de los que decoran (Parte F del documento principal).

Si sos principiante. Un linter es un programa que lee el código y marca lo que está mal escrito o es peligroso (una variable que no se usa, una comparación que siempre da lo mismo), como el corrector ortográfico de un procesador de texto. Un formateador lo acomoda con un estilo único (sangrías, espacios) para que todo el código parezca escrito por la misma mano. La complejidad de una función es cuántos caminos distintos puede tomar (cada "si" la aumenta); una función con cuarenta caminos no la entiende nadie. Código duplicado es el mismo bloque copiado en dos lugares: el día que se arregla uno, el otro queda mal. La cobertura es qué porcentaje del código es ejecutado por algún test. Y un trinquete es un mecanismo que solo deja mejorar: el número de hoy es el piso de mañana. Las pruebas de mutación son un programa que rompe el código a propósito, de a un cambio chico por vez, y mira si algún test se da cuenta; si ninguno se da cuenta, ese pedazo de código no está vigilado.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• La integración continua corriendo en cada push (peldaño 4).
• El primer bloque funcional abierto, con al menos un pendiente construido: sin código no hay calidad que medir.
• Tu decisión sobre los límites, o la disposición a aceptar los que el agente proponga, con razón.
• La auditoría anterior (13, o N3 en un legado), si hubo.

2. Prompts

Inicial (montar la compuerta):

Qué le estoy pidiendo: las cinco verificaciones que un revisor humano haría, hechas por máquina y con la construcción en rojo como consecuencia, porque una verificación que no bloquea es un consejo; los límites con su valor medido, para que el límite salga del número y no de una opinión; el trinquete de cobertura, que es la pieza que hace que la calidad no se degrade sola; y no arreglar nada todavía, porque en un sistema con código ya escrito la primera corrida siempre da rojo y la decisión de qué se arregla ahora y qué se tolera con fecha es mía.

Rutina (va en el contrato de convivencia):

Qué le estoy pidiendo: que la calidad sea parte del cierre de cada pendiente y no una tarea aparte; la prohibición de silenciar (un modelo frente a un linter en rojo tiende a agregar la excepción en vez de arreglar, porque es más rápido) y de subir el límite; y la lectura por bloque, que es el único momento en que vos mirás los números.

Obligatorio en cualquier proyecto con usuarios (opcional solo sin usuarios reales): pruebas de mutación.

Qué le estoy pidiendo: la medida que la cobertura no da (la cobertura dice qué código se ejecutó; la mutación dice qué código está vigilado); el alcance acotado a las líneas cambiadas, que es lo que hace que el costo se pueda pagar en cada pendiente; no arreglar nada todavía, porque decidir qué mutante importa es mío; y el puntaje al cierre de cada bloque, junto a la cobertura, con una baja tratada como rojo.

3. Resultado esperado

• El linter, el formateador, los límites, la detección de duplicación y código muerto, la cobertura con trinquete y los tipos, corriendo en cada push y en rojo cuando corresponde.
• docs/CODE_QUALITY.md con herramientas, configuración, límites con valor medido, y la lista de lo que falla con su pendiente o su fecha.
• La compuerta en docs/GATES.md y la rutina en el contrato.
• En cualquier proyecto con usuarios: el puntaje de mutación en docs/CODE_QUALITY.md, por bloque, junto a la cobertura, y un pendiente por cada mutante que sobrevive en código que importa.

4. Verificación de completitud (la hacés vos, sin leer código)

• Pedile el enlace a la última corrida de la cadena: ¿la calidad está en verde?
• Pedile que meta a propósito, en una rama, una función de cien líneas y una variable sin usar: ¿la cadena se pone en rojo por las dos cosas?
• ¿La cobertura de hoy es mayor o igual que la del cierre del bloque anterior? Pedí los dos números.
• ¿Hay alguna excepción al linter en el código? Pedile la lista; cada una tiene que tener razón escrita.
• ¿Subió algún límite desde la primera corrida? ¿Con qué razón y quién lo decidió?
• Si el proyecto tiene usuarios reales: ¿están corriendo las pruebas de mutación? Si no, ¿qué razón escrita justifica no tenerlas?
• Si hay pruebas de mutación: ¿cuántos mutantes sobrevivieron en el último bloque, y cada uno tiene pendiente o razón escrita?

5. Señales de alarma

• La calidad pasó en verde a la primera sobre código ya escrito. Casi nunca es verdad: los límites están demasiado flojos.
• El agente propone "desactivar esta regla porque es muy estricta". A veces tiene razón; siempre tiene que pasar por vos con la razón escrita.
• La cobertura sube porque se agregaron tests que no prueban nada (el verde que esconde un bug, peldaño 8). El trinquete mide cantidad; el rojo demostrado mide calidad. Van juntos.
• Un archivo creció hasta el límite y se partió en dos archivos con el mismo contenido. Es la duplicación disfrazada de cumplimiento.
• La cobertura es alta y el puntaje de mutación es bajo. Son tests que ejecutan el código sin verificar nada: el caso exacto que el rojo demostrado del peldaño 8 intenta evitar.
• El proyecto tiene usuarios reales y nadie corrió las pruebas de mutación ni escribió por qué no. "Es opcional" dejó de ser una razón válida para un proyecto con usuarios.

Peldaño 10 — Los casos de prueba manual se escriben junto con la funcionalidad, y los ejecutan personas (contrato del peldaño)

Tramo: bucle. Cuándo: con cada pendiente, al cerrarlo, después del test en rojo (8) y de la calidad (9): el agente escribe los casos de prueba manual del flujo que tocó. Se ejecutan por personas en tres momentos: al cierre de cada bloque (las pruebas humanas), antes del primer despliegue a producción (las pruebas de aceptación con el dueño), y después de cada despliegue, en una pasada de solo lectura. Cada ejecución que falla reinyecta un requerimiento al bucle como pendiente correctivo. Forma: rutina de cada pendiente; después, ejecución humana por ciclo. Tamaño: obligatorio en todo proyecto con usuarios: el caso de prueba manual es la única prueba que no escribe ni corre el modelo.

Para qué sirve

El método tiene pruebas automáticas de sobra: el test en rojo, la regresión, la punta a punta en tres escalas. Todas las escribe y las corre el modelo, y todas prueban lo que el modelo entendió. Falta la prueba que hace una persona con sus propios ojos y sus propias manos, siguiendo un guion escrito, y que encuentra lo que ningún test encuentra: el botón que está donde no debe, el mensaje que no se entiende, el flujo que técnicamente anda y humanamente no sirve. La vista humana y las pruebas humanas ya estaban en la línea de tiempo; lo que faltaba era que tuvieran guion, y que el guion lo escribiera el mismo que construyó la funcionalidad, en el mismo momento, a partir de los criterios de aceptación del pendiente. Sin guion, la prueba humana es "jugá un rato con el sistema", y lo que se encuentra depende del humor del día. Con guion, se ejecuta igual cada vez, se registra qué pasó, y lo que falla vuelve al bucle como requerimiento. Es el cierre del circuito que el gráfico del proceso muestra: la ejecución manual de los casos de prueba reinyecta requerimientos al desarrollo.

Un caso de prueba manual tiene siempre la misma forma: un identificador; el pendiente que lo origina; la precondición (qué tiene que existir antes: un paciente, un turno de ayer); los pasos, numerados, cada uno con lo que la persona hace y lo que tiene que ver; el resultado esperado al final, incluido el efecto en el backend que una persona puede verificar (un registro que aparece, un mensaje en la bandeja falsa); los datos de prueba a usar; y el espacio para el resultado de cada ejecución: fecha, quién, pasó o falló, observación.

Si sos principiante. Un caso de prueba manual es una receta para que una persona pruebe una funcionalidad: qué preparar, qué hacer paso por paso, y qué tiene que pasar en cada paso. Se escribe para que cualquiera la siga igual, sin saber cómo está hecho el sistema. Ejecutar un caso es seguir la receta y anotar si pasó o falló. Precondición es lo que tiene que existir antes de empezar. Y reinyectar quiere decir que lo que la persona encontró mal vuelve a la lista de pendientes como un pedido nuevo, con sus palabras.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• El pendiente que se está cerrando, con sus criterios de aceptación "dado, cuando, entonces" (peldaño 5): son la materia prima del caso.
• El entorno de prueba con datos, para que los pasos se puedan seguir de verdad.
• Quién va a ejecutar los casos (el dueño, un usuario de confianza) y cuándo (cierre de bloque, aceptación, después de cada despliegue).

2. Prompts

Rutina de cada pendiente (va en el contrato de convivencia):

Qué le estoy pidiendo: que el caso salga de los criterios de aceptación (así prueba lo que se pidió, no lo que el modelo entendió); que esté escrito para alguien que no sabe cómo funciona el sistema, que es la diferencia entre un caso de prueba y una nota técnica; que incluya el efecto en el backend verificable por una persona, para que la prueba manual también mire del otro lado de la pantalla; que los casos se mantengan en el mismo commit, igual que la documentación; y que el modelo nunca los ejecute, porque ejecutados por el modelo son un test más, y la gracia es que los ejecute una persona.

Para una ejecución (cierre de bloque, aceptación, después de un despliegue):

Qué le estoy pidiendo: la reinyección hecha operativa: cada fallo humano es un pendiente correctivo, con las palabras de la persona (no las del modelo) como reproducción, y colgado del árbol; la comparación con la ejecución anterior, que es lo que te dice si el sistema mejora o se degrada entre bloques; y la distinción entre "el caso está mal escrito" y "el sistema está mal", que son dos pendientes distintos.

3. Resultado esperado

• docs/MANUAL_TESTS.md con un caso por flujo tocado por cada pendiente cerrado, en el formato, escrito para una persona.
• Las ejecuciones registradas, con fecha y quién, en cada ciclo.
• Un pendiente correctivo por cada fallo y por cada observación.
• La rutina en el contrato.

4. Verificación de completitud (la hacés vos, sin leer código)

• Tomá un caso al azar y seguilo vos en el entorno de prueba sin preguntarle nada al agente: ¿pudiste? Si tuviste que preguntar, el caso no está escrito para una persona.
• ¿Cada pendiente cerrado que toca una pantalla tiene su caso? Pedile la lista de pendientes sin caso.
• ¿El caso dice qué efecto verificar del otro lado de la pantalla, y cómo lo verifica una persona?
• ¿La última ejecución tiene fecha y nombre en cada caso? ¿Hay alguno "pasó" sin fecha?
• ¿Cada fallo de la última ejecución tiene su pendiente, con las palabras de la persona?

5. Señales de alarma

• El agente marcó los casos como ejecutados. Los ejecutó él, que es lo mismo que no ejecutarlos.
• Los casos son copias del test automático en prosa. Un caso manual tiene que mirar lo que el test no mira: lo que se ve, lo que se entiende, lo que molesta.
• Todos los casos pasan en todas las ejecuciones. Las personas encuentran cosas siempre; si no encuentran nada, no están siguiendo el guion o el guion no pide mirar.
• Los fallos se "arreglan" en el momento, sin pendiente. Se pierden las palabras de la persona y el rastro de qué se repitió.

Peldaño 11 — Simetría entre productor y consumidor, y el registro de anti-patrones (contrato del peldaño)

Tramo: bucle. Cuándo: con cada pendiente que toca un contrato entre dos partes del sistema. El mapa de contratos se construye al abrir el segundo bloque funcional, cuando ya hay pantalla y servidor. El registro de anti-patrones crece cada vez que algo se rompe por segunda vez. Forma: automática dentro del bucle; más un archivo que crece con cada golpe. Tamaño: la simetría es obligatoria siempre; el mapa productor/consumidor es opcional en un proyecto de un solo módulo, y obligatorio apenas hay una pantalla y un servidor separados.

Para qué sirve

Cuando cambiás una punta (el servidor, el robot, el esquema de la base), hacé que la otra punta (la pantalla, el contador, el consumidor) cambie en el mismo commit. Si no, tarde o temprano divergen, y el usuario ve un número de un lado y otro número del otro Ref. 26. Y los errores que ya pagaste una vez, anotalos para no pagarlos dos veces Ref. 2.

El principio general detrás, que impuse en la Obra Social y que vale para todo sistema Ref. 27: toda lista tiene un solo dueño. Las columnas de una tabla, los estados posibles de una orden, las causas por las que algo espera: las define una sola parte del sistema (el productor) y todas las demás las leen de ahí. En cuanto hay dos copias de la misma lista, una está desactualizada; solo falta saber cuál. El árbol semántico del peldaño 2 es el primer lugar donde esas listas se declaran: los estados de una entidad están ahí, y el código tiene que leerlos de una sola fuente.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• Un mapa de qué partes del sistema consumen qué: qué pantallas leen qué servicios, qué procesos escriben qué tablas. Si no existe, el primer prompt lo construye.
• El registro de anti-patrones docs/GOTCHAS.md, aunque esté vacío.

2. Prompts

Para construir el mapa (una vez):

Qué le estoy pidiendo: el inventario de contratos con sus dos lados, y la cláusula de completitud en su forma para este peldaño: lo que no se ve se declara, no se omite. Un mapa con agujeros escondidos es peor que ningún mapa.

Rutina (va en el contrato de convivencia):

Qué le estoy pidiendo: la simetría como reflejo (buscar el otro lado antes de cerrar), la regla de la lista con un solo dueño, y que el mapa se mantenga solo a medida que se usa.

Cuando algo se rompe por segunda vez:

Qué le estoy pidiendo: el formato fijo de un anti-patrón (olor, causa raíz, arreglo, detección temprana) y, sobre todo, la verificación automática: un anti-patrón anotado y no automatizado se va a repetir cuando cambie la persona o la sesión.

3. Resultado esperado

• docs/PRODUCER_CONSUMER_MAP.md: la lista de contratos con productor y consumidores.
• En cada commit que toca un contrato: los consumidores actualizados, nombrados en el mensaje.
• docs/GOTCHAS.md: una entrada por anti-patrón, con las cuatro partes (olor, causa raíz, arreglo, cómo detectarlo antes), y la fecha de la primera vez.

4. Verificación de completitud

• Elegí un contrato del mapa y pedile al agente que te muestre dónde lo lee cada consumidor. Si alguno tiene su propia copia de la lista, hay deuda.
• ¿Hay un número que se muestre en dos pantallas distintas? Compará: ¿dan igual?
• ¿Cada entrada de GOTCHAS tiene las cuatro partes?
• ¿Se repitió un error que ya estaba en GOTCHAS? Si sí, falta la verificación automática.

5. Señales de alarma

• El mismo valor aparece escrito a mano en más de un archivo ("PENDIENTE", "APROBADA" en el servidor y en la pantalla). Dos copias; una va a divergir.
• Un cambio al servidor se cerró con el test del servidor en verde y nadie tocó la pantalla.
• GOTCHAS tiene entradas sin la parte "cómo detectarlo antes". Son anécdotas, no anti-patrones.

Peldaño 12 — Verificación honesta y reporte proporcional (contrato del peldaño)

Tramo: bucle. Cuándo: en cada reporte, de cada pendiente, durante todo el proyecto. Es la forma que tiene que tener todo lo que el agente te dice. Forma: rutina; es la forma que debe tener cada reporte del agente. Tamaño: obligatorio en todo proyecto, sin excepciones. No cuesta nada y es lo que le permite al dueño no leer código.

Para qué sirve

Si no vas a leer código, el reporte del agente tiene que ser confiable. No optimista, no "completo en apariencia": confiable. Esto es lo genuinamente nuevo del método: el autor del código fabrica también la evidencia, y lo hace con la misma seguridad en la voz cuando está bien y cuando está mal. Por eso la evidencia tiene que probarse a sí misma, y el reporte tiene que separar lo verificado de lo creído. La regla la escribí en junio Ref. 8, y la volví a necesitar en octubre, cuando un error de autenticación fue reportado con la leyenda "success" Ref. 43.

Entendé por qué el modelo tiende a reportar de más. No es mala fe: es que fue entrenado para ser útil y completo, y un reporte que dice "esto no lo pude verificar" se siente menos útil que uno que dice "listo". Entonces pedile explícitamente las malas noticias, los puntos ciegos y lo que no hizo. Si no se lo pedís, no te lo da, no porque lo oculte sino porque no lo considera parte de la respuesta.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• El trabajo hecho y el pendiente que lo pedía.
• El contrato de convivencia (peldaño 1), que ya prohíbe anunciar lo no hecho.

2. Prompts

Rutina (va en el contrato de convivencia; se aplica en cada reporte):

Qué le estoy pidiendo, cláusula por cláusula: los tres bloques, que son la estructura que vuelve honesto un reporte (lo verificado con su prueba, lo creído con la razón de por qué no se probó, lo que no puede ver); la cobertura ítem por ítem, para que nada "se olvide"; la prueba al lado de cada afirmación; la prohibición del "listo" a secas; y las malas noticias primero, porque el modelo tiende a dejarlas para el final o para nunca.

Ante un "sigue roto" tuyo:

Qué le estoy pidiendo: que ante un "sigue roto" no vuelva a diagnosticar de cero sino que primero compare versiones. La mitad de los "sigue roto" son arreglos que están en el repositorio pero no en el lugar donde vos mirás Ref. 45.

3. Resultado esperado

Cada reporte del agente con:

• Los tres bloques (verificado / creído / puntos ciegos), aunque alguno esté vacío.
• Una línea por cada ítem pedido, con su estado.
• Para cada "verificado": el comando y la salida, o el test y su resultado, o el número y su medidor.
• Lo que salió mal, al principio y no al final.

4. Verificación de completitud

• ¿Están los tres bloques? Si "creído" y "puntos ciegos" están siempre vacíos, el agente no está siendo honesto: siempre hay algo que no vio.
• Elegí al azar una afirmación del bloque "verificado": ¿tiene su prueba al lado? ¿La podés reproducir?
• ¿Cubre cada ítem de lo que pediste, o hay uno que "se olvidó"?
• ¿Las malas noticias están al principio?
• ¿Dijo "listo" a secas alguna vez? Es una violación del contrato.

5. Señales de alarma

• Diez reportes seguidos sin ningún punto ciego. Nadie ve todo; el bloque está vacío por costumbre, no por verdad.
• El bloque "verificado" tiene frases como "debería funcionar". Es "creído" disfrazado.
• El reporte es más largo que el cambio. Un reporte proporcional dice lo que hay que decir; uno inflado está tapando algo con volumen.

Peldaño 13 — La auditoría periódica como insumo del plan (contrato del peldaño)

Tramo: salida a producción. Cuándo: obligatoria antes del primer despliegue a producción; abre el tramo de salida. Después, en operación, cada uno o dos meses según el ritmo de cambio, y al cierre de cada etapa grande. Forma: un solo tiro largo, idealmente a un agente distinto del que construye. Tamaño: obligatorio antes del primer despliegue a producción, en cualquier proyecto; después, proporcional al ritmo de cambio (un sistema que cambia todas las semanas se audita cada mes; uno estable, cada seis).

Para qué sirve

Mirá el sistema entero con ojos frescos cada tanto, y convertí lo que veas en pendientes. La auditoría no es un informe que se archiva: es plan. Evita la contraseña escrita en el código que nadie había visto, las consultas que leen tablas enteras Ref. 18, la vulnerabilidad conocida en una dependencia, el componente de miles de líneas Ref. 41. Y es la independencia del control de calidad llevada un paso más adentro: el que audita no es el que construyó.

Sobre la independencia: no hace falta otra empresa ni otra herramienta. Alcanza con otra sesión, con otro archivo de instrucciones, que no haya participado de la construcción. Lo que buscás es que el auditor no comparta los supuestos del constructor. Un modelo que construyó un módulo "sabe" que la contraseña hardcodeada era provisoria; un modelo que lo ve por primera vez la reporta como lo que es. Así se detectaron dos puertas de administrador que el constructor había dejado en un día Ref. 40.

Si podés elegir, que además sea un modelo distinto del que construyó, no solo otra sesión del mismo: un estudio de 2026 midió que una sesión limpia con un modelo distinto encuentra más errores que dos sesiones del mismo modelo (arXiv 2610.01471). No es una compuerta dura, porque a veces el modelo del constructor es el único disponible; es una preferencia que vale la pena ejercer cuando se puede, y cuanto más crítico el sistema, más vale ejercerla.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• El repositorio completo, en solo lectura.
• La producción o el entorno de prueba, en solo lectura (base de datos, logs).
• La auditoría anterior, si hubo, para medir qué cambió.
• El alcance: integridad, seguridad, rendimiento, calidad de código, o todo.
• docs/PENDING.md con los pendientes cerrados del último ciclo y sus recibos, para que el auditor elija cuáles reproducir.

2. Prompts

Inicial (a un agente distinto del constructor, si se puede):

Qué le estoy pidiendo, cláusula por cláusula: solo lectura (el auditor no arregla; propone); la cláusula de completitud en su forma para auditar: lo que no se pudo verificar se declara, no se aprueba por omisión; todo el código y no una muestra, porque los hallazgos graves suelen estar donde nadie mira; la reproducción literal de dos o tres recibos, para que la auditoría verifique evidencia, no solo la lea (esta es la cláusula que cierra el hueco de D-033: un rojo contado no es un rojo auditado); cada hallazgo con ubicación, riesgo, evidencia y prioridad, para que sea accionable sin releer el informe; notas por dimensión, para comparar con la auditoría anterior; y los P0 ya convertidos en pendientes propuestos.

De cierre (al constructor):

Qué le estoy pidiendo: que la auditoría se convierta en pendientes (si no, es un informe que se archiva), y que el desacuerdo sea explícito y con evidencia, no silencioso.

3. Resultado esperado

• docs/AUDIT_[fecha].md con: alcance, qué se pudo verificar y qué no (y por qué), los hallazgos con ubicación, riesgo, evidencia y prioridad, una nota por dimensión, el resultado de reproducir dos o tres recibos del último ciclo, y la lista de pendientes propuestos.
• En docs/PENDING.md: un pendiente por cada P0 y P1, citando el hallazgo.

4. Verificación de completitud

• ¿El informe dice qué NO pudo verificar? Si dice que verificó todo, desconfiá.
• Elegí dos hallazgos: ¿tienen archivo y línea, y una evidencia que podés reproducir?
• ¿El informe dice qué recibos reprodujo, con el comando y el resultado, o solo dice que los leyó?
• ¿Cada P0 tiene su pendiente abierto antes de dar la auditoría por cerrada?
• ¿Las notas por dimensión se van a poder comparar con la auditoría anterior?
• ¿Auditó el mismo agente que construyó? Si es así, pedí una segunda mirada sobre los P0.

5. Señales de alarma

• La auditoría no encontró ningún P0. En un sistema de más de tres meses, casi nunca es verdad; más probable es que el alcance fue chico o que el auditor compartía los supuestos.
• Los hallazgos no tienen línea de archivo. Son opiniones, no hallazgos.
• El informe dice que los recibos "se revisaron" sin mostrar el comando que corrió ni su salida. Un recibo leído y uno reproducido no son lo mismo, y solo el segundo cierra la objeción de D-033.
• Pasaron dos semanas y los P0 siguen sin pendiente. La auditoría se archivó.

Peldaño 14 — Fail-closed, candados y cero daño silencioso (contrato del peldaño)

Tramo: salida a producción. Cuándo: en el tramo de salida a producción, ANTES de construir cualquier funcionalidad que cobre, envíe, apruebe o borre; se revisa con cada acción nueva con consecuencias. Las automatizaciones nuevas arrancan en modo de ensayo y se habilitan después de mirar su registro unos días. Forma: conversación: el agente lista las acciones con consecuencia, vos confirmás cuáles llevan candado y de qué tipo. Tamaño: obligatorio apenas el sistema hace algo irreversible (cobrar, enviar, borrar, aprobar). Un sistema de solo lectura puede saltearlo; en el momento en que gana su primer botón que actúa sobre el mundo, este peldaño pasa a ser el más importante.

Para qué sirve

Hacé que el sistema, ante una duda o un fallo, NO actúe, y que lo diga. Suena obvio y es lo contrario de lo que el software hace por defecto, que ante la duda sigue adelante. Evita el doble cobro, la aprobación automática sin pasar por un humano, el git add -A que sube una credencial, y el borrado de datos del cliente. Los candados que puse en la Obra Social son el modelo: el botón de pánico con doble seguro, el aprobador automático en modo de ensayo, el vigía con guardas Ref. 28; y el reflejo de que un fallo deje una fila sin su botón en vez de romper el listado entero Ref. 25.

El principio tiene nombre, "fail-closed", y viene de la seguridad física: una puerta de seguridad que queda cerrada cuando se corta la luz. Lo contrario, "fail-open", es la puerta que se abre. En software la mayoría de las cosas son fail-open por defecto: si la validación falla, el código sigue; si el servicio no responde, se asume que está todo bien. El método invierte el defecto: ante la duda, no. Y se aplica tanto al sistema como al agente que lo opera.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• Relevamiento de acciones con consecuencia, nombrado así en forma genérica: qué hace el sistema que cobra, envía, aprueba, borra, o le avisa a alguien de afuera; qué pasa si se hace dos veces; qué pasa si se hace mal; cómo se deshace. Lo sabe el negocio; el agente evalúa si la lista está completa y pregunta. El árbol semántico ayuda: cada proceso con consecuencia está ahí.
• Qué acciones puede hacer el agente mismo sobre el sistema (si está embebido).

2. Prompts

Inicial:

Qué le estoy pidiendo: el cruce entre lo que el negocio dijo y lo que el código hace (ahí aparecen las acciones que nadie recordaba); la cláusula de completitud en su forma para este peldaño: las diferencias entre las dos listas se preguntan, no se resuelven; para cada acción, reversibilidad, candado y camino de vuelta; y la regla general del fail-closed escrita en el prompt, para que quede en la tabla y en el código.

De cierre:

Qué le estoy pidiendo: el test por candado probado en rojo (sin el candado, la acción ocurría; con el candado, no), que es el peldaño 8 aplicado a la seguridad; la tabla final; y la regla del modo de ensayo para toda automatización nueva, que es lo que permite ver qué habría hecho antes de dejarla hacer.

3. Resultado esperado

• docs/LOCKS.md: una fila por acción con consecuencia: qué hace, si es reversible, el candado, el camino de vuelta, quién lo aprobó y cuándo.
• Un test por candado, probado en rojo, que verifica que ante la duda la acción no ocurre.
• Las automatizaciones nuevas arrancando en modo de ensayo, con el registro de "habría hecho".
• Si el agente está embebido: sus permisos escritos (qué puede leer, qué puede cambiar, qué requiere aprobación).

4. Verificación de completitud

• ¿Cada acción que cobra, envía, aprueba o borra está en la tabla? Pensá una que no esté y preguntá.
• ¿Cada candado tiene su test en rojo? ("Sin el candado, la acción ocurría; con el candado, no.")
• ¿Toda acción irreversible tiene camino de vuelta escrito? Si no lo tiene, necesita doble seguro.
• ¿Las automatizaciones nuevas arrancaron en modo de ensayo? ¿Viste el registro de "habría hecho" antes de habilitarlas?
• ¿Qué pasa si el agente embebido intenta algo fuera de sus permisos? Pedile que lo intente y te muestre el rechazo en el log.

5. Señales de alarma

• Una automatización pasó de "no existe" a "corre sola" sin un período de modo de ensayo.
• El log no tiene ninguna entrada de "acción no ejecutada por duda". O el sistema nunca duda (imposible) o cuando duda sigue adelante.
• Un candado se puede saltear con un parámetro "para pruebas". Ese parámetro va a quedar puesto en producción.

Peldaño 15 — Integración continua, entornos, secretos y despliegue como parte del producto (contrato del peldaño)

Tramo: salida a producción. Cuándo: la cadena de integración y el despliegue al entorno de prueba se montan en el peldaño

4. El cierre hacia producción —entorno real, secretos en el servidor, promoción, vuelta atrás

probada, candado contra secretos— se hace en el tramo de salida, después de la auditoría y de los candados. La rutina de cada despliegue se aplica en toda la operación. Forma: un solo tiro para montarlo; rutina para cada despliegue. Tamaño: obligatorio en todo proyecto con usuarios. En uno chico, "integración continua" puede ser una sola acción de GitHub y "entornos" pueden ser dos carpetas en el mismo servidor; lo que no se negocia es que los tests corran solos, que la configuración no esté en el repositorio, y que haya vuelta atrás.

Para qué sirve

Hacé que llegar a producción sea un paquete reproducible: los tests corren UNA vez, la configuración vive fuera del repositorio, y los secretos no andan dando vueltas. Evita los tests corridos tres veces por commit y la cuota fundida Ref. 39, el despliegue endurecido a golpe de pendientes por haberlo descubierto tarde Ref. 32, y los secretos pegados en el chat Ref. 42.

Sobre los secretos hay una regla que adoptá como reflejo, sin excepciones: un secreto que se vio en un chat, en un log o en un commit ya no es un secreto. No importa si "nadie lo vio" o si "se borró después". Se rota. La rotación cuesta diez minutos; averiguar si alguien lo usó es imposible.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• Relevamiento de entornos y accesos, en forma genérica: qué entornos hay (prueba, producción), dónde corren, quién tiene acceso, cómo se promueve algo de uno a otro, qué secretos existen y dónde viven hoy, cuánta cuota de integración continua hay. El agente evalúa si alcanza y pregunta.
• El esqueleto con su integración continua y su despliegue a prueba (peldaño 4).

2. Prompts

Inicial:

Qué le estoy pidiendo, cláusula por cláusula: los accesos antes de empezar; los tests una sola vez por commit (correrlos tres veces es lo que fundió la cuota); el despliegue que solo empaqueta; la configuración fuera del repositorio; la promoción como procedimiento repetible; la vuelta atrás probada (una vuelta atrás que nunca se probó no existe) con su plan de datos, porque una migración de esquema o de datos no se deshace revirtiendo el commit; el candado contra secretos en los commits; y la documentación para una persona, que es el peldaño 20 aplicado a la infraestructura.

Rutina de cada despliegue:

Qué le estoy pidiendo: las tres condiciones previas (prueba en verde con la misma versión, vuelta atrás lista, cambios de configuración anunciados) y las dos pruebas posteriores (la versión corriendo y una verificación de punta a punta sin escribir nada).

Si un secreto apareció en el chat o en un commit:

Qué le estoy pidiendo: rotación inmediata, inventario de dónde más estaba, y la verificación que lo habría detectado, para que la próxima vez no llegue al chat.

3. Resultado esperado

• La integración continua corriendo una sola vez por commit, con el enlace a una corrida.
• El despliegue que espera a la integración y solo empaqueta; medido: cuánto tarda antes y después.
• La configuración fuera del repositorio; en el repo, solo un ejemplo sin valores.
• docs/DEPLOYMENT.md: cómo desplegar, promover y volver atrás, paso a paso, para una persona.
• La vuelta atrás probada al menos una vez, con su evidencia.
• La verificación anti-secretos activa (un intento de subir uno, rechazado).
• Un registro de la cuota de integración continua consumida por mes.

4. Verificación de completitud

• ¿Cuántas veces corre la batería por cada commit? Tiene que ser una. Pedí el enlace.
• ¿Hay algún valor real de configuración (una clave, una contraseña, una URL interna) en el repositorio? Pedile al agente que busque y te muestre la búsqueda vacía.
• ¿Podrías seguir docs/DEPLOYMENT.md vos solo, sin el agente? Leelo con esa pregunta.
• ¿La vuelta atrás se probó? ¿Cuándo? ¿Qué evidencia hay?
• Si hubo una migración de esquema o de datos: ¿hay un plan escrito para deshacerla o compensarla, además de la vuelta atrás del código?
• ¿Se pegó algún secreto en el chat durante el proyecto? Si sí, ¿se rotó?
• ¿Sabés cuánta cuota de integración continua queda este mes?

5. Señales de alarma

• El despliegue a producción se hace "a mano, rápido, porque es un cambio chico". Los cambios chicos son los que rompen producción, porque nadie los prueba.
• El archivo de ejemplo de la configuración tiene valores que parecen reales. Probablemente lo sean.
• Nadie sabe decir cuándo fue la última vez que se probó la vuelta atrás.
• Una migración cambió datos o esquema y "la vuelta atrás" de la que se habla es solo la del código. Para esa migración, no hay vuelta atrás: hay, en el mejor de los casos, un plan para compensarla.

Peldaño 16 — Observabilidad y trazabilidad totales, con nivel configurable (contrato del peldaño)

Tramo: salida a producción. Cuándo: en la fase de salida a producción, después del 15 (ya hay cadena de despliegue y configuración por entorno) y antes de las pruebas de rendimiento (19), porque sin observabilidad las pruebas de rendimiento no dicen qué se rompió. En un legado, el nivel mínimo (registros estructurados con nivel configurable y un identificador de correlación) entra en el cinturón de seguridad (N4); el nivel completo, acá. La regla de "todo módulo nuevo registra y propaga" rige durante toda la operación. Forma: un solo tiro; el agente arma y demuestra; vos leés una traza real. Tamaño: obligatorio en su nivel mínimo en todo proyecto que vaya a tener usuarios; completo en cualquier proyecto con consecuencias.

Para qué sirve

Cuando algo falle en producción, y va a fallar, quiero poder seguir una acción desde la pantalla hasta la base de datos y hasta cada llamada externa, con un solo identificador, sin abrir el código y sin pedirle al agente que "revise". Y quiero poder subir el nivel de detalle de los registros en producción, en un minuto, sin volver a desplegar, y bajarlo después. Eso es observabilidad: ver lo que el sistema hace. Y lo segundo es trazabilidad: que toda acción con consecuencia (cobró, envió, borró, aprobó) deje un rastro de quién, cuándo, qué, desde dónde y con qué resultado, en un registro que la aplicación no puede editar. Sin esto, el agente residente del peldaño 23 opera a ciegas, el monitoreo de los peldaños 21 y 22 no tiene de qué alimentarse, y cada incidente se diagnostica con hipótesis en vez de con evidencia. El turno huérfano que siguió vivo una hora cuarenta y tres se encontró por el log, no por el código Ref. 16; y el agente residente arrancó, justamente, leyendo logs Ref. 13.

"Nivel configurable" es la cláusula que distingue esto de "poner logs": el nivel (error, aviso, información, depuración, traza) se cambia por configuración en el servidor, por entorno, sin tocar código ni desplegar, y producción corre en información salvo cuando se está investigando algo.

Si sos principiante. Un registro (log) es una línea que el sistema escribe cada vez que hace algo: "10:42:13, módulo agenda, usuario recepcion1, turno 17 cancelado". Estructurado quiere decir que todas las líneas tienen las mismas partes en el mismo orden, para que se puedan buscar por máquina. El nivel es cuánto detalle se escribe: en "error" solo lo que falló; en "traza", cada paso. El identificador de correlación es un número único que se le da a cada acción cuando empieza (apretaste "cancelar") y que viaja pegado a todo lo que esa acción provoca (la consulta a la base, el mensaje al paciente), así después se busca ese número y aparece la historia completa. Y la auditoría es una lista que no se puede editar de las acciones importantes: quién hizo qué y cuándo.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• La cadena de despliegue y la configuración por entorno (peldaño 15): el nivel se configura ahí.
• La tabla de candados (peldaño 14): cada acción con consecuencia es una entrada de la auditoría.
• El relevamiento inicial con los datos personales marcados: los registros no pueden contenerlos.
• Dónde van a vivir los registros y las métricas (un archivo rotado, un servicio): lo decidís vos.

2. Prompts

Inicial:

Qué le estoy pidiendo: las cinco piezas, y dos demostraciones que son la evidencia del peldaño: un identificador real seguido por todas las capas (si no lo puede mostrar, la propagación está rota en algún lado) y el nivel cambiando sin desplegar (si hay que desplegar, no es configurable). La auditoría de acciones con consecuencia tiene que ser inmutable desde la aplicación, porque un rastro que la aplicación puede borrar no es un rastro. Y el enmascaramiento de datos personales va en el mismo prompt porque los registros son el lugar donde más datos personales se filtran sin que nadie lo decida.

Rutina (va en el contrato de convivencia):

Qué le estoy pidiendo: que la observabilidad no se degrade con cada módulo nuevo, que es lo que pasa siempre si no es regla: el módulo del mes tres no registra nada y es justo el que falla.

3. Resultado esperado

• Registros estructurados con nivel configurable por entorno, cambiados sin desplegar.
• Un identificador de correlación en cada registro, propagado de la pantalla a la base y a las llamadas externas.
• Un registro de auditoría inmutable de las acciones con consecuencia.
• Puntos o archivos de salud y métricas, documentados.
• Ningún dato personal en los registros.
• docs/OBSERVABILITY.md y la rutina en el contrato.

4. Verificación de completitud (la hacés vos, sin leer código)

• Pedile un identificador de un pedido real y buscalo vos en los registros: ¿aparece en la pantalla, en el backend, en la base y en la llamada externa, si la hubo?
• Subí el nivel a depuración en el entorno de prueba, hacé una acción, mirá los registros, bajalo. ¿Tuviste que desplegar? Entonces no está subido.
• Buscá un nombre o un teléfono de prueba en los registros: no tiene que estar.
• Hacé una acción con consecuencia en prueba (cancelar, enviar a la bandeja falsa): ¿quedó en la auditoría con quién, cuándo, qué y resultado?
• ¿docs/OBSERVABILITY.md te alcanza para encontrar un registro vos solo a las tres de la mañana?

5. Señales de alarma

• El agente muestra "logs" pero cada módulo escribe en un formato distinto. No es estructurado; nadie va a poder buscarlos.
• El identificador aparece en el backend pero no en las llamadas externas o en las tareas programadas. Son justo los lugares donde se pierden los incidentes.
• El nivel de producción quedó en depuración "por ahora". Se llena el disco y se filtran datos.
• La auditoría de acciones con consecuencia vive en la misma tabla que el resto de los datos y la aplicación puede borrarla.

Peldaño 17 — Optimización de la capa de persistencia, medida antes y después (contrato del peldaño)

Tramo: salida a producción. Cuándo: en la fase de salida a producción, después del 16 (hace falta ver las consultas para medirlas) y antes del 19 (las pruebas de rendimiento se corren sobre la persistencia ya optimizada; si no, miden el problema que ya se conocía). Se repite cuando un bloque agrega una tabla grande o cambia un flujo crítico, y cuando el monitoreo (21) muestra una consulta fuera de rango. En un legado, las mediciones salen de N6 y la mayor parte de lo que se encuentra se paga "al tocar", salvo lo que ya está fuera de rango. Forma: dos tiros: medir y proponer; aplicar con antes y después. Tamaño: proporcional: en un proyecto chico, los índices de las consultas reales y el fin de los bucles N+1; en uno con consecuencias, completo, con presupuestos por camino.

Para qué sirve

La capa de persistencia es donde los sistemas se mueren despacio: funcionan bien con cien registros, aceptablemente con diez mil, y a los cien mil cada pantalla tarda veinte segundos, y nadie sabe cuándo empezó. Este peldaño existe para que eso se decida con números y antes de producción, no con quejas y después. Y para que se decida con el método del peldaño 7: cada consulta que el sistema hace se cuenta y se cronometra con un medidor que tiene test, se cambia lo que los números dicen, y se vuelve a medir sobre los mismos datos. La primera auditoría de consultas sin índice sobre un sistema vivo Ref. 18 y el presupuesto de consultas apretado a lo medido Ref. 37 son el origen de este peldaño; la decisión de la interfaz asincrónica desde la línea uno Ref. 15, su antecedente en el arranque.

Lo que no es: no es "reescribir el acceso a datos", ni elegir otro motor. Eso lo decidió el peldaño 3. Es ajustar lo que hay (índices, paginación, lotes, retención, tamaño del pool) a partir de lo que las consultas reales hacen.

Si sos principiante. La capa de persistencia es la parte del sistema que guarda y lee los datos, casi siempre una base de datos. Un índice es como el índice de un libro: sin él, para encontrar un turno la base lee la tabla entera (eso es un full scan); con él, va directo. Un bucle N+1 es un error muy común: para mostrar cien turnos, el sistema hace una consulta para la lista y después cien consultas más, una por turno, en vez de una sola. Paginación es mostrar de a veinte en vez de todo junto. Retención es cuánto tiempo se guarda cada dato antes de archivarlo o borrarlo. Y el pool de conexiones es la cantidad de "líneas abiertas" que el sistema tiene con la base al mismo tiempo. Nada de esto requiere que leas código: requiere que mires números antes y después.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• El dimensionamiento y la volumetría (peldaño 3, o N6 en un legado): los volúmenes a los que hay que medir.
• El mapa productor-consumidor (peldaño 11): qué consume cada tabla.
• La observabilidad (16): cada consulta visible con su tiempo.
• El entorno de prueba cargado con datos al volumen esperado.

2. Prompts

Inicial (medir y proponer):

Qué le estoy pidiendo: medir con el método del peldaño 7 (medidor con test, auditado en dos direcciones, número con comando) antes de proponer; proponer consulta por consulta, con la ganancia y el riesgo, y con los consumidores del mapa que cada cambio toca (un índice nuevo no toca a nadie; una retención por tabla toca a todos los que leen esa tabla); y no cambiar nada hasta que yo apruebe, porque la optimización es el lugar donde más se "mejora" lo que nadie pidió.

De cierre (aplicar con antes y después):

Qué le estoy pidiendo: un commit por cambio, para que el antes y el después sean atribuibles; el mismo medidor sobre los mismos datos (si cambian los datos, el número no dice nada); el presupuesto con test, que es lo que impide que el bucle N+1 vuelva en tres meses; y la simetría del peldaño 11 aplicada a la persistencia.

3. Resultado esperado

• Los medidores de consultas en el repositorio, con test.
• docs/PERSISTENCE.md con la tabla de antes y después por cambio, los presupuestos por camino y la retención por tabla.
• Los índices, la paginación, los lotes y la retención aplicados, un commit cada uno, con la regresión y la punta a punta en verde.
• Un test por presupuesto que falla si se supera.

4. Verificación de completitud

• Corré vos un medidor antes y después (el agente te da los dos comandos): ¿coinciden con la tabla?
• ¿Hay alguna consulta que lea una tabla entera en un flujo crítico? ¿Por qué quedó?
• ¿Cada tabla tiene una política de retención escrita, aunque sea "para siempre"?
• ¿Los presupuestos tienen test? Pedile que suba uno a propósito y te muestre el rojo.
• ¿La pantalla más lenta, con los datos al volumen, tarda lo que el dimensionamiento esperaba?

5. Señales de alarma

• Las mediciones se hicieron con los datos de ejemplo del esqueleto. Todo es rápido con diez filas.
• El agente propone "migrar a otra base" o "reescribir la capa de datos". Eso es el peldaño 3, y si hay que volver a él es una decisión tuya, no una optimización.
• Mejoró el número pero la punta a punta de un flujo dejó de pasar. Un índice no rompe un flujo; una retención o una paginación sí: faltó un consumidor del mapa.
• No hay presupuestos. Sin presupuesto, la optimización dura hasta el próximo bloque.

Peldaño 18 — Escaneo y solución de vulnerabilidades, en la cadena y con calendario (contrato del peldaño)

Tramo: salida a producción. Cuándo: en la fase de salida a producción, después del 15 (el escaneo corre en la integración continua) y antes del primer despliegue: ningún P0 abierto se promueve. Después, en cada push, y con un calendario propio (semanal) aunque no haya pushes, porque las vulnerabilidades nuevas aparecen sin que vos cambies nada. En un legado, la primera corrida es parte de N3 (la dimensión de seguridad de la auditoría) y los hallazgos entran al backlog con su marca de velocidad. Forma: un solo tiro para montar y correr; después, automático, con un reporte que vos leés. Tamaño: obligatorio en todo proyecto que vaya a tener usuarios: el escaneo de dependencias y de secretos no se negocia; el análisis estático y la línea base de configuración, proporcionales.

Para qué sirve

La auditoría del peldaño 13 mira el sistema con ojos frescos cada tanto; este peldaño mira una sola cosa, la seguridad, todo el tiempo y por máquina. Son complementarios: la auditoría encuentra lo que requiere criterio (una puerta de administrador que nadie debería tener Ref. 40); el escaneo encuentra lo que requiere constancia (la dependencia que ayer no tenía una vulnerabilidad conocida y hoy sí Ref. 41). La primera auditoría de seguridad formal me convenció de que la seguridad es una rutina periódica y no una lista que se tilda una vez Ref. 23; este peldaño es esa rutina hecha máquina.

Y una regla que quiero escrita: una actualización de dependencia es un cambio, y entra por el bucle como cualquier otro. "Subí la versión para cerrar la vulnerabilidad" sin regresión ni punta a punta es la forma más común de romper producción un viernes.

Si sos principiante. Una vulnerabilidad es un defecto que alguien puede usar para entrar, robar datos o hacer que el sistema haga algo que no debería. Las hay de cuatro tipos que este peldaño busca por máquina. En las dependencias: las piezas de software de otros que tu sistema usa (hay bases públicas que listan cuáles tienen defectos conocidos, identificados con un número CVE). En el código: el análisis estático lee el código sin ejecutarlo buscando patrones peligrosos, como una inyección (que un usuario escriba en un formulario algo que la base interprete como una orden). En el historial: un secreto (una contraseña, una clave) que alguna vez se guardó en el repositorio sigue ahí aunque después se haya borrado. Y en la configuración: puertos abiertos que no hacían falta, contraseñas por defecto, cabeceras de seguridad (instrucciones que el servidor le manda al navegador para protegerlo) que faltan.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• La integración continua (peldaño 4 y 15), donde corre el escaneo.
• El relevamiento de entornos: qué servidor, qué contenedor, qué puertos, para la línea base de configuración.
• La auditoría anterior (13, o N3), para no reportar lo ya conocido.
• Tu criterio sobre qué es P0: lo que permite entrar, lo que expone datos personales, lo que permite cobrar o enviar sin control.

2. Prompts

Inicial (montar, correr, proponer):

Qué le estoy pidiendo: las cuatro capas de escaneo (dependencias, código, secretos en el historial, configuración), en la cadena y con calendario, porque las vulnerabilidades nuevas no esperan a tu próximo push; el informe con la forma del peldaño 13, con la cláusula de "no escaneado" en vez de "limpio"; el criterio de P0 dado por mí; y la prohibición de actualizar sin pasar por el bucle, que es la que evita el viernes roto.

De cierre (arreglar y convertir en compuerta):

Qué le estoy pidiendo: un pendiente por arreglo, con el rojo del peldaño 8 donde se puede (una vulnerabilidad arreglada sin test vuelve con el próximo refactor); el escaneo repetido como evidencia; y la conversión en compuerta, que es lo que hace que este peldaño siga vivo cuando nadie lo mira.

3. Resultado esperado

• El escaneo en cuatro capas corriendo en cada push y semanalmente.
• docs/SECURITY_[fecha].md con los hallazgos y lo no escaneado; docs/SECURITY.md con la política, el calendario, la compuerta y la cobertura.
• Los P0 y P1 arreglados, cada uno con su pendiente y su test donde aplica.
• La compuerta en docs/GATES.md.

4. Verificación de completitud

• Pedile el enlace a la última corrida del escaneo: ¿está en verde, y de qué fecha es?
• ¿El informe dice qué NO escaneó?
• ¿Cada P0 tiene su pendiente cerrado con evidencia, o abierto con fecha?
• Pedile que introduzca a propósito una dependencia con vulnerabilidad conocida en una rama: ¿la cadena se pone en rojo?
• ¿Sabés cuándo corre el próximo escaneo programado?

5. Señales de alarma

• El escaneo pasó limpio a la primera en un sistema con más de un mes. Casi nunca es verdad: falta una capa, o se escaneó solo la rama y no el historial.
• Se actualizaron diez dependencias en un commit "para cerrar los hallazgos". Ese commit no tiene antes ni después; es el viernes roto esperando.
• El escaneo está pero no es compuerta: produce informes que nadie lee.
• Hay un P0 "aceptado" sin pendiente ni fecha ni firma.

Peldaño 19 — Pruebas de rendimiento en volumen y punto de ruptura (contrato del peldaño)

Tramo: salida a producción. Cuándo: en la fase de salida a producción, después del 16 (sin observabilidad no se sabe qué se rompió) y del 17 (sobre la persistencia ya optimizada), y antes del primer despliegue a producción. Se repite antes de cada despliegue que cambie la arquitectura, la persistencia o un flujo crítico, y cuando el dimensionamiento cambia (se vende a otro cliente, se duplica el volumen). En un legado, se corre con los volúmenes medidos en N6, antes del primer despliegue posterior a la normalización. Forma: un solo tiro; el agente carga, mide y rompe; vos leés los números y el punto de ruptura. Tamaño: proporcional: en un proyecto chico, una corrida al volumen esperado y una al "por diez"; en uno con consecuencias, completo, con el punto de ruptura encontrado y los umbrales registrados para el monitoreo.

Para qué sirve

El peldaño 3 dimensionó con cuentas; este peldaño comprueba las cuentas con el sistema real corriendo. Quiero saber tres cosas antes de que entre el primer usuario: cómo se comporta el sistema al volumen que el negocio dijo (¿la pantalla más usada responde en lo que el dueño toleraría?), cómo se comporta al "por diez" (¿aguanta, o qué deja de aguantar primero?), y dónde se rompe: la carga exacta a la que algo cede, y qué es ese algo (las conexiones a la base, la memoria, una cola, un bloqueo). El punto de ruptura es el número más útil de todo el tramo, porque de él salen los umbrales de alerta del peldaño 21: una alerta puesta "a ojo" avisa tarde o avisa siempre; una alerta puesta debajo del punto de ruptura medido, con un margen, avisa cuando todavía hay tiempo. Los patrones de escala que saqué de un sistema en producción Ref. 12 y la batería que se moría por memoria y parecía un test fallido Ref. 44 son los dos antecedentes: el primero, de medir la carga real; el segundo, de que un punto de ruptura no encontrado a tiempo se disfraza de otra cosa.

Si sos principiante. Una prueba de carga es un programa que simula a muchos usuarios usando el sistema al mismo tiempo, para ver qué pasa. Rendimiento (throughput) es cuántas acciones por segundo aguanta. Latencia es cuánto tarda una acción en responder; se mira la mediana (la mitad de las acciones tardó menos que esto) y el percentil 95 (el 95 % tardó menos que esto; el 5 % restante son los usuarios que se quejan). El punto de ruptura es la cantidad de carga a la que algo deja de funcionar: no "se pone lento" sino "las conexiones a la base se agotaron" o "la memoria se llenó". Y un umbral es un número límite a partir del cual el monitoreo avisa.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• El dimensionamiento (peldaño 3 o N6): el volumen esperado y el "por diez".
• La observabilidad (16) encendida, para ver qué se rompe.
• La persistencia optimizada (17) con sus presupuestos.
• Un entorno de prueba parecido a producción en recursos, o la conciencia de en qué difiere.
• Los flujos críticos (los del árbol semántico, o los de la caracterización en un legado).

2. Prompts

Inicial (cargar, medir, romper):

Qué le estoy pidiendo: un script de carga que es un medidor más (vive en el repositorio y tiene test, porque un script de carga que no ejercita el flujo mide el aire); tres corridas (esperado, por diez, hasta romper); los números con comandos; la comparación con los presupuestos, la tolerancia del negocio y los supuestos del dimensionamiento, que es donde se descubre que el peldaño 3 se equivocó en algo; y nada de optimizar todavía, porque optimizar sin leer el diagnóstico es cambiar lo que no era.

De cierre (umbrales y pendientes):

Qué le estoy pidiendo: los umbrales de alerta derivados del punto de ruptura, que es el enganche con el peldaño 21; los cuellos de botella como pendientes con el número como criterio (así se cierran con evidencia y no con "ahora anda mejor"); y la prueba de carga como compuerta archivada, para que dentro de seis meses se pueda comparar.

3. Resultado esperado

• El script de carga en el repositorio, con test.
• docs/PERFORMANCE_[fecha].md con las tres corridas, los números, el punto de ruptura y el diagnóstico; docs/PERFORMANCE.md con los umbrales y la compuerta.
• Un pendiente por cuello de botella bajo el volumen decidido.
• La prueba de carga como compuerta antes de los despliegues que la requieren.

4. Verificación de completitud

• ¿La pantalla más usada, al volumen esperado, tarda menos que la tolerancia del dueño? Si no, hay un pendiente abierto con ese número.
• ¿El punto de ruptura dice qué se rompió y a qué carga, o dice "el sistema se puso lento"?
• ¿Los umbrales de docs/PERFORMANCE.md están debajo del punto de ruptura y encima del esperado?
• Corré vos el script al volumen esperado con el comando que te dio: ¿los números se parecen?
• ¿El entorno de prueba difiere de producción en recursos, y está anotado cómo?

5. Señales de alarma

• "Aguanta el por diez sin problemas" sin un punto de ruptura. Si no encontró dónde se rompe, no subió la carga lo suficiente.
• El script de carga pega a la API pero no pasa por la pantalla, en un sistema donde la pantalla es la que carga. Mide otra cosa.
• Los resultados son de una corrida en la máquina del agente, no en el entorno de prueba.
• Se arreglaron cuellos de botella durante la prueba, "ya que estaba". Ahora no sabés qué número corresponde a qué versión.

Peldaño 20 — Documentación viva y manuales que una persona puede seguir sin IA (contrato del peldaño)

Tramo: salida a producción. Cuándo: el manual de usuario crece con cada bloque funcional, al cierre, con las pantallas nuevas; alimentado por los pendientes cerrados, que son la documentación de lo hecho. Los tres manuales completos se generan en el tramo de salida a producción, después del 15, y la prueba con una persona que no programa se hace antes del primer despliegue. La rutina del mismo commit rige durante toda la operación. Forma: rutina; más un tiro largo cuando se generan los manuales. Tamaño: proporcional. Un sistema chico necesita, como mínimo, el manual de infraestructura y recuperación; el de usuario puede ser una página. Lo que no cambia: si la persona que lo construyó desaparece, otra tiene que poder seguir.

Para qué sirve

Hacé que el sistema se pueda usar, mantener y recuperar sin el agente y sin vos. Si el día que no hay agente no se puede desplegar, no está terminado. En el método clásico la documentación era cara y envejecía; acá regenerarla es gratis, así que la regla pasa a ser "en el mismo commit" y "reproducible a mano". Los manuales que escribí para la Obra Social con ese criterio son el modelo Ref. 24; y el archivo de proyecto que se volvió un historial de miles de líneas es el contraejemplo Ref. 41.

Un criterio de calidad para el manual de recuperación, que sirve para juzgarlo sin ser técnico: lo tiene que poder seguir una persona de confianza que no programe, a las tres de la mañana, con el sistema caído y el agente sin conexión. Si en algún paso dice "consultar con el desarrollador" o "según el caso", ese paso está incompleto.

Y una fuente que no hay que desaprovechar: los pendientes cerrados. Cada uno trae su especificación, su decisión, su evidencia y su fecha. El manual de usuario no se escribe de cero al final: se arma, bloque a bloque, a partir de los pendientes que cerraron, y el diario de cambios sale directamente de ellos.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• Quiénes son los lectores de cada manual: el usuario final, el que mantiene, el que opera la infraestructura. Lo sabe el negocio; el agente pregunta si no está claro.
• El sistema corriendo en el entorno de prueba, para sacar capturas reales.
• Los pendientes cerrados del bloque, con su documentación de cierre (peldaño 5).
• docs/DEPLOYMENT.md (peldaño 15) y docs/LOCKS.md (peldaño 14), que son insumos.

2. Prompts

Rutina (va en el contrato de convivencia):

Qué le estoy pidiendo: la regla del mismo commit, que es la única que mantiene un manual al día; el cierre de bloque como momento en que los pendientes cerrados se vuelven manual y diario de cambios; y la pregunta cuando no está claro a qué manual va.

Para generar los manuales:

Qué le estoy pidiendo: los tres manuales con sus lectores; capturas reales del entorno de prueba (no dibujos ni descripciones); el criterio de las tres de la mañana para el de recuperación; la cláusula de completitud en su forma para documentar: lo que solo el negocio sabe se pregunta, y no se deja un hueco ni se inventa; y fecha y versión, para que se sepa a qué sistema corresponde cada manual.

3. Resultado esperado

• docs/USER_MANUAL.md (o HTML), con capturas reales e incrustadas, que creció bloque a bloque.
• docs/MAINTENANCE_MANUAL.md.
• docs/INFRASTRUCTURE_AND_RECOVERY_MANUAL.md: paso a paso, para una persona.
• docs/CHANGELOG.md, alimentado por los pendientes cerrados.
• Cada uno con fecha y la versión del sistema que documenta.
• En los commits que cambian pantallas, operación o despliegue: el manual actualizado.

4. Verificación de completitud

• Abrí el manual de usuario en una pantalla al azar: ¿la captura coincide con lo que hay hoy en el entorno de prueba?
• ¿El manual de recuperación lo podrías seguir vos, o alguien de confianza que no programe? Leé la sección "se cayó": ¿dice qué hacer, en orden, con los comandos?
• Elegí un commit reciente que cambió una pantalla: ¿tocó el manual?
• ¿El diario de cambios tiene una entrada por cada pendiente cerrado del último bloque?
• ¿Hay un hueco tipo "[completar]" o "consultar con el responsable"? Ahí el agente tenía que preguntar.
• ¿Cada manual dice para qué versión del sistema vale?

5. Señales de alarma

• El manual de usuario tiene capturas de una versión que ya no existe. Se generó una vez y no se mantuvo: la regla del mismo commit no está en el contrato o no se está aplicando.
• El manual de recuperación empieza con "abrí una sesión con el agente". Si el agente es prerrequisito, no es un manual para una persona.
• Nadie fuera del constructor leyó nunca el manual de recuperación. Pedile a alguien que lo siga en el entorno de prueba; lo que lo trabe es lo que hay que arreglar.

Peldaño 21 — Monitoreo de recursos, funciones y consultas fuera de rango, con reporte cíclico (contrato del peldaño)

Tramo: operación. Cuándo: se monta en la fase de operación, con el primer despliegue a producción, con los umbrales del 19 y las métricas del 16; desde entonces, corre solo, y el reporte cíclico se lee con el dueño en cada ciclo (semanal en un sistema con consecuencias, mensual en uno chico). Cada evento fuera de rango entra al bucle como pendiente correctivo. En un legado, igual, con una diferencia: la primera lectura del reporte es la línea base, y lo que ya estaba fuera de rango el primer día se convierte en pendientes con su marca de velocidad. Forma: un solo tiro para montar; después, rutina cíclica. Tamaño: mínimo en un proyecto chico (un reporte mensual, una alerta de disco y una de errores de base); completo en uno con consecuencias (umbrales por función y por consulta, alertas, reporte semanal).

Para qué sirve

Las pruebas del peldaño 19 dicen cómo se comporta el sistema un día, con una carga que yo elegí. La producción es todos los días, con la carga que los usuarios eligen, con los datos creciendo, y con cambios que entran cada semana. Lo que estaba en rango en octubre sale de rango en marzo sin que nadie cambie nada, solo porque la tabla creció. Este peldaño existe para que eso se vea antes de que lo vea el usuario: el uso de recursos contra la capacidad, el tiempo de respuesta de cada función, cada punto de entrada, cada tarea y cada consulta, comparado con los umbrales del 19 y con su propia historia; una alerta cuando algo sale de rango; y un reporte cíclico que yo leo con el dueño, donde cada desvío tiene una causa o un pendiente. El techo apretado a lo medido Ref. 37 es la idea de fondo: el rango no es una opinión, es el número medido más un margen; y la cuota de integración continua que se fundió sin que nadie mirara Ref. 39 es el fallo que evita: un recurso que se consume sin monitoreo se descubre cuando se acaba.

Dos reglas que no negocio. Una alerta que se dispara y nadie lee es un defecto de la alerta, no del que no la leyó: se ajusta o se elimina. Y un umbral no se sube para callar una alerta sin una razón medida escrita.

Si sos principiante. Monitorear es mirar el sistema todo el tiempo por máquina y avisar cuando algo se sale de lo normal. Los recursos son lo que el sistema consume: procesador, memoria, disco, conexiones a la base, y también cuotas de servicios externos (cuántos mensajes por mes te deja mandar el proveedor). "*Fuera de rango*" quiere decir por encima de un umbral (un límite fijo, que salió de las pruebas del peldaño 19) o muy distinto de la línea base (lo que ese mismo número venía dando los últimos días). Una alerta es el aviso en el momento; el reporte cíclico es el resumen que se lee cada semana o cada mes con calma.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• La observabilidad (16): las métricas y los registros de los que se alimenta.
• Los umbrales del 19 y los presupuestos del 17.
• Producción desplegada (15), con acceso de solo lectura para el monitoreo.
• El canal de alertas y el ciclo del reporte: los decidís vos con el dueño.

2. Prompts

Inicial (montar y demostrar):

La ventana de la medición. El reporte cíclico compara las filas observadas por año contra lo declarado en el peldaño 3. Un número correcto con una ventana equivocada abre un pendiente falso: en la práctica Turnera heredada, 30.000 filas de tres años pasadas como si fueran de uno. Por eso la medición lleva su ventana verificable: el primer y el último registro leídos de la base o del registro, no un número escrito a mano. Si la herramienta no puede leer la base, lo declara como punto ciego; una ventana ingresada a mano se marca como tal en el reporte y solo avisa, nunca abre un pendiente por sí sola. (Decisión D-039.)

Qué le estoy pidiendo: recolección con historia (sin historia no hay línea base, y sin línea base no hay "fuera de rango"); alertas contra dos referencias, el umbral absoluto del 19 y el desvío relativo sobre la propia historia; el reporte cíclico con la forma de un reporte del peldaño 12 (cada desvío con causa o con propuesta, nada de "todo normal"); la conversión de cada desvío en pendiente con número; y las dos demostraciones: el primer reporte y una alerta provocada.

Rutina de cada ciclo (va en el contrato de convivencia):

Qué le estoy pidiendo: que el reporte se lea y se decida, con rastro; y la regla del umbral, que es la que evita que el monitoreo se vuelva silencioso de a poco.

3. Resultado esperado

• Recolección de recursos y tiempos de respuesta con historia, sin datos personales.
• Alertas por umbral y por desvío, a un canal que una persona lee.
• El reporte cíclico, generado solo, con cada desvío causado o propuesto.
• docs/MONITORING.md con umbrales, canal, ciclo y cómo silenciar con razón.
• La rutina en el contrato; los desvíos como pendientes correctivos.

4. Verificación de completitud

• Pedí que se supere un umbral a propósito en prueba: ¿te llegó la alerta, por el canal acordado, con el identificador?
• Leé el último reporte: ¿cada evento fuera de rango tiene causa o propuesta? ¿Alguno quedó sin nada?
• ¿Hay un pendiente por cada desvío que decidiste atender, con el número como criterio?
• ¿Algún umbral subió desde el 19? ¿Con qué razón escrita?
• ¿El reporte menciona la cuota de los servicios externos (mensajería, integración continua)?

5. Señales de alarma

• Las alertas se disparan todos los días y nadie las lee. Hay que bajar su cantidad hasta que cada una signifique algo, no acostumbrarse.
• El reporte dice "todo normal" tres ciclos seguidos. O el sistema no tiene usuarios, o el reporte no mira lo que importa.
• Un umbral subió "para que deje de avisar". Es el peldaño 21 muriendo en silencio.
• El monitoreo guarda datos personales "para poder diagnosticar". Es una filtración con horario.

Peldaño 22 — Monitoreo de errores y reporte cíclico: ningún error sin pendiente (contrato del peldaño)

Tramo: operación. Cuándo: se monta en la fase de operación, con el primer despliegue, junto con el 21, sobre los registros del 16; desde entonces corre solo, con alertas en el momento y un reporte cíclico que se lee con el dueño. Cada error nuevo entra al bucle como pendiente correctivo y se cierra con el test que lo reproduce en rojo. En un legado, la primera lectura es la línea base: los errores que ya existían el primer día se vuelven pendientes con su marca de velocidad, y ninguno queda como "conocido" sin un pendiente que diga por qué se tolera y hasta cuándo. Forma: un solo tiro para montar; después, rutina cíclica. Tamaño: obligatorio en todo proyecto con usuarios: la captura centralizada y el reporte no se negocian; las alertas en el momento, proporcionales.

Para qué sirve

Un sistema en producción produce errores que ningún usuario reporta: el que vio la pantalla en blanco y volvió a intentar, el de la tarea nocturna que falló y nadie mira, el de la llamada externa que devolvió un error y el código tragó. Si no los capturo, no existen hasta que existen demasiado. Este peldaño es la contraparte del 21: aquel vigila el rendimiento, este vigila los errores, y los dos terminan en el mismo lugar, el bucle, como pendientes correctivos. Las reglas de fondo son dos. Ningún error sin pendiente: un error nuevo abre uno, y se cierra con el test que lo reproduce en rojo, como pide el modo correctivo del camino evolutivo. Y no existe el "error conocido" sin un pendiente que diga por qué se tolera y hasta cuándo; "ese error siempre estuvo" es la frase con la que un sistema se pudre. El error de autenticación reportado como éxito Ref. 43 y las cuatro rondas hasta la causa raíz Ref. 22 son los dos antecedentes: el primero, de que los errores se esconden si no se los captura por máquina; el segundo, de que un error sin reproducción se arregla varias veces.

Si sos principiante. Un error es cualquier cosa que el sistema intentó hacer y no pudo: una pantalla que no cargó, una tarea nocturna que se cortó, una llamada a otro servicio que falló. Una excepción no manejada es un error que el código no previó y que corta lo que estaba haciendo. Capturar un error es guardarlo con todos sus datos (cuándo, en qué versión, con qué identificador, la pila, que es la lista de pasos del programa hasta el fallo) en un solo lugar central, en vez de dejarlo perderse en la pantalla de un usuario. Agrupar es juntar las mil veces que pasó el mismo error en una sola entrada con un contador. Y la tasa de error por flujo es, de cada cien veces que alguien cargó un turno, cuántas fallaron.

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

• La observabilidad (16): los errores llegan con identificador de correlación, versión y actor.
• La tabla de candados (14): los errores en acciones con consecuencia son alerta inmediata.
• Producción desplegada (15), con el navegador del usuario incluido en la captura.
• El canal de alertas y el ciclo del reporte, compartidos con el 21.

2. Prompts

Inicial (montar y demostrar):

Los errores de la herramienta no son errores del sistema. La captura centralizada separa por fuente: los errores del sistema y los de las herramientas que lo observan (el panel, el agente residente, el propio monitoreo) se guardan con fuente distinta, el reporte los lista en secciones separadas, y solo los del sistema abren pendientes. En la práctica Turnera, el primer reporte cíclico abrió seis "bugs" que eran el panel de Forge hablando con un servidor apagado. (Decisión D-038.)

Qué le estoy pidiendo: la captura en los tres lugares donde los errores se esconden (backend, tareas, navegador), con el identificador del 16 para poder seguirlos; el agrupamiento, sin el cual el reporte es una lista de diez mil líneas; las tres alertas que importan (nuevo, recurrente que crece, con consecuencia); el reporte con la tasa por flujo, que es el número que el dueño entiende; las dos reglas; y la demostración de punta a punta, del navegador al reporte.

Rutina de cada ciclo (va en el contrato de convivencia):

Qué le estoy pidiendo: la disciplina del ciclo, y la regla del error que desaparece, que es la más contraintuitiva y la que más vale: un error que se fue solo vuelve solo.

3. Resultado esperado

• Captura centralizada de errores en backend, tareas y navegador, agrupados por causa, sin datos personales.
• Alertas por error nuevo, recurrente que crece, y con consecuencia.
• El reporte cíclico con la tasa de error por flujo.
• docs/MONITORING.md completo (con el 21); la rutina en el contrato.
• Un pendiente por cada error abierto; ninguno "conocido" sin pendiente.

4. Verificación de completitud

• Provocá vos un error en el navegador en prueba (una acción que sabés que falla): ¿apareció en la captura con tu identificador, y te llegó la alerta?
• Leé el último reporte: ¿hay algún error recurrente sin pendiente ni razón?
• Tomá un error "arreglado" del reporte: ¿el pendiente tiene el test que lo reprodujo en rojo?
• ¿La tasa de error por flujo está, y bajó o subió respecto del período anterior?
• Buscá un dato personal en la captura de errores: no tiene que estar.

5. Señales de alarma

• Cero errores en producción durante un mes con usuarios reales. No hay sistema así; la captura no está viendo el navegador o las tareas.
• Un error con mil ocurrencias y un comentario "conocido, no afecta". Sin pendiente, sin fecha.
• Los errores se "arreglan" reiniciando el servicio. Desaparecen y vuelven.
• El reporte de errores y el de recursos los lee gente distinta y nadie los cruza: la consulta lenta del 21 es la causa del tiempo de espera agotado del 22.

Peldaño 23 — El agente adentro del sistema, y la retrospectiva con número (contrato del peldaño)

Tramo: operación. Cuándo: el agente residente, al entrar en operación, después del primer despliegue a producción. La retrospectiva, al cierre de cada etapa y del proyecto; vuelve al peldaño 0 para el proyecto siguiente. También corré una retrospectiva corta cuando cambiás el modelo que construye: un contrato calibrado para un modelo no necesariamente rinde igual con otro, y el cambio de modelo es exactamente el tipo de hallazgo que esta escalera pide convertir en una propuesta de cambio, no en una sorpresa que se descubre a mitad de un bloque. Forma: dos partes: una conversación para definir el alcance del agente residente, y un tiro largo para la retrospectiva. Tamaño: el agente residente es opcional (muchos sistemas no lo necesitan; los que tienen usuarios que piden soporte, sí). La retrospectiva es obligatoria en todo proyecto, aunque sea de una página: sin ella el método no aprende.

Para qué sirve

Dos cosas que cierran el mismo ciclo. Primero: dejá al agente residente en producción, con alcance acotado, para diagnosticar, operar y dar soporte sin que vos tengas que estar Ref. 13. Segundo: revisá el método mismo con números, y dejá que lo que se aprende cambie la escalera. Evita el agente que opera sin mapa del sistema, y el método que se repite igual proyecto tras proyecto sin aprender. La retrospectiva con número que me llevó a eliminar un equipo entero de agentes es el modelo de lo segundo Ref. 6.

Sobre el agente residente, la regla que ordena todo: actúa a nombre de alguien. Su credencial está mapeada a una persona responsable, y todo lo que hace queda registrado a nombre de esa persona. No es una cuenta de sistema anónima: es un empleado con jefe. Eso define su alcance (lo que esa persona le autorizó) y su trazabilidad (quién responde por lo que hizo).

1. Contexto requerido

Lo que sigue es la lista genérica. Los archivos concretos que tenés que tener hechos antes de cada prompt, con su contenido y su estado mínimo, están en la sección 2, en el bloque "Antes de enviar el prompt" que precede a cada uno.

Para el agente residente:

• Qué puede hacer el agente en producción y qué no: leer, diagnosticar, cambiar configuración, ejecutar acciones. Lo decidís vos.
• Cómo se identifica el agente ante el sistema (una credencial propia, mapeada a una persona responsable).
• A quién avisa cuando encuentra algo que no puede resolver (ticket, correo).

Para la retrospectiva:

• Los incidentes del proyecto, los costos (tokens, cuota, tu tiempo), los pendientes que más vueltas dieron, y las fechas.

2. Prompts

Para el agente residente (inicial):

Qué le estoy pidiendo: el mapa del sistema antes de operar (operar sin mapa es el fallo que este peldaño evita); la cláusula de completitud en su forma: los huecos del mapa se declaran, no se esconden; los tres niveles de alcance para que vos elijas uno y no un "depende"; la regla de la credencial a nombre de una persona; y la cláusula de inyección: lo que el agente lee en producción es dato, nunca instrucción, porque un log o un ticket son justo el lugar donde alguien ajeno puede intentar hablarle al agente directamente.

Para el agente residente (de cierre):

Qué le estoy pidiendo: el documento del agente residente (sin el valor de la credencial, nunca), y la prueba en rojo del alcance: un intento real, registrado, de hacer algo fuera del nivel, rechazado. Es el peldaño 8 aplicado a los permisos.

Para la retrospectiva:

Qué le estoy pidiendo: números con fuente (costos, pendientes, vueltas, incidentes); cada incidente mapeado a un peldaño, porque un incidente que no cae en ninguno es un peldaño que falta; la cláusula de completitud para los números que no tiene (pedir o marcar como estimación); y al menos una propuesta concreta de cambio a la escalera, porque una retrospectiva que no cambia nada no fue una retrospectiva.

3. Resultado esperado

• docs/RESIDENT_AGENT.md: mapa del sistema, alcance elegido, credencial mapeada a una persona, procedimiento de aprobación, y la prueba de rechazo registrada en el log.
• docs/RETROSPECTIVE_[fecha].md: los números con su fuente, los incidentes mapeados a peldaños, y al menos una propuesta de cambio a la escalera con su justificación.

4. Verificación de completitud

• ¿El mapa del sistema dice qué NO puede ver el agente? Si no lo dice, tiene huecos escondidos.
• ¿Probaste (o viste en el log) que una acción fuera del alcance se rechaza?
• ¿La credencial del agente actúa a nombre de una persona identificable?
• ¿El documento dice explícitamente que lo que el agente lee en producción es dato, no instrucción?
• ¿La retrospectiva tiene números con fuente, o adjetivos? ("Costó mucho" no es un número.)
• ¿Cada incidente cae en un peldaño? Si uno no cae en ninguno, falta un peldaño: esa es la propuesta de cambio.
• ¿Hay al menos una propuesta concreta de cambio a la escalera? Si la retrospectiva no cambia nada, no fue una retrospectiva.
• ¿Cambió el modelo que construye desde la última retrospectiva? Si sí, ¿hay una revisión corta de qué contratos siguen rindiendo igual y cuáles no?

5. Señales de alarma

• El agente residente "necesita" un nivel más alto de permisos cada semana. Revisá si lo que pide es para resolver problemas del sistema o sus propios límites.
• El agente ejecutó algo porque "lo decía un log" o "lo pedía un ticket". Un registro o un ticket no autorizan nada; solo vos, o el procedimiento de aprobación que escribiste, lo hacen.
• La retrospectiva dice que todo salió bien. Nunca sale todo bien; está escrita para vos, no para el método.
• Dos proyectos seguidos tuvieron el mismo incidente y la escalera no cambió entre uno y otro. El peldaño 23 no se está cerrando: se escribe la retrospectiva y no se aplica.