2. Qué es un runbook y por qué tu cabeza no lo es

Descripción

Al terminar esta lección vas a poder distinguir con claridad un runbook de la documentación técnica —que es una confusión que hunde a la mayoría de los equipos—, vas a entender por qué el conocimiento tácito es el único riesgo operativo que nadie mide aunque sea de los más caros, y vas a saber hacer el examen honesto que ordena todo este módulo: si mañana no estás, ¿qué se rompe primero?. No vas a escribir un runbook todavía —eso es la lección 3— pero vas a salir sabiendo exactamente qué es lo que vas a escribir y por qué.

Esto importa porque casi todos los equipos creen que ya tienen esto resuelto. Preguntas "¿tienen runbooks?" y la respuesta es "sí, tenemos un wiki con toda la documentación". Y esa respuesta es, casi siempre, la señal más clara de que no los tienen, porque documentación y runbook son dos cosas distintas que sirven a dos momentos distintos, y tener mucha de una no te da ni un poco de la otra. Es como responder "¿tienes un extintor?" con "sí, tengo un manual muy completo de cómo funciona el fuego". El manual es valioso. No apaga nada.

Conexión con el módulo: esta es la lección conceptual de la primera pieza del kit, el runbook. La lección 1 te dio el escenario —Daniela, las tres de la mañana, el sistema que funcionó y aun así falló— y aquí entiendes por qué la pieza que faltaba era precisamente esta. La lección 3, que viene después, es la práctica: la anatomía exacta de un runbook y tres ejemplos completos y reales de Terra Market. Así que piensa en esta lección como el "qué" y el "por qué", y en la 3 como el "cómo". Una frontera que ya conoces pero conviene repetir: aquí no hablamos de versionar documentos ni de dónde vive el wiki —eso toca temas de Git que están en n8n-git-and-environments-guide—; hablamos de qué información va dentro y para quién.

El recetario y el libro de cocina

Hay dos libros en la cocina de cualquier restaurante, y confundirlos arruina el servicio.

El primero es el libro de cocina. Explica la teoría: por qué la masa leva, qué le hace el calor a la proteína, cómo se equilibra la acidez de una salsa. Es profundo, es hermoso, y lo lees en tu casa, con calma, con una copa de vino, cuando quieres entender la cocina. Un cocinero que estudió ese libro cocina mejor durante toda su vida.

El segundo es la ficha de la estación, pegada con cinta a la pared junto a la plancha. No explica nada. Dice: "Hamburguesa clásica: sella 90 segundos por lado, queso al voltear, pan tostado 30 segundos, monta en este orden." No te dice por qué 90 segundos. Te dice 90 segundos. La lees a las nueve de la noche de un viernes, con doce comandas colgando, gritos en la cocina y la mano quemada. La lees en dos segundos y sigues.

Fíjate en la diferencia, porque es exactamente la diferencia entre documentación y runbook:

• El libro de cocina responde "¿cómo funciona esto?". La ficha responde "¿qué hago ahora?".
• El libro se lee con tiempo, para aprender. La ficha se lee con prisa, para actuar.
• El libro te hace mejor cocinero. La ficha te permite sobrevivir el servicio de esta noche.
• Si te falta el libro, cocinas peor con los años. Si te falta la ficha, el viernes se cae.

Un restaurante serio tiene los dos. Y —esto es lo importante— el segundo no se puede deducir del primero en el momento. Con doce comandas colgando, nadie va a abrir el libro de cocina a razonar cuántos segundos necesita la proteína. Esa cuenta se hizo antes, con calma, y se pegó a la pared convertida en un número.

Un runbook es la ficha de la estación de tu sistema. Y la razón por la que casi nadie lo tiene es la misma por la que un cocinero novato cree que con saber teoría le alcanza: mientras no llega el viernes de las doce comandas, la ficha parece redundante.

Ejemplo trabajado: la misma falla, documentada de dos formas

Vamos a tomar un problema real de Terra Market y a escribirlo dos veces. La falla: el nodo Create order in ERP de order-sync empieza a devolver 401 Unauthorized. La causa, que tú conoces pero quien recibe la alerta no, es que el token del ERP expiró.

