# Redacción de manuales operativos

Produce el procedimiento que alguien sigue bajo presión, de noche, sin contexto y sin nadie a quien preguntar.

## Entregable

Un documento Markdown, `runbook.md`, con la estructura fijada en **Salida** más abajo. Un manual cubre un procedimiento; un segundo procedimiento lleva un segundo documento.

## Entradas obligatorias

- **El procedimiento** — la operación que hay que dejar escrita y la condición que la dispara.
- **El sistema contra el que se ejecuta** — acceso a él, o a alguien que ejecute los pasos mientras tú los registras.
- **Quién lo va a ejecutar** — el rol, y qué le está permitido hacer a ese rol sin pedir permiso.

Si falta cualquiera de los tres, detente e informa de cuál. Un manual escrito sin saber quién lo ejecuta o bien supone accesos que esa persona no tiene, o bien le oculta pasos que necesita.

## Entradas opcionales

- Incidentes anteriores en los que se usó este procedimiento y qué salió mal
- La monitorización, las alertas o los síntomas que indican que este manual aplica
- El proceso de cambios y aprobaciones que esta operación debe respetar
- Un entorno fuera de producción donde ensayar los pasos
- La estructura de escalado, por roles
- El registro de auditoría o cumplimiento que esta operación debe dejar

Cuando falta una entrada opcional, el manual lo dice en el punto donde importa: un paso no ensayado se marca `sin probar`, una ruta de escalado desconocida se escribe `desconocido` en la sección 7. Nunca se rellena con lo más probable.

## Ejecución

**1 — Fijar el límite.** Cuándo aplica este manual y — igual de importante — cuándo no, nombrando el procedimiento más cercano para los casos que no cubre. Quien sigue con confianza el manual equivocado hace más daño que quien se detiene.

**2 — Listar las precondiciones y los accesos.** Qué debe ser cierto antes del primer paso y qué permisos, credenciales o aprobaciones necesita tener ya en la mano quien opera. Todo lo que habría que solicitar a mitad del procedimiento es una precondición, no un paso.

**3 — Escribir los pasos, cada uno con su verificación.** Una acción por paso, en orden, con el comando o el control nombrado exactamente y las partes variables escritas como `<nombre>`. Debajo de cada uno, cómo confirma quien opera que funcionó. Un paso sin verificación es un paso cuyo fallo se descubre más tarde y por otra vía.

**4 — Escribir las bifurcaciones como ramas.** Donde el procedimiento se abre, declara la condición observable y qué hacer a cada lado. Ningún paso puede decir `según convenga`: bajo presión esa frase significa que quien opera está adivinando, y el manual le ha devuelto la decisión a la persona peor situada para tomarla.

**5 — Escribir la reversión.** Para cada paso que cambia el estado, cómo deshacerlo y si se puede deshacer siquiera. Un paso que no se puede revertir se marca `IRREVERSIBLE` y lleva su propia confirmación antes de ejecutarse.

**6 — Tratar el fallo en el sitio.** Debajo de cada paso, qué hacer cuando falla, en lugar de una sola sección al final. Después el escalado: a quién involucrar, por rol y no por nombre, en qué momento y qué contarle.

**7 — Ensayar y después marcar lo que no se ensayó.** Ejecuta el procedimiento donde sea seguro hacerlo, corrige lo que la ejecución revele y marca `sin probar` cada paso que no pudiste ejecutar. Registra qué hay que dejar anotado al terminar: horas, decisiones tomadas y el estado en que quedó el sistema.

## Salida

`runbook.md`, en este orden:

- **1. Alcance** — cuándo aplica, cuándo no y a dónde ir en su lugar
- **2. Precondiciones** — qué debe ser cierto y qué accesos necesita quien opera
- **3. Roles** — quién lo ejecuta y a quién hay que avisar de que se está ejecutando
- **4. Pasos** — numerados, una acción cada uno, con la verificación y la respuesta al fallo debajo
- **5. Bifurcaciones** — la condición observable y la rama que se toma en cada caso
- **6. Reversión** — por paso que cambia el estado: cómo deshacerlo, o `IRREVERSIBLE`
- **7. Escalado** — el disparador, el rol al que acudir y qué entregarle
- **8. Al terminar** — qué registrar, dónde y quién lo revisa
- **9. Estado del ensayo** — qué pasos se ejecutaron, cuáles quedan `sin probar` y cuándo se ejecutó esto por última vez

## Validación

El manual está listo cuando se cumple todo esto:

- Cada paso de la sección 4 declara una sola acción y cómo verificarla
- Ningún paso contiene `según convenga`, `si hace falta` ni ninguna otra instrucción que devuelva la decisión a quien opera
- Cada paso que cambia el estado aparece en la sección 6, con su reversión o como `IRREVERSIBLE`
- Cada rama de la sección 5 nombra una condición observable, no un juicio
- La sección 7 nombra roles, nunca personas
- Cada paso no ejecutado durante el ensayo está marcado `sin probar` en la sección 9

Falla la ejecución si un paso cambia el estado sin entrada en la sección 6, o si algún paso se escribió sin ejecutarse y sin marcarse `sin probar`.

## Gestión de fallos

- **Sin acceso al sistema** — escribe el procedimiento a partir del material aportado, marca cada paso como `sin probar` y declara arriba que este manual no se ha ejecutado nunca. Di con claridad que hay que ensayarlo antes de confiar en él.
- **Un paso no se puede ensayar sin riesgo** — márcalo `sin probar` con el motivo, y escribe la verificación que quien opera debe esperar a partir de la definición del paso y no de una ejecución.
- **El procedimiento no tiene reversión** — dilo en la sección 6 en lugar de dejarla vacía, marca el paso como `IRREVERSIBLE` y añade la confirmación que quien opera debe hacer antes.
- **Sin estructura de escalado** — escribe `desconocido` en la sección 7 y lístalo como bloqueante. Un manual que termina en un paso fallido y sin ruta hacia adelante deja tirada a la persona que lo sigue.
- **Versiones enfrentadas del procedimiento** — registra cada una con su fuente, marca el punto como `en disputa` y no las fundas en una sola secuencia. Un procedimiento fundido que nadie ha ejecutado es peor que dos que alguien sí ha ejecutado.