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]

bashCopy code
# 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:

bashCopy code
[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]

bashCopy code
[comando de reversión]

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

Resolución de Problemas

Escalada

Si este runbook no resuelve el problema:

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