Al terminar esta lección
- Redactar un runbook de release que alguien que no escribió la feature pueda ejecutar, con disparadores y responsables.
- Diseñar señales de observabilidad ligadas a preguntas operativas, sin datos sensibles.
- Ensayar tres fallos, anotar el comportamiento esperado, la evidencia y clasificar cada hallazgo como código, spec o entorno.
- Armar un guion de demo de 20 minutos con cinco historias, un fallo incluido y preguntas que puedan refutar la solución.
Nexo B2B · Expediente 11: ensayo de un lunes a las 9
Escenario: 25 vendedores conectados, catálogo cargando, una integración externa lenta y una migración desplegada la noche anterior. El equipo ejecuta smoke tests, confirma métricas, revisa la cola de outbox y simula un retry. La pregunta no es si el sistema “abre”, sino si puede operar y explicar fallos.
Un runbook también define quién decide. Si la tasa de errores supera el umbral, alguien debe poder pausar el despliegue o activar el rollback. Sin autoridad operativa, una checklist técnica puede quedarse esperando mientras producción se degrada. Este taller te pide construir exactamente esa autoridad en papel antes de necesitarla.
Práctica E11 · Preparar una demo que pueda fallar
Situación. Diseñá la demo del release 1 de Nexo para dueño, vendedor y depósito.
Entregá. Guion de 20 minutos; dataset; 5 escenarios; plan de rollback demo; preguntas de validación.
Está listo cuando. Cada escenario conecta con un objetivo; incluye al menos un fallo; el usuario puede refutar supuestos; no depende de discursos técnicos.
Solución comentada: Solución comentada E11. Comparala después de producir tu entrega.
El taller tiene seis pasos. Cada uno tiene un objetivo, un tiempo sugerido, un ejemplo parcial ya trabajado y un ejercicio que produce un artefacto. La solución comentada vive en 14.4: usala para comparar, no como punto de partida. Los tiempos suman unas dos horas y media, incluida la revisión de otra persona.
Antes de empezar, el material de referencia es el del caso: las migraciones 0005, el backfill y la 0007; el compose de demo; el pipeline con sus gates; el smoke de demo y el plan de rollback con sus tiempos medidos. Si algún dato del ejercicio contradice el caso, el caso gana, y lo dejás anotado como desconocido.
Paso 1 · El runbook mínimo (30 minutos)
Objetivo. Producir un runbook que alguien que no escribió la feature pueda seguir sin preguntarte nada.
Qué incluye. Prechecks, backup y punto de rollback, orden de migración y de deploy, smoke tests, señales a observar y criterios de aborto con responsable. Antes de escribirlo, ordená las secciones: el orden importa porque cada una depende de la anterior.
Ordená las secciones del runbook de release
Usá las flechas para dejar las secciones en el orden en que alguien las necesita durante el release.
- Posición 1 de 7: Prechecks: backup verificado, flags con defaults conocidos, compatibilidad N-1 confirmada.
- Posición 2 de 7: Punto de rollback: digest de la imagen anterior y estado del schema antes de la migración.
- Posición 3 de 7: Disparadores de rollback, quién decide y cuánto tarda cada paso.
- Posición 4 de 7: Migración en fase expand, backfill por lotes y verificación de conteos.
- Posición 5 de 7: Smoke de readiness y de reglas, con la versión que corresponde a cada entorno.
- Posición 6 de 7: Deploy por digest, con réplicas nuevas y la versión anterior todavía atendiendo.
- Posición 7 de 7: Señales a observar durante 60 minutos, con umbrales y responsable de cada una.
Un ejemplo parcial del runbook, con cuatro secciones completas y tres pendientes. Lo que queda en PENDIENTE es tu trabajo:
release: r1.4.2
punto_de_rollback:
digest_anterior: "sha256 de la imagen r1.4.1, registrado antes del deploy"
schema: "versión 4 confirmada antes de la migración 0005"
migracion:
fase_expand: "db/migrations/0005_expand_request_hash.sql"
backfill: "db/ops/backfill-request-hash.sql, lotes de 500, repetir hasta 0 pendientes"
fase_contract: "0007 NO se ejecuta en esta ventana: requiere gate propio"
smoke:
produccion: "scripts/smoke-readonly.sh (solo lectura)"
staging_y_demo: "scripts/smoke-demo.sh (crea pedidos sintéticos)"
disparadores_de_rollback:
- "PENDIENTE: umbral de errores 5xx, con ventana de medición"
- "PENDIENTE: umbral de lag del outbox, con ventana"
- "PENDIENTE: condición de invariante que dispara rollback inmediato"
responsables:
decide: "PENDIENTE: nombre o rol, y qué autoridad tiene para pausar sin consultar"
ejecuta: "operaciones"
comunica: "PENDIENTE"
tiempos_objetivo:
decision: "PENDIENTE: minutos desde el disparador"
rollback_aplicacion: "PENDIENTE: usar el tiempo medido en staging, no uno estimado"
Completá los disparadores del rollback
Completá las tres secciones PENDIENTE del ejemplo: disparadores con umbral y ventana, responsables con autoridad explícita y tiempos objetivo. Cada disparador tiene que poder verificarse con una métrica o una consulta que ya definiste en el caso.
Ver pistas si te trabaste
- Un umbral sin ventana es ruido: un pico de un segundo no justifica un rollback.
- La invariante de reserva negativa no tiene ventana de espera. Si aparece, el disparo es inmediato.
- “Comercial decide” no es un responsable para pausar el release si comercial no tiene acceso al pipeline. Nombrá a quien sí lo tiene.
- Si no tenés el tiempo medido, escribí “estimado” y registralo como unknown para medirlo en el próximo ensayo.
Paso 2 · Cinco señales ligadas a preguntas (25 minutos)
Objetivo. Diseñar cinco eventos o métricas que respondan preguntas reales de la operación, sin loguear datos sensibles.
Criterio. Evitá “log request” o “log error” como respuesta genérica: no dicen qué pregunta responden ni qué hace alguien cuando aparecen. Compará los dos diseños antes de escribir el tuyo:
Señal genérica vs señal que responde una pregunta
logger.info("pedido creado", { body: req.body }). Imprime el payload completo: precios, identificadores de cliente y líneas. No responde ninguna pregunta de la operación, y el día que aparece un dato personal en el body, ya está en los logs.
Evento order.create.finished con request_id, order_id, actor, cu, result, rule y duration_ms. Responde “¿por qué quedó pendiente?” y “¿cuánto tardó?”. Excluye precios y datos del cliente. Tiene una alerta asociada: si duration_ms p95 supera el umbral de NFR-01 durante 10 minutos, se avisa al responsable.
Un evento bien formado tiene cuatro partes: la pregunta que responde, los campos que incluye, los que excluye a propósito y quién lo mantiene. Este es el de ejemplo, parcial, para que lo tomes como modelo:
Evento: order.reservation.rejected
Pregunta: ¿por qué un pedido no obtuvo la reserva y cuántas veces pasó esto hoy?
Campos: request_id, order_id, sku, depot_id, reason ("stock_insuficiente" | "carrera"), attempt
Excluye: cantidades solicitadas por cliente, precio, nombre del cliente
Alerta: reason = "carrera" más de 3 veces en 10 minutos en el mismo depot_id
Responsable: PENDIENTE
Diseñá cuatro señales más
Escribí cuatro eventos o métricas adicionales con la misma estructura del ejemplo: pregunta, campos, exclusiones, alerta y responsable. Tienen que cubrir al menos dos preguntas de las que aparecieron en el caso: por qué un pedido quedó pendiente de autorización, cuánto tarda el handoff a preparación, si un reintento se procesó dos veces y quién autorizó una excepción.
Ver una solución posible
Si tu lista tiene campos como total_cents o customer_name, sacalos: el evento responde preguntas de operación y no necesita el dato de negocio. Si una alerta no tiene un responsable que pueda actuar, todavía no es una alerta: es una métrica que se mira cuando alguien se acuerda.
Paso 3 · Ensayar tres fallos (40 minutos)
Objetivo. Ensayar tres fallos (integración caída, respuesta perdida y dato histórico incompatible), anotar el comportamiento esperado y la evidencia que lo demuestra.
Método. Para cada fallo: escribí qué debería pasar antes de inyectarlo, después inyectalo en el entorno de demo, y registrá qué señal apareció, cuánto tardó la detección y cuál fue la recuperación. Si el comportamiento real no coincide con el esperado, no lo corrijas en el momento: clasificá el hallazgo. Esa clasificación es el trabajo más importante de este paso.
Los tres fallos, con la forma en que el caso los resolvió:
- Integración caída. El ERP simulado sube su latencia a 28 segundos. Esperado: el pedido falla con 503
temporarily_unavailable, sin pedido parcial. Señal: la métrica de duración sube y el evento de rechazo lleva el motivo de dependencia. - Respuesta perdida. El proxy corta la respuesta justo después del commit y el usuario reintenta. Esperado: el reintento con el mismo
requestIddevuelve el pedido existente. Señal:idempotent_replays_totalaumenta en una unidad. - Dato histórico incompatible. Se aplica el paso de la 0007 sobre la copia con los 1.412 pedidos sin depósito todavía en la tabla activa. Esperado: la migración se niega a ejecutarse y el gate lo informa, sin cambiar datos. Señal: la consulta de precondición devuelve un número distinto de cero.
Antes de la clasificación, mirá cómo se ve un hallazgo sin clasificar. Supongamos que el test de paridad del backfill falla y que el primer diagnóstico del equipo fue “la migración está mal”. Eso no ayuda a nadie: no dice si hay que cambiar el código, la spec o el entorno, y cada categoría tiene un arreglo distinto.
Clasificá cada hallazgo del ensayo
Un hallazgo es código si el software no hace lo que la spec dice. Es spec si la spec no dice qué debería pasar. Es entorno si el problema viene de la infraestructura del ensayo. Elegí una sola categoría.
El backfill calcula el hash con upper() y el fingerprint TypeScript no normaliza el SKU, así que el test de paridad falla.
El readiness devuelve 503 en staging porque la migración 0005 nunca se aplicó en ese entorno.
No está definido si un reintento tras timeout debe responder 200 con el pedido existente o 201 como si fuera nuevo.
El simulador fiscal no responde porque el servicio no está en la red del compose y la app lo resuelve por un nombre que no existe.
El pedido con requestId repetido se crea dos veces porque la clave idempotente se escribe después del commit del pedido.
Sin un criterio escrito, el equipo no sabe si un rechazo por lag del outbox durante 12 minutos justifica un rollback.
Un diagrama del ciclo de un fallo ensayado. Te sirve para comprobar que cada inyección termina en una señal, una decisión y una recuperación medida, y no en una anécdota:
Escribí los tres fallos ensayados
Para cada uno de los tres fallos del paso, anotá: comportamiento esperado escrito antes del ensayo, la señal que lo hizo visible, el tiempo de detección y de recuperación, la evidencia (consulta, log o captura) y la clasificación del hallazgo si el comportamiento no coincidió. Si el fallo no coincidió con lo esperado, dejá el hallazgo registrado aunque lo hayas corregido.
Ver una solución posible
Un fallo ensayado que no tiene hallazgo suele indicar que el ensayo fue demasiado cómodo. Si lo inyectaste sin pensar qué esperabas, el resultado no te enseña nada. Si el hallazgo es solo de entorno, preguntate si el entorno del ensayo debería haberse parecido más a producción. Y si no tenés tiempos medidos, anotá el número como estimado: es mejor un tiempo honesto que un tiempo bonito.
Paso 4 · El guion de la demo de 20 minutos (30 minutos)
Objetivo. Escribir un guion de 20 minutos con cinco escenarios, un fallo incluido y la versión corta de 12 minutos para el ensayo técnico.
Regla. La demo empieza con el problema y termina con los límites. No recorre menús. Cada bloque responde una pregunta del público, no una pantalla del sistema. Ordená los bloques antes de escribir el tuyo.
Ordená los bloques del guion de 20 minutos
Usá las flechas para dejar los bloques en el orden de la demo. El último bloque tiene que devolver la conversación al problema.
- Posición 1 de 6: Autorización y última unidad: dos historias de decisión y de concurrencia (4 minutos).
- Posición 2 de 6: Integración lenta y reintento: el fallo de la demo, con señal visible (4 minutos).
- Posición 3 de 6: Pedido normal y límite de crédito: el caso que el vendedor hace todos los días (4 minutos).
- Posición 4 de 6: Quiebre físico en picking: lo que el sistema no resuelve y quién lo resuelve (4 minutos).
- Posición 5 de 6: Problema y promesa: qué no funciona hoy y qué garantía va a mostrar la demo (2 minutos).
- Posición 6 de 6: Resultado medible y preguntas de validación para el público (2 minutos).
Un ejemplo parcial del guion, con los bloques 1 y 2 completos y los demás a completar. Fijate en que cada bloque tiene un observable concreto:
Guion · Demo release 1 · 20 minutos
Audiencia: dueño, vendedor, responsable de depósito
[0:00 - 2:00] Problema y promesa
Decir: hoy el pedido llega por WhatsApp, se reescribe en el ERP y el depósito se entera tarde.
Promesa: “Lo que vamos a ver es qué pasa cuando el límite, el stock o la red juegan en contra.”
Señal visible: ninguna. Es el momento de pedir a la audiencia una pregunta concreta.
[2:00 - 6:00] Pedido normal y límite de crédito
Estado inicial: DEMO-CLI-03, saldo 480.000,00, límite 500.000,00.
Acción: el vendedor carga un pedido de 20.000,00 (queda justo en el límite).
Señal: pedido confirmado; regla RN-01 aplicada; reserva creada.
Éxito: el total coincide con la lista vigente y el saldo queda en el límite.
Pregunta a la audiencia: “¿Qué harías vos con un pedido que queda justo en el límite?”
[6:00 - 10:00] PENDIENTE
[10:00 - 14:00] PENDIENTE
[14:00 - 18:00] PENDIENTE
[18:00 - 20:00] PENDIENTE: resultado medible y límites
Para la versión de 12 minutos del ensayo técnico, reducí el guion a problema (1 minuto), autorización (3), última unidad (3), integración lenta con reintento (3) y límites (2). La versión de 12 minutos no reemplaza a la de 20: sirve para ensayar el tiempo y el orden técnico antes de presentar.
Completá el guion de la demo
Completá los cuatro bloques PENDIENTE del ejemplo, con estado inicial, acción, señal observable, criterio de éxito y una pregunta para la audiencia en cada bloque. Incluí al menos un fallo (la integración lenta o la respuesta perdida) y que el bloque de límites diga explícitamente qué no protege el sistema.
Ver una solución posible
Si tu guion no tiene ningún momento donde la audiencia pueda decir “eso no funciona así”, todavía es un tour. Buscá el bloque donde una decisión de negocio cambia el resultado y ponela explícitamente. Y si la versión de 12 minutos es solo un recorte de la de 20 sin reordenar los bloques, perdiste la narrativa: la de 12 tiene que empezar igual y terminar igual.
Paso 5 · Dataset y sesión de validación (20 minutos)
Objetivo. Definir el dataset sintético de la demo y las preguntas de validación que pueden refutar la solución.
Dataset. Usá la clasificación del caso como punto de partida: sintético, anonimizado o prohibido. Para la demo solo entra lo sintético. Un dataset útil tiene clientes de cada categoría de crédito, al menos un caso en el borde exacto del límite, al menos un caso un centavo por encima, un SKU con stock insuficiente, un acuerdo sin vigencia y un pedido de un vendedor fuera de su cartera. Todos con identificadores que empiecen con DEMO.
Preguntas de validación. Escribí cinco preguntas que busquen episodios, no opiniones. “¿Te gustó?” no sirve. “¿Cuándo fue la última vez que un pedido quedó pendiente sin que supieras por qué?” sí sirve. Y definí, antes de la sesión, qué respuesta confirmaría la solución y cuál la refutaría.
Antes del paso siguiente, un contraejemplo: una sesión de validación que empieza con “te muestro cómo funciona”. Ese orden ya le dice al usuario qué debe aprender, y convierte la sesión en demo de asentimiento.
Escribí las preguntas de validación
Escribí cinco preguntas para la sesión de validación con vendedores y responsable de depósito. Cada pregunta busca un episodio, una decisión o un dato que la persona usa fuera del sistema. Para cada una, anotá la respuesta que confirmaría la solución y la que la refutaría.
Ver pistas si te trabaste
- Una pregunta que empieza con “¿te parece…?” invita a responder “sí”. Reescribila con “¿qué hiciste la última vez que…?”.
- Si todas las preguntas confirman la solución, probablemente hiciste preguntas que ya sabías responder. La pregunta valiosa es la que te incomoda.
- Las preguntas sobre TTL o tolerancia de Platino no tienen respuesta en el release: si las hacés, la respuesta correcta es “no lo sabemos todavía”, y eso también es un resultado.
Paso 6 · Auditá el pipeline heredado y cerrá el gate (25 minutos)
Objetivo. Revisar un pipeline escrito por otro equipo, detectar lo que permitiría un release sin gates, y cerrar el gate de esta lección.
Antes de cerrar tu entrega, auditá este pipeline. Lo escribió otro equipo para un release parecido. Hacé clic en las líneas que permitirían un deploy a producción sin tests, sin aprobación, con una imagen no verificable o con datos que no deberían salir del pipeline.
¿Qué permite este pipeline que no debería permitir?
Hacé clic en las líneas que rompen un gate, mezclan staging con producción, usan una imagen no reproducible o exponen un secreto. Elegí solo las que son un problema real.
Ahora la tarea de cierre. Tu entrega tiene que pasar los criterios del gate. El tracker guarda tu autoevaluación. La aprobación real requiere revisar la evidencia que produjiste en los pasos anteriores.
Criterios de revisión
Revisá tus artefactos antes de marcar cada criterio. El checklist registra tu autoevaluación; la aprobación requiere revisar la evidencia.
Gate 11 · la solución está lista para demostrarse
Un gate no es una formalidad. Si una condición crítica no se cumple, el trabajo correcto es hacer visible la incertidumbre y volver a buscar evidencia.
Un criterio que se marca sin evidencia no cuenta. Para cada uno de los cinco, la pregunta de control es la misma: ¿qué artefacto de este taller lo demuestra? Si la respuesta es “ninguno, pero lo hice mentalmente”, dejalo sin marcar y anotalo en la hoja de entrega como riesgo abierto.
Cuaderno de campo 11 · Game day
Entregable: guion de game day de 30 a 60 minutos.
- Elegí cuatro fallos plausibles y asigná a otra persona para dispararlos sin decirte el orden.
- Tu equipo debe detectar cada fallo a través de señales, no porque quien lo inyectó avise.
- Registrá tiempo de detección, diagnóstico y recuperación.
- Actualizá runbook y observabilidad con lo aprendido.
- Decidí qué fallos bloquearían release y cuáles pueden aceptarse con mitigación.
Para el quinto punto, usá la misma lógica que el caso: un fallo bloquea el release si rompe una invariante (reserva negativa, pedido duplicado) o si no tiene recuperación medida. Puede aceptarse con mitigación si el daño es acotado, la señal existe y el procedimiento está escrito.
Revisión: una demo bonita no sustituye un game day. Una demo vende comprensión del flujo; el game day construye confianza operativa. Necesitás las dos cosas, y no se reemplazan.
Hoja de entrega 11 · completá antes de pasar el gate
Este bloque no se completa “de memoria”. Volvé a tus artefactos, evidencia y resultados. El objetivo es obligarte a hacer explícito qué vas a defender frente a un mentor o cliente.
Artefacto que entrego y versión:
Tres evidencias que sostienen mis decisiones:
Decisiones que tomé yo y que un agente no podía tomar:
Desconocidos o riesgos que siguen abiertos:
Feedback o propuesta de IA que rechacé, y por qué:
Qué tendría que ocurrir para que yo mismo cambie esta conclusión:
Revisión de calidad: qué corregí antes de enviar o presentar:
Firma del mentor/reviewer o referencia del feedback:
Guardá tu entrega
Completá la entrega 11, adjuntá evidencia y registrá los criterios del gate que todavía no podés demostrar.
Cuando termines tu entrega, compará tu razonamiento con la solución comentada E11. No hay una única respuesta correcta: la comparación busca fuentes, decisiones y evidencia.
Errores frecuentes
- Síntoma: el runbook dice “rollback a la versión anterior” y nadie sabe qué digest es. Causa: el punto de rollback no se registró antes del deploy. Corrección: el digest anterior y el estado del schema se anotan como primer paso, antes de cualquier cambio.
- Síntoma: la señal se dispara todas las mañanas y después nadie la mira. Causa: el umbral no tiene ventana de medición ni responsable. Corrección: cada alerta del runbook tiene umbral, ventana, responsable y acción concreta.
- Síntoma: en el ensayo, el equipo corrige el código del fallo en el momento y no queda registro. Causa: el ensayo se trató como un arreglo y no como una evidencia. Corrección: registrar el comportamiento antes de corregir, y clasificar el hallazgo como código, spec o entorno.
- Síntoma: el guion de 20 minutos termina en 35. Causa: el orden de los bloques no tiene tiempos asignados y la demo se alarga en el primer escenario. Corrección: asignar minutos a cada bloque y ensayar con cronómetro.
- Síntoma: la sesión de validación confirma todo lo que el equipo ya creía. Causa: las preguntas se escribieron para obtener un sí, o los datos eran demasiado limpios. Corrección: preguntas de episodio, datos con bordes y una respuesta que refute la solución escrita de antemano.
Para llevarte
- Un runbook se escribe para quien no lo escribió: punto de rollback, orden de migración, disparadores con umbral y responsable que pueda decidir.
- Una señal responde una pregunta concreta de la operación, excluye los datos que no la responden y tiene alguien que la mantiene.
- Un fallo ensayado tiene comportamiento esperado escrito antes, señal observable, tiempos medidos y un hallazgo clasificado si no coincidió.
- El guion de la demo empieza con el problema, incluye un fallo y termina con lo que el sistema no protege.
- Una sesión de validación busca episodios y datos de borde. Si confirma todo, probablemente no preguntó lo suficiente.
- Un pipeline se audita contra sus gates: needs, environment, digest, smoke sin efectos en producción y ningún secreto impreso.
IA EN ESTA FASE
Qué puede hacer el agente: revisar el borrador del runbook contra el plan de release y señalar secciones sin responsable o sin umbral, proponer señales a partir de preguntas que vos escribiste, convertir tus notas del ensayo en el formato de hallazgos y sugerir preguntas de validación que busquen episodios.
Qué no debe decidir: qué fallo bloquea el release, qué umbral es aceptable para la operación, qué pregunta de validación se descarta o si un criterio del gate está cumplido.
Contexto mínimo útil: el runbook completo, las señales con sus preguntas, los resultados del ensayo con tiempos y el guion de la demo. No le pases datos reales de clientes ni de pedidos, aunque sea para “ayudarte a leer” un caso.
Cómo verificar: cada umbral que el agente propone se contrasta con una medición del ensayo. Cada hallazgo se revisa contra la evidencia original. Las preguntas de validación se leen en voz alta a alguien del equipo antes de la sesión.
Prompt de ejemplo:
Sos revisor de un runbook de release para Nexo B2B.
Te paso el runbook, la lista de señales con sus preguntas y las notas del ensayo.
Para cada sección del runbook respondé:
1. ¿Tiene un responsable que puede actuar sin consultar a otra área?
2. ¿Cada disparador tiene umbral, ventana de medición y una acción concreta?
3. ¿Algún tiempo es estimado y figura como medido?
Para las notas del ensayo, proponé una clasificación (código, spec o entorno) con la razón en una línea, y marcá las que no podés clasificar sin más datos.
No cambies los umbrales ni agregues disparadores sin marcarlos como propuesta.
Al revisar la salida, comprobá que cada propuesta de umbral tiene una medición detrás y que las clasificaciones dudosas quedaron como hallazgos abiertos. Si el agente dice que el release está listo, esa frase no es evidencia: el gate lo decide la evidencia que revisaste.
¿Cómo valoras el contenido técnico de esta lección?
Tu feedback nos ayuda a mejorar los laboratorios prácticos de Eje Z.