Versión documentación (así está hoy en el wiki de Terra Market):

## Autenticación de order-sync con el ERP

El workflow order-sync se autentica contra la API del ERP mediante un
token OAuth2 de tipo client_credentials. El token se almacena en la
credencial "ERP Terra Market" de n8n y se inyecta en la cabecera
Authorization de cada petición del nodo HTTP Request "Create order in ERP".

El proveedor del ERP emite tokens con una validez de 90 días. La rotación
es responsabilidad del equipo de automatización. El endpoint de emisión es
POST /oauth/token con los parámetros client_id y client_secret, que se
obtienen del panel de integraciones del ERP.

La política de seguridad de Terra Market (ver Módulo 5) exige que este
token tenga permisos de escritura únicamente sobre el recurso /orders y
lectura sobre /inventory, siguiendo el principio de mínimo privilegio.

Es un buen texto. Es correcto, es completo, y a Daniela a las tres de la mañana no le sirve para nada. Lo lee entero, entiende cada palabra, y sigue sin saber qué hacer. ¿El token expiró? ¿Hay que renovarlo? ¿Cómo? ¿Ella puede? ¿Mientras tanto se están perdiendo pedidos? El texto explica cómo funciona la autenticación. La pregunta era otra.

Versión runbook:

SÍNTOMA: la alerta de order-sync dice 401 / Unauthorized

VERIFICACIÓN (1 min)
· ¿Se están perdiendo pedidos? Corre:
  SELECT count(*) FROM dead_letter
  WHERE source_workflow='order-sync'
    AND created_at > now() - interval '30 min';
· Si el número crece, los pedidos están a salvo. No es emergencia.

QUÉ ES: el token del ERP expiró. Se rota cada 90 días. Es normal, toca
        cada tres meses. No hiciste nada mal.

ACCIÓN (15 min, la puedes hacer tú)
1. Entra al panel del ERP → Integraciones → n8n → "Regenerar token".
2. Copia el token nuevo.
3. En n8n → Credenciales → "ERP Terra Market" → pega el token → Guardar.
4. Reprocesa lo apartado:
   - Abre dead-letter-watch → botón "Reprocess pending".
   - Verifica que dead_letter baja a 0.

CUÁNDO ESCALAR
· Si el paso 1 dice que no tienes acceso al panel del ERP → escríbele a
  Marco, él tiene la cuenta de administrador.
· Si tras regenerar el token el 401 sigue → NO es el token. Escala a
  automatización (yo). Puede ser que revocaron el client_secret.

LO QUE NUNCA HAY QUE HACER
· No borres la credencial vieja para "empezar limpio": otros 4 workflows
  la usan. Solo actualiza el token dentro de ella.

Las dos versiones hablan del mismo token. La primera te enseña. La segunda te salva. Y fíjate en tres cosas que la segunda tiene y la primera no puede tener:

Empieza por el síntoma que se ve, no por el concepto. La documentación se titula "Autenticación con el ERP" —el nombre de un concepto—. El runbook se titula "la alerta dice 401" —lo que la persona tiene delante de los ojos—. Quien recibe la alerta sabe lo segundo y no lo primero. Este es el corazón de la lección 3 y lo adelanto aquí porque es lo que más cambia: el runbook se organiza por síntoma, la documentación por tema.

Dice quién puede hacerlo y hasta dónde. "La puedes hacer tú", "escríbele a Marco", "escala a automatización". La documentación describe un sistema; el runbook reparte una responsabilidad. Daniela no solo sabe qué hacer: sabe qué está autorizada a hacer y en qué punto deja de ser su problema.

Contiene un "nunca". Ese "no borres la credencial vieja" no está en ninguna documentación, porque la documentación describe cómo son las cosas, no advierte contra el atajo que alguien apurado va a considerar. Ese tipo de conocimiento —"lo que parece buena idea y no lo es"— casi solo existe en la cabeza de quien ya se equivocó una vez. Escribirlo es rescatarlo.

