poorvith-mp/skills-writing

sop-writing

Philosophie Fondamentale

Une procédure opérationnelle standardisée (SOP) n'est pas un essai théorique ou un document politique ambitieux. Une SOP est un runbook algorithmique exécutable pour des opérateurs humains ou agents. Une bonne SOP est conçue pour qu'un opérateur qualifié, sous stress extrême à 3h du matin, puisse exécuter le processus avec zéro ambiguïté, zéro supposition et zéro erreur catastrophique. Chaque étape doit avoir des entrées déterministes, des actions physiques numérotées, des critères d'acceptation observables et des chemins d'escalade explicites.

---

Architecture en 4 Étapes de la Procédure Opérationnelle Standardisée (SOP)

Étape 1 : Périmètre, Gouvernance & Prérequis de Pré-Vol

1. En-tête de Métadonnées et Propriété :
   • ID SOP, Version (SemVer), Date d'Effet, Cadence de Révision (Annuelle/Semestrielle), Propriétaire du Processus Responsable.
2. Délimitation Stricte de l'Objectif et du Périmètre :
   • Exactement ce que cette procédure couvre, et ce qu'elle ne couvre pas.
3. Prérequis et Permissions d'Accès :
   • Lister les identifiants requis, l'accès VPN, les paquets logiciels et les variables d'environnement avant la première étape d'exécution.

Étape 2 : La Séquence d'Étapes Numérotées Déterministe

1. Verbes d'Action Impératifs et Non Ambiguës :
   • Commencez chaque étape par un verbe actif : Cliquer, Exécuter, Vérifier, Copier, Exporter, Contrôler.
   • N'écrivez jamais de directives passives : « S'assurer que les journaux sont consultés. »
   • Écrivez : « 1. Ouvrir le tableau de bord Datadog Prod-Ingestion. 2. Inspecter le graphique p99 Latency. 3. Vérifier que la valeur est inférieure à 200ms. »
2. Hygiène des Commandes Copier-Coller :
   • Fournissez les commandes CLI exactes ou les extraits de code dans des blocs de code. Ne faites jamais deviner les noms de drapeaux ou les paramètres à l'opérateur.

Étape 3 : Vérification Observable et Points de Contrôle d'Acceptation

1. Le Contrôle « Comment Savoir Si Ça a Fonctionné ? » :
   • Chaque étape majeure doit spécifier son résultat attendu :
     • « Résultat Attendu : Le terminal affiche Déploiement Terminé : 12/12 pods sains. »
2. Arbres de Décision et Logique de Ramification :
   • Formatez la logique conditionnelle clairement :
     • Si statut == 200 : Passer à l'Étape 4.
     • Si statut == 500 : Aller à la Section de Dépannage 5.1.

Étape 4 : Gestion des Échecs, Retour Arrière et Chemins d'Escalade

1. Le Runbook de Retour Arrière :
   • Si la procédure échoue en cours de route, fournissez les commandes de retour arrière exactes pour restaurer le système dans un état de référence sûr.
2. SLA d'Escalade et Matrice de Contacts :
   • Qui contacter, sur quel canal, avec quelle sévérité, si la procédure ne peut pas être terminée dans les 15 minutes.

---

Format Livrable : Procédure Opérationnelle Standardisée de Production (SOP-TEMPLATE.md)

# Procédure Opérationnelle Standardisée : Déploiement de Correctif de Production
*ID SOP : SOP-ENG-042 | Version : v2.1.0 | Propriétaire : Responsable de l'Ingénierie des Plateformes*
*Date d'Effet : [AAAA-MM-JJ] | Cadence de Révision : Trimestrielle*

## 1. Objectif et Périmètre
Cette procédure régit le déploiement de correctifs d'urgence sur les clusters de production en dehors du cycle de publication CI/CD hebdomadaire standard.

## 2. Prérequis et Exigences d'Accès
- Rôle IAM AWS de Production `arn:aws:iam::123456789012:role/EmergencyDeployer`
- GitHub CLI (`gh`) authentifié avec un accès en écriture au dépôt
- AWS CLI v2 et `kubectl` configurés localement

## 3. Séquence d'Exécution Étape par Étape

### Étape 1 : Isolation et Vérification de la Branche
1. Extraire la branche de correctif depuis `main` :
   ```bash
   git checkout main && git pull origin main
   git checkout -b hotfix/SEC-[IssueNum]

2. Exécuter la suite de tests complète localement :

   npm run test:ci
   

   • Contrôle d'Acceptation : Code de sortie 0 ; toutes les suites de tests réussissent.

Étape 2 : Construction et Étiquetage de l'Image Conteneur

1. Déclencher le pipeline de construction de correctif automatisé :

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

   • Résultat Attendu : GitHub Actions émet le digest de l'image sha256:....

Étape 3 : Déploiement en Production et Vérification Canary

1. Appliquer le déploiement au pool de pods Canary (10% du trafic) :

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

2. Surveiller les taux d'erreur pendant 5 minutes :
   • Consulter le tableau de bord Grafana https://grafana.internal/d/canary-health.
   • Point de Contrôle d'Acceptation : Le taux d'erreur 5xx doit rester inférieur à 0,01%.

4. Retour Arrière et Plan de Contingence

Si le taux d'erreur Canary dépasse 0,05% :

1. Revenir immédiatement au déploiement précédent :

   kubectl rollout undo deployment/api-gateway -n production
   

2. Notifier le Commandant des Incidents sur Slack #incident-war-room.

5. Contacts d'Escalade

• SRE de Période Principale : Calendrier PagerDuty sre-tier-1
• VP Ingénierie : Téléphone : [Numéro] (Contacter si l'interruption dépasse 15 minutes)

---

## Exemple Travailé : SOP de Restauration de Base de Données

- **Contexte** : Runbook de récupération pour la restauration d'un instantané de base de données PostgreSQL chiffré.
- **Impact** : Une SOP étape par étape a permis à un ingénieur junior en rotation de nuit de restaurer une table client supprimée accidentellement en 11 minutes sans aucune corruption de données.

---

## Liste de Vérification

- [ ] Chaque étape procédurale commence par un verbe impératif actif.
- [ ] Les commandes et extraits de code sont 100% copiables avec une syntaxe exacte.
- [ ] Le résultat observable attendu est spécifié pour chaque étape critique.
- [ ] Des procédures de retour arrière explicites sont documentées pour les exécutions ayant échoué.
- [ ] La matrice de contacts d'escalade comprend des rôles nommés et les canaux de paging.

---

## Anti-Patterns

- **Instructions Ambiguës** : Écrire « Configurer le réseau correctement » au lieu de fournir les tables IP ou la configuration YAML exactes.
- **Runbook de Retour Arrière Manquant** : Expliquer comment pousser un changement sans expliquer comment le révoquer s'il casse quelque chose.
- **Runbooks Non Testés** : Écrire une SOP de reprise après sinistre d'urgence qui n'a jamais été testée à blanc dans un environnement de préproduction.