Recette : Correction de bug avec le SDD

Cette recette montre comment utiliser SpecForge pour documenter, cadrer et résoudre un bug d'une façon qui crée une spec durable — pour que la même catégorie de bug ne passe plus jamais en production.

Pourquoi documenter les bugs comme des specs ?

La plupart des bugs récurrent parce que le comportement correct n'a jamais été formellement spécifié. Corriger un bug sans spec signifie :

• Le correctif n'a pas de critères d'acceptation (comment savoir qu'il est corrigé ?)
• Le test de régression n'a pas de traçabilité
• Le même pattern peut réapparaître dans du code connexe

Le SDD traite les bugs comme des specs manquantes ou incorrectes. Corriger le bug signifie écrire la spec qui aurait dû exister, puis implémenter pour y correspondre.

---

Scénario

Les utilisateurs signalent que passer deux commandes simultanément entraîne parfois des doubles débits. Il s'agit d'un bug de concurrence dans le flux de passage de commande.

---

Étape 1 — Clarifier le bug

Prompt :

Utilise specforge pour clarifier les exigences d'un correctif de bug :
doubles débits lors du passage de commandes simultanées dans le projet proj_abc123

SpecForge posera :

• Où se produit la duplication — couche API, processeur de paiement ou BDD ?
• Est-ce reproductible dans des conditions spécifiques (charge, délai réseau) ?
• Quel est le comportement attendu — exactement un débit par commande, toujours ?
• Existe-t-il des tests existants qui auraient dû détecter cela ?

---

Étape 2 — Créer une spec de correctif de bug

Prompt :

Crée une spec pour corriger le bug de double débit dans le passage de commande pour le projet proj_abc123.
Cause racine : race condition dans OrderService.placeOrder — pas de clé d'idempotence sur l'appel Stripe.
Comportement attendu : exactement un débit par commande quelles que soient les requêtes concurrentes.

Ce que contiendra la spec :

## Critères d'acceptation

1. Passer la même commande deux fois de façon concurrente résulte en exactement un débit Stripe
2. La deuxième requête concurrente reçoit une réponse 409 Conflict avec l'identifiant de commande
3. La clé d'idempotence est dérivée du orderId et stockée dans la table orders
4. Les commandes existantes ne peuvent pas être modifiées après l'initiation du paiement
5. Un test d'intégration couvre le passage de commande concurrent avec 10 requêtes simultanées
6. Un test unitaire couvre les cas limites de génération de clé d'idempotence (UUID v4, résistance aux collisions)

---

Étape 3 — Tester la conception du correctif sous pression

Prompt :

Challenge la spec SPEC-BUG-001 pour le projet proj_abc123

SpecForge sonder :

• Que se passe-t-il si la génération de la clé d'idempotence elle-même a une race condition ?
• Que se passe-t-il si la première requête échoue en plein vol — la deuxième réussit-elle ?
• Quelle est la politique d'expiration des clés d'idempotence ?
• Le correctif gère-t-il le cas où le paiement réussit mais l'écriture en BDD échoue ?

---

Étape 4 — Vérification de sécurité

Prompt :

Lance une vérification de sécurité sur la spec SPEC-BUG-001 pour le projet proj_abc123

Les bugs de paiement concurrents ont souvent des implications de sécurité — assurez-vous que le correctif n'introduit pas de vulnérabilité TOCTOU.

---

Étape 5 — Rétro-ingénierer le code existant

Documenter ce que le code actuel (buggé) fait réellement :

Prompt :

Rétro-ingénieure le code dans /Users/moi/mon-app/src/orders/OrderService.ts pour le projet proj_abc123

Cela crée une spec du comportement actuel — utile pour comprendre exactement où la spec et l'implémentation ont divergé.

---

Étape 6 — Générer les tests en premier (approche TDD)

Prompt :

Génère des tests pour la spec SPEC-BUG-001 dans le projet proj_abc123

Écrivez les tests de régression avant de toucher à l'implémentation. Cela garantit :

• Le bug est reproductible avec un test (rouge)
• Le correctif fait passer le test (vert)
• Le test reste dans la suite pour toujours (protection contre les régressions)

---

Étape 7 — Générer le plan d'exécution

Prompt :

Génère un plan d'exécution pour la spec SPEC-BUG-001 dans le projet proj_abc123

Pour un correctif de bug, le plan ressemble typiquement à :

## Phase 1 : Reproduire
- [ ] Écrire un test d'intégration échouant qui déclenche le double débit (RED)
- [ ] Confirmer que le test échoue contre l'implémentation actuelle

## Phase 2 : Corriger
- [ ] Ajouter la colonne idempotency_key à la table orders (migration)
- [ ] Générer la clé d'idempotence dans OrderService avant l'appel Stripe
- [ ] Stocker la clé de façon atomique avec la création de commande (transaction)
- [ ] Gérer le 409 de l'endpoint d'idempotence Stripe

## Phase 3 : Vérifier
- [ ] Exécuter le test d'intégration (GREEN)
- [ ] Exécuter la suite de tests complète
- [ ] Test manuel avec des requêtes concurrentes en mode test Stripe

---

Étape 8 — Implémenter et valider

Après avoir implémenté le correctif :

Prompt :

Valide la spec SPEC-BUG-001 contre le code dans /Users/moi/mon-app/src pour le projet proj_abc123

Assurez-vous que les 6 critères d'acceptation sont couverts par l'implémentation et les tests.

---

Étape 9 — Détecter le drift par rapport à la spec originale

S'il existe une SPEC pour le flux de passage de commande, vérifiez si le correctif a introduit du drift :

Prompt :

Détecte le drift dans la spec SPEC-002 (passage de commande) pour le projet proj_abc123

Le correctif devra peut-être être reflété dans la spec originale comme nouveau critère : "Le système doit utiliser des clés d'idempotence pour tous les appels API Stripe."

---

Étape 10 — Capturer l'apprentissage

Prompt :

Capture learning : les appels API de fournisseur de paiement doivent toujours inclure des clés d'idempotence dérivées de l'identifiant d'entité métier, jamais depuis des UUID générés par requête

Ce pattern est maintenant stocké et influencera les futures specs impliquant des appels API de paiement.

---

Résultat de cette recette

À la fin :

• Une spec de correctif de bug (SPEC-BUG-001) avec des critères d'acceptation complets
• Des tests de régression avec traçabilité à chaque critère
• La spec originale mise à jour pour refléter le comportement correct
• Un apprentissage capturé qui empêche le pattern de récidiver
• Une piste d'audit : quand le bug a été trouvé, quel était le correctif, pourquoi c'était le bon correctif