Qué esperar. Si haces este ejercicio con tus propios sistemas —tomar una página de documentación y preguntarte "¿esto le sirve a alguien apurado?"— vas a descubrir que tienes mucho del libro de cocina y casi nada de fichas de estación. Es lo normal. La documentación se escribe sola, porque es satisfactoria y se parece a un entregable. La ficha hay que decidir escribirla, y esa decisión es justo lo que este módulo te empuja a tomar.

El conocimiento tácito: el riesgo que nadie mide

Aquí está el concepto que sostiene todo el módulo, y merece que lo desmenucemos despacio porque tiene un nombre técnico que suena abstracto y una realidad muy concreta.

Conocimiento tácito es todo lo que sabes hacer pero no has puesto por escrito. No es ignorancia de nadie: es información real, correcta y valiosa, que existe únicamente en la cabeza de una persona y que se transmite —cuando se transmite— por ósmosis, mirando a alguien trabajar. El cocinero que sabe, sin medir, cuándo la cebolla está en su punto tiene conocimiento tácito. Tú, que sabes que el pico de las 21:00 satura el ERP y que subir la concurrencia lo empeora, tienes conocimiento tácito.

Piénsalo como el agua de un pozo. Mientras hay alguien con el balde —tú— el pozo da agua todos los días y nadie se pregunta cuánto queda ni cómo se saca. El pozo funciona. Pero el día que la persona del balde no está, el pueblo entero descubre, al mismo tiempo y de golpe, que nadie más sabía sacar agua. El agua siempre estuvo ahí; lo que faltaba era el método, y el método vivía en una sola persona.

El conocimiento tácito tiene tres propiedades que lo hacen el riesgo operativo más peligroso, precisamente porque es invisible:

No aparece en ningún inventario. Puedes listar tus workflows, tus credenciales, tus servidores. No puedes listar lo que sabes y no escribiste, porque para listarlo tendrías que escribirlo, y escribirlo es justo lo que no pasó. Es un activo que no figura en ningún balance y un riesgo que no figura en ningún registro. Por eso nadie lo mide: no tiene dónde medirse.

Se siente como competencia, no como riesgo. Que tú seas la única persona que sabe atender order-sync se vive, desde dentro, como ser bueno en tu trabajo. Y lo eres. Pero desde el punto de vista del sistema, eso mismo es un punto único de falla con patas, que además toma vacaciones. La misma cualidad que te hace valioso hoy es la que hace frágil al sistema mañana. Esa contradicción es la razón de que sea tan difícil de atacar: arreglarlo se siente, engañosamente, como volverse prescindible.

Su costo solo se descubre cuando ya es tarde. Un servidor que se puede caer tiene un monitor que avisa antes. El conocimiento que solo está en tu cabeza no tiene monitor: la primera señal de que era un problema es el día que hace falta y no está. No hay alerta previa. Por eso el examen que viene a continuación se hace antes, deliberadamente, como quien revisa el extintor sin esperar el incendio.

Y hay algo que agrava las tres propiedades a la vez: el conocimiento tácito no se va solo el día que tú te vas —se va por goteo, todo el tiempo, en cada persona que rota. En un equipo de seis como el de Terra Market, alguien entra, alguien cambia de rol, alguien se va a otra empresa, y con cada movimiento se evapora un pedazo de "lo que sabíamos y nadie escribió". El equipo no lo nota porque nunca hay un momento en que todo desaparezca de golpe; simplemente, un año después, nadie recuerda por qué inventory-update corre cada quince minutos y no cada cinco, y la decisión que había detrás —que cada cinco saturaba el ERP— se toma de nuevo, mal, porque el que la aprendió ya no está para contarla. Un runbook y una nota de inventario son, en el fondo, una forma de que ese goteo no vacíe el pozo.

Y una precisión honesta para que no te vayas con una idea equivocada: el objetivo no es escribir todo lo que sabes. Eso es imposible y sería inútil —una enciclopedia que nadie lee no salva a nadie a las tres de la mañana—. El objetivo es escribir lo que alguien va a necesitar en el peor momento, que es una fracción pequeña y muy concreta del total. Distinguir esa fracción del resto es una habilidad, y es la que la lección 3 desarrolla. Por ahora quédate con el diagnóstico: la mayor parte de lo que hace operable a tu sistema no está escrita, y eso no es una falla tuya, es el estado por defecto de todos los sistemas hasta que alguien decide cambiarlo.

