poorvith-mp/skills-writing

sop-writing

Filosofía Central

Un Procedimiento Operativo Estándar (SOP) no es un ensayo teórico ni un documento de política aspiracional. Un SOP es un runbook algorítmico ejecutable para operadores humanos o agentes. Un gran SOP está diseñado para que un operador calificado bajo estrés extremo a las 3:00 a. m. pueda ejecutar el proceso con cero ambigüedad, cero conjeturas y cero errores catastróficos. Cada paso debe tener entradas deterministas, acciones físicas numeradas, criterios de aceptación observables y rutas de escalación explícitas.

---

Arquitectura de Procedimiento Operativo Estándar (SOP) en 4 Pasos

Paso 1: Alcance, Gobierno y Requisitos Previos al Vuelo

1. Metadatos y Encabezado de Propiedad:
   • ID del SOP, Versión (SemVer), Fecha de Vigencia, Cadencia de Revisión (Anual/Semestral), Propietario del Proceso Responsable.
2. Límites Estrictos de Propósito y Alcance:
   • Exactamente qué cubre este procedimiento, y qué no cubre.
3. Requisitos y Permisos de Acceso:
   • Liste las credenciales necesarias, acceso VPN, paquetes de software y variables de entorno antes del primer paso de ejecución.

Paso 2: La Secuencia Determinista de Pasos Numerados

1. Verbos de Acción Imperativos e Inequívocos:
   • Comience cada paso con un verbo activo: Hacer clic, Ejecutar, Verificar, Copiar, Exportar, Revisar.
   • Nunca escriba pautas pasivas: "Asegurarse de que se revisen los registros."
   • Escriba: "1. Abra el panel de Datadog Prod-Ingestion. 2. Inspeccione el gráfico p99 Latency. 3. Verifique que el valor sea inferior a 200 ms."
2. Higiene de Comandos para Copiar y Pegar:
   • Proporcione comandos CLI exactos o fragmentos de código en bloques con formato. Nunca haga que los operadores adivinen nombres de banderas o parámetros.

Paso 3: Verificación Observable y Puertas de Aceptación

1. La Verificación "¿Cómo sé que funcionó?":
   • Cada paso importante debe especificar su salida esperada:
     • "Salida esperada: La terminal muestra Implementación Completa: 12/12 pods saludables."
2. Árboles de Decisión y Lógica de Ramificación:
   • Formatee la lógica condicional claramente:
     • Si estado == 200: Proceda al Paso 4.
     • Si estado == 500: Vaya a la Sección de Solución de Problemas 5.1.

Paso 4: Manejo de Fallos, Reversión y Rutas de Escalación

1. El Runbook de Reversión:
   • Si el procedimiento falla a medio camino, proporcione comandos de reversión exactos para restaurar el sistema a un estado base seguro.
2. SLA de Escalación y Matriz de Contacto:
   • A quién contactar, en qué canal, con qué gravedad, si el procedimiento no se puede completar dentro de los 15 minutos.

---

Formato del Entregable: Procedimiento Operativo Estándar de Producción (SOP-TEMPLATE.md)

# Procedimiento Operativo Estándar: Implementación de Hotfix de Producción
*ID del SOP: SOP-ENG-042 | Versión: v2.1.0 | Propietario: Líder de Ingeniería de Plataforma*
*Fecha de Vigencia: [AAAA-MM-DD] | Cadencia de Revisión: Trimestral*

## 1. Propósito y Alcance
Este procedimiento rige la implementación de hotfixes de emergencia en clústeres de producción fuera del ciclo de lanzamiento semanal estándar de CI/CD.

## 2. Requisitos y Permisos de Acceso
- Rol de IAM de AWS de Producción `arn:aws:iam::123456789012:role/EmergencyDeployer`
- CLI de GitHub (`gh`) autenticada con acceso de escritura al repositorio
- AWS CLI v2 y `kubectl` configurados localmente

## 3. Secuencia de Ejecución Paso a Paso

### Paso 1: Aislamiento y Verificación de la Rama
1. Cambie a la rama hotfix desde `main`:
   ```bash
   git checkout main && git pull origin main
   git checkout -b hotfix/SEC-[IssueNum]

2. Ejecute la suite de pruebas completa localmente:

   npm run test:ci
   

   • Verificación de aceptación: Código de salida 0; todas las suites de pruebas pasan.

Paso 2: Construcción y Etiquetado de la Imagen del Contenedor

1. Active el pipeline de compilación de hotfix automatizado:

   gh workflow run hotfix-build.yml -f branch=hotfix/SEC-[IssueNum]
   

   • Salida esperada: GitHub Actions emite el digest de la imagen sha256:....

Paso 3: Despliegue en Producción y Verificación Canary

1. Aplique el despliegue al grupo de pods Canary (10% del tráfico):

   kubectl set image deployment/api-gateway api=ecr.internal/api:[Digest] -n production
   

2. Supervise las tasas de error durante 5 minutos:
   • Revise el panel de Grafana https://grafana.internal/d/canary-health.
   • Puerta de aceptación: La tasa de error 5xx debe permanecer < 0.01%.

4. Plan de Reversión y Contingencia

Si la tasa de error Canary supera el 0.05%:

1. Revierta el despliegue inmediatamente:

   kubectl rollout undo deployment/api-gateway -n production
   

2. Notifique al Comandante de Incidentes en Slack #incident-war-room.

5. Contactos de Escalación

• SRE de Guardia Principal: Programación de PagerDuty sre-tier-1
• VP de Ingeniería: Teléfono: [Número] (Página si la interrupción supera los 15 minutos)

---

## Ejemplo Práctico: SOP de Restauración de Base de Datos

- **Contexto**: Runbook de recuperación para restauración de instantánea de base de datos PostgreSQL cifrada.
- **Impacto**: El SOP paso a paso permitió a un ingeniero junior en el turno nocturno restaurar una tabla de cliente eliminada accidentalmente en 11 minutos con cero corrupción de datos.

---

## Lista de Verificación

- [ ] Cada paso del procedimiento comienza con un verbo imperativo activo.
- [ ] Los comandos y fragmentos de código son 100% copiables y pegables con sintaxis exacta.
- [ ] La salida observable esperada está especificada para cada paso crítico.
- [ ] Se documentan procedimientos de reversión explícitos para ejecuciones fallidas.
- [ ] La matriz de contacto de escalación incluye roles nombrados y canales de notificación.

---

## Anti-patrones

- **Instrucciones Ambiguas**: Escribir "Configure la red correctamente" en lugar de proporcionar las tablas IP exactas o la configuración YAML.
- **Runbook de Reversión Faltante**: Explicar cómo enviar un cambio sin explicar cómo revertirlo si se rompe.
- **Runbooks No Probados**: Escribir un SOP de recuperación ante desastres de emergencia que nunca se haya ejecutado en seco en un entorno de pruebas.