runbook-writer

Habilidad Runbook Writer

Produce runbooks operacionales para servicios, tipos de incidentes y procedimientos de despliegue — estructurados de modo que un ingeniero on-call que nunca ha tocado el sistema pueda seguirlos bajo presión.

Entradas Requeridas

Pide esto si no se proporciona:

• Para qué es el runbook (p. ej. desplegar el servicio de pagos, responder a un failover de base de datos, rotar claves de API)
• Tipo de runbook (Despliegue / Respuesta a Incidentes / Mantenimiento / Recuperación ante Desastres)
• Nombre del sistema/servicio y qué hace (breve descripción)
• Audiencia (ingenieros on-call nuevos / SREs experimentados / equipo DevOps)
• Stack tecnológico (donde sea relevante — p. ej. Kubernetes, AWS RDS, Node.js)
• Herramientas de monitoreo (p. ej. Grafana, Datadog, CloudWatch, Splunk — se usan para nombrar dashboards específicos y enlaces de alertas en los pasos)
• Detalles clave del entorno (p. ej. nombre del cluster de Kubernetes, cuenta/región de AWS, namespaces o nombres de recursos relevantes — pega lo que sea relevante para comandos exactos)

Formato de Salida

---

Runbook: [Título del Runbook]

Servicio: [Nombre del Servicio]

Tipo: [Despliegue / Respuesta a Incidentes / Mantenimiento / Recuperación ante Desastres]

Última Actualización: [Insertar la fecha de hoy en formato YYYY-MM-DD]

Propietario: [Equipo o persona]

Severidad: [P1 / P2 / P3 — si es tipo incidente]

---

Descripción General

Qué cubre este runbook:

[1–2 frases sobre el escenario que maneja este runbook]

Cuándo usar este runbook:

• [Condición de disparo específica 1 — p. ej. Alerta PagerDuty: high-error-rate-payment-service]
• [Condición de disparo específica 2 — p. ej. Despliegue necesario después de PR fusionado a main]

Tiempo estimado para completar: [X minutos / X–Y minutos dependiendo del resultado]

Impacto si no se completa correctamente: [p. ej. Procesamiento de pagos degradado / Riesgo de pérdida de datos / Usuarios bloqueados]

---

Requisitos Previos

Acceso requerido:

• [ ] [Acceso a sistema/herramienta — p. ej. Consola AWS: production-account]
• [ ] [Credencial — p. ej. vault read secret/payment-service]
• [ ] [Acceso VPN / bastion si es necesario]

Herramientas requeridas:

• [ ] [Nombre de la herramienta y versión — p. ej. kubectl v1.28+]
• [ ] [Nombre del CLI o dashboard]

Antes de empezar:

• [ ] [Verificación de requisito previo — p. ej. Verifica que el despliegue actual sea saludable en Grafana]
• [ ] [Acción de requisito previo — p. ej. Anuncia en #ops-live que estás comenzando]

---

Procedimiento

Enumera cada paso. Usa comandos exactos. No parafrasees nombres de herramientas o flags.

Paso 1: [Nombre de la acción]

[Qué estás haciendo y por qué — una oración]

# Comando exacto
[comando aquí]

Salida esperada: [qué debería aparecer si esto funcionó]

Si esto falla: [Mensaje de error exacto a buscar] → [Qué hacer, o ver Resolución de Problemas]

Paso 2: [Nombre de la acción]

[Misma estructura que el Paso 1]

Paso 3: Verificar

Siempre incluye un paso de verificación después del procedimiento principal:

[comando de verificación]

Estado esperado: [Cómo se ve un sistema saludable después de completar este runbook]

---

Reversión

Cómo deshacer este procedimiento si algo salió mal:

Paso R1: [Acción de reversión]

[comando de reversión]

Verificar reversión: [comando para confirmar que la reversión fue exitosa]

---

Resolución de Problemas

| Síntoma | Causa Probable | Resolución |

|---|---|---|

| [Mensaje de error u síntoma observable] | [Por qué sucede esto] | [Solución exacta o próximo paso] |

| [Otro síntoma] | [Causa] | [Resolución] |

---

Escalada

Si este runbook no resuelve el problema:

| Condición | A Quién Contactar | Cómo |

|---|---|---|

| [p. ej. DB no disponible después de 10 min] | [DBA on-call] | [Política PagerDuty: db-oncall] |

| [p. ej. Proveedor de pagos sin respuesta] | [Contacto del proveedor] | [Contacto en 1Password: vendor-escalation] |

Siempre actualiza la línea de tiempo del incidente en [herramienta] antes de escalar.

---

Lista de Verificación Post-Procedimiento

Después de completar el runbook:

• [ ] Anuncia el final en #ops-live con el resultado
• [ ] Actualiza el ticket de incidente / log de despliegue
• [ ] Verifica que las alertas se hayan resuelto en el dashboard de monitoreo
• [ ] Si esto reveló una brecha en este runbook — actualízalo ahora (enlace al proceso de edición)

---

Verificaciones de Calidad

• [ ] Cada paso tiene un comando exacto (no "ejecuta el script de despliegue")
• [ ] La salida esperada se especifica para cada paso para que el ingeniero sepa si funcionó
• [ ] La ruta de fallo es explícita para cada paso (no "si falla, investiga")
• [ ] El procedimiento de reversión es completo e independientemente testeable
• [ ] La tabla de escalada no tiene celdas que contengan solo "[Nombre del equipo]" — cada fila debe tener un contacto real o estar explícitamente marcada como [COMPLETAR: enlace de rotación on-call]
• [ ] La sección de reversión contiene al menos un comando concreto (no dejado como marcador "[rollback command]")
• [ ] El runbook puede ser seguido por alguien que nunca ha tocado este sistema

Ejemplos de Uso

• "Escribe un runbook para [servicio] despliegue"
• "Crea un runbook de respuesta a incidentes para [tipo de alerta]"
• "Necesito un runbook para [procedimiento]"
• "Documenta el procedimiento operacional para [X]"
• "Escribe un playbook de ops para [escenario]"

Anti-Patrones

• [ ] No escribas pasos como acciones vagas como "ejecuta el script de despliegue" — cada paso debe incluir el comando exacto
• [ ] No dejes la sección de reversión como un marcador — un runbook sin un procedimiento de reversión testado es incompleto y peligroso
• [ ] No omitas la salida esperada para cada paso — sin ella, el ingeniero on-call no puede saber si el paso fue exitoso
• [ ] No escribas contactos de escalada como "[Nombre del equipo]" — cada fila de escalada debe tener un contacto real o una marca explícita para completar
• [ ] No asumas que el lector conoce el sistema — escribe para alguien que nunca lo ha tocado antes