El examen honesto: si mañana no estás

Este es el examen que ordena el módulo entero, y se hace en voz baja, contigo mismo, sin herramientas.

Imagina que mañana no estás. No importa la razón —vacaciones, gripe, un trabajo nuevo—; el punto es que no contestas el teléfono durante dos semanas y nadie puede llamarte. El sistema sigue corriendo. Los 18 workflows siguen haciendo sus 4.000 ejecuciones al día. Y en algún momento de esas dos semanas, algo se va a romper, porque siempre se rompe algo.

La pregunta no es "¿se va a romper algo?" —sí—. La pregunta es "¿qué se rompe primero, y quién queda sin saber qué hacer?".

Para responderla, recorre tus workflows con esta cuadrícula. Es la misma forma de pensar de la matriz de criticidad del Módulo 1, girada hacia lo humano:

Los dos cuadrantes de la derecha son tu lista de trabajo, y en orden:

"Falla seguido, nadie más sabe" es la emergencia garantizada, y va primero. En Terra Market, esto es order-sync con sus fallos del ERP: pasa cada pocas semanas, y hoy solo tú sabes que el 401 es el token y que el 503 es esperar. En tus dos semanas de ausencia, esto se rompe seguro y deja a alguien varado seguro. Cada workflow de este cuadrante necesita un runbook, y por eso son los tres primeros que vas a escribir en la lección 3.

"Falla rara vez, nadie más sabe" es la bomba de tiempo silenciosa, y es más traicionera. En Terra Market es el comportamiento raro de andes-express que devuelve 200 con un cuerpo de error: pasa una vez cada varios meses, y cuando pasa, la persona que esté de guardia va a ver un "todo bien" que en realidad es un fallo, y no va a tener forma de saberlo. No urge escribir su runbook mañana, pero sí anotarlo en el inventario, porque el día que estalle nadie va a poder deducirlo.

El examen tiene una versión rápida que puedes hacer ahora mismo, en treinta segundos, con un solo workflow: elige tu automatización más importante y describe, en voz alta, qué haría la persona menos experta de tu equipo si esa automatización fallara esta madrugada. Si tu descripción incluye la frase "pues me llamaría", ese workflow no está en producción todavía: está en tu cabeza. Y ya sabes, por la lección 1, que tu cabeza se va de vacaciones.

Un matiz importante para que el examen no te paralice: no todo workflow necesita un runbook. inventory-update, el autocorrectivo, casi no lo necesita: si falla, la corrida siguiente arregla el desastre, y "no hagas nada, revisa en media hora" es un runbook de una línea. La criticidad del Módulo 1 sigue mandando aquí. Lo que este examen agrega es una segunda dimensión —no solo cuánto duele el fallo, sino cuánta gente sabe atenderlo— y el cruce de las dos es lo que te dice dónde poner el esfuerzo.

El runbook como acto de generosidad con tu futuro

Hay una forma de ver el runbook que ayuda a vencer la resistencia natural a escribirlo, y quiero dejártela porque es la que a mí, Mike, me destrabó cuando me costaba sentarme a hacerlo.

Escribir un runbook se siente como escribir para otra persona —para Daniela, para quien llegue en seis meses— y por eso se pospone: mi yo de hoy está ocupado y "ya me sé eso de memoria". Pero hay un lector del runbook que casi siempre se nos olvida: tú mismo, dentro de ocho meses, a las tres de la mañana, medio dormido, sin acordarte de los detalles.

Ese tú futuro no se acuerda de que el token se rota cada 90 días. No se acuerda de que reprocesar dead_letter sin marcar el status duplica pedidos. No se acuerda del contacto real del proveedor. Lo sabías perfectamente el día que lo viviste, y ocho meses después es tan ajeno como si lo hubiera sabido otra persona. El conocimiento tácito no solo se pierde cuando te vas: se pierde solo, con el tiempo, aunque te quedes.

Así que el runbook no es un favor que le haces al equipo. Es un favor que te haces a ti, dos veces: te libera de ser el único que puede responder hoy, y te rescata de tener que recordarlo todo mañana. La generosidad con el equipo es un efecto secundario muy bienvenido de un acto bastante egoísta: dejar de cargar en la cabeza cosas que un archivo puede cargar mejor.

Errores comunes

Confundir "está documentado" con "está operable" (conceptual). Qué pasa: el equipo tiene un wiki extenso, se siente cubierto, y cuando llega el incidente descubre que ninguna de sus páginas responde "qué hago ahora". La documentación explicaba el sistema en reposo; el incidente pedía instrucciones en movimiento. Por qué pasa: escribir documentación es agradable y visible, se parece a terminar algo; escribir un guion de emergencia se siente redundante mientras nada falla, porque "eso ya lo sé". Cómo detectarlo: abre tu mejor página y busca literalmente las palabras "haz", "corre", "abre", "si pasa X entonces". Si la página describe y no ordena, es documentación, no runbook. Cómo corregirlo: no borres la documentación —sirve para aprender el sistema con calma— pero agrégale, aparte, el guion. Son dos documentos, dos propósitos, dos momentos. La lección 3 te da la plantilla del segundo.

Escribir el runbook para el experto que ya sabe (práctico). Qué pasa: quien escribe el runbook es la persona que más sabe, y sin darse cuenta escribe para alguien como ella. "Renueva el token" —obvio para quien sabe dónde, imposible para quien no—. El runbook es técnicamente correcto y prácticamente inservible para la persona que de verdad lo va a leer, que es la que menos sabe. Por qué pasa: es dificilísimo escribir desde la ignorancia cuando tú tienes el conocimiento; das por hecho pasos que para ti son un reflejo. Cómo detectarlo: dáselo a la persona más nueva del equipo y pídele que lo siga al pie de la letra, sin ayuda. Cada vez que te pregunte algo, esa pregunta es una línea que le falta al runbook. Cómo corregirlo: escribe para la persona menos experta que podría recibir la guardia, no para ti. Es exactamente la prueba de fuego del traspaso de la lección 7, adelantada.

Querer documentar todo (conceptual). Qué pasa: alguien se toma en serio lo del conocimiento tácito y decide escribir absolutamente todo lo que sabe. A las tres semanas tiene sesenta páginas, se agotó, lo abandonó, y —peor— produjo un documento tan grande que nadie lo lee a las tres de la mañana, con lo cual no cumple ni siquiera para lo urgente. Por qué pasa: el diagnóstico "casi nada está escrito" produce, por reacción, el impulso opuesto de "hay que escribirlo todo", y los dos extremos fallan. Cómo detectarlo: si tu esfuerzo de documentación lleva semanas y aún no produce una sola página que alguien pueda usar en un incidente real, estás en el extremo equivocado. Cómo corregirlo: empieza por los dos cuadrantes de la derecha del examen —lo que falla y nadie más sabe atender— y escribe solo eso primero. Una página útil hoy vale más que sesenta páginas perfectas dentro de un mes que nunca llega.

Ejercicios

Ejercicio 1 — Clasifica cinco páginas. Aquí hay cinco cosas escritas sobre Terra Market. Para cada una, di si es documentación, runbook, o ninguna de las dos (una nota suelta que no sirve para ninguno de los dos propósitos), y por qué:

(a) "El workflow shipment-notify recibe webhooks del carrier en el endpoint /webhook/carrier-status, los normaliza y envía un correo transaccional por SMTP." (b) "Si #ops-alerts recibe la alerta de correos duplicados de shipment-notify: 1) pausa el workflow, 2) revisa si el carrier está reenviando el mismo evento, 3) escríbele a Lucía que su equipo va a recibir reclamos." (c) "El carrier a veces es raro." (d) "Diagrama de la arquitectura de los 18 workflows y los sistemas que tocan." (e) "Cuando order-sync dé 503: NO subas la concurrencia (empeora), NO relances a mano uno por uno (usa el botón de reproceso), espera a que el ERP vuelva."

Ejercicio 2 — Haz el examen honesto. Toma tres workflows tuyos que estén corriendo hoy (o los tres de Terra Market). Para cada uno, ubícalo en la cuadrícula de dos ejes —¿falla seguido o rara vez? ¿alguien más sabe atenderlo o solo tú?— y di qué acción concreta le corresponde: runbook urgente, nota en el inventario, o nada.

Ejercicio 3 — Rescata un conocimiento tácito. Piensa en una cosa que sabes sobre tus sistemas y que nadie más sabe, del tipo "cuando pasa X, en realidad es Y, aunque parezca Z". Escríbela primero como te sale (probablemente como una nota suelta inútil, tipo el (c) del ejercicio 1) y después reescríbela para que le sirva a alguien que no eres tú.

El ERP se pone lento a las 9 de la noche.

SÍNTOMA: entre 20:45 y 21:30, order-sync tarda más y algunas ejecuciones
dan timeout en "Create order in ERP".

QUÉ ES: es el pico de pedidos del día. El ERP responde lento por carga,
        no está caído. Es esperado, pasa todas las noches en ese horario.

ACCIÓN: nada, si es solo lentitud y los reintentos resuelven. Los pedidos
        que dan timeout se apartan en dead_letter y se recuperan solos en
        el reintento o se reprocesan después. Verifica que dead_letter no
        crezca sin parar.

LO QUE NUNCA HAY QUE HACER: NO subas la concurrencia de order-sync para
        "acelerar". Manda más peticiones a un ERP ya saturado y lo tumbas
        del todo. La lentitud a esta hora se aguanta, no se combate.

Resumen y siguiente paso

En esta lección separaste dos cosas que casi todos los equipos confunden, con la imagen del libro de cocina y la ficha de la estación: la documentación responde "¿cómo funciona esto?" y se lee con calma para aprender; el runbook responde "¿qué hago ahora?" y se lee con prisa para actuar. Viste la misma falla del ERP escrita de las dos formas y comprobaste que la versión documentación, siendo correcta y completa, no le sirve de nada a quien está apurado. Entendiste el concepto que sostiene el módulo —el conocimiento tácito, con la imagen del pozo y el balde—: información real y valiosa que vive en una sola cabeza, que no aparece en ningún inventario, que se siente como competencia y no como riesgo, y cuyo costo solo se descubre cuando ya es tarde. Aprendiste a hacer el examen honesto —si mañana no estás, ¿qué se rompe primero?— con la cuadrícula de dos ejes que cruza "cuánto falla" con "quién más sabe atenderlo", y viste que no todo workflow necesita un runbook: solo los de los dos cuadrantes de la derecha. Y quedó dicho lo más importante para no paralizarte: el objetivo no es escribir todo lo que sabes, sino la fracción pequeña que alguien va a necesitar en el peor momento.

Antes de avanzar deberías poder: explicar en una frase la diferencia entre documentación y runbook; decir por qué el conocimiento tácito es un riesgo aunque no aparezca en ningún registro; y hacer el examen honesto sobre tu automatización más importante sin que la respuesta sea "me llamarían a mí".

Lo que no viste todavía es cómo se escribe uno de verdad. Sabes qué es un runbook y por qué lo necesitas; lo que falta es la anatomía —las cinco partes que todo buen runbook tiene—, la regla que lo organiza —por síntoma, no por causa, porque quien recibe la alerta todavía no sabe la causa—, y sobre todo la práctica: en la lección 3 vas a escribir tres runbooks completos y reales de Terra Market, uno para cada uno de los tres síntomas más frecuentes —el ERP no responde, llegaron pedidos duplicados, y la cola de dead_letter creció—. Es la lección más técnica del módulo, y al terminarla vas a tener las primeras tres fichas pegadas a la pared de tu cocina.

Recursos

• Handle errors gracefully — n8n Docs — describe lo que el sistema resuelve solo; todo lo que este documento no cubre es, justamente, lo que un runbook tiene que decirle a una persona.
• Configure workflow settings — n8n Docs — el campo Error Workflow y los ajustes por workflow: la referencia técnica que un runbook traduce a acciones concretas.
• Postgres node — n8n Docs — el nodo con el que se corren las consultas de verificación rápida que abren cada runbook (dead_letter, error_log, inbox).
• Credentials — n8n Docs — cómo se guardan y editan las credenciales, el conocimiento que el runbook del token del ERP convierte en cuatro pasos ejecutables.