Briser la Boucle – Analyse Approfondie des Bogues
Lorsque le débogage est terminé, utilisez ceci pour une analyse approfondie afin de briser le cycle « corriger le bogue -> oublier -> répéter ».
Cadre d'Analyse
Analysez le bogue que vous venez de corriger selon ces 5 dimensions :
1. Catégorie de Cause Racine
À quelle catégorie ce bogue appartient-il ?
| Catégorie | Caractéristiques | Exemple |
|---|---|---|
| A. Spécification Manquante | Aucune documentation sur comment faire | Nouvelle fonctionnalité sans liste de contrôle |
| B. Contrat Inter-Couches | Interface entre couches peu claire | L'API renvoie un format différent de celui attendu |
| C. Échec de Propagation de Changement | Changé un endroit, manqué d'autres | Changé la signature d'une fonction, manqué les sites d'appel |
| D. Lacune de Couverture de Test | Le test unitaire passe, l'intégration échoue | Fonctionne seul, échoue lorsqu'il est combiné |
| E. Hypothèse Implicite | Le code repose sur une hypothèse non documentée | Secondes vs millisecondes pour timestamp |
2. Pourquoi les Corrections Ont-elles Échoué (si applicable)
Si vous avez essayé plusieurs corrections avant de réussir, analysez chaque échec :
- Correction Superficielle : A corrigé le symptôme, pas la cause racine
- Périmètre Incomplet : A trouvé la cause racine, n'a pas couvert tous les cas
- Limitation de l'Outil : grep a manqué, la vérification de type n'était pas stricte
- Modèle Mental : A continué à chercher dans la même couche, n'a pas pensé inter-couche
3. Mécanismes de Prévention
Quels mécanismes empêcheraient que cela se reproduise ?
| Type | Description | Exemple |
|---|---|---|
| Documentation | Écrire pour que les gens sachent | Mettre à jour le guide de réflexion |
| Architecture | Rendre l'erreur structurellement impossible | Wrappers typés sécurisés |
| Compilation | Vérification de type stricte, sans échappatoires | Un changement de signature provoque une erreur de compilation |
| Exécution | Surveillance, alertes, scans | Détection d'entités orphelines |
| Couverture de Test | Tests E2E, tests d'intégration | Vérifier le flux complet |
| Revue de Code | Liste de contrôle, modèle de PR | « Avez-vous vérifié X ? » |
4. Extension Systématique
Quels problèmes plus larges ce bogue révèle-t-il ?
- Problèmes Similaires : Où d'autre ce problème pourrait-il exister ?
- Défaut de Conception : Y a-t-il un problème d'architecture fondamental ?
- Défaut de Processus : Y a-t-il une amélioration du processus de développement ?
- Lacune de Connaissance : L'équipe manque-t-elle d'une certaine compréhension ?
5. Capture des Connaissances
Solidifiez les informations dans le système :
- Mettre à jour les guides de réflexion
.trellis/spec/guides/ - Mettre à jour les documents
.trellis/spec/pertinents - Créer un enregistrement de ticket (si applicable)
- Créer un ticket de fonctionnalité pour la correction racine
- Mettre à jour les directives de vérification si nécessaire
Format de Sortie
Veuillez produire l'analyse dans ce format :
## Analyse du Bogue : [Description Courte]
### 1. Catégorie de Cause Racine
- **Catégorie** : [A/B/C/D/E] - [Nom de la Catégorie]
- **Cause Spécifique** : [Description détaillée]
### 2. Pourquoi les Corrections Ont-elles Échoué (si applicable)
1. [Première tentative] : [Pourquoi a-t-elle échoué]
2. [Deuxième tentative] : [Pourquoi a-t-elle échoué]
...
### 3. Mécanismes de Prévention
| Priorité | Mécanisme | Action Spécifique | Statut |
|----------|-----------|-------------------|--------|
| P0 | ... | ... | TODO/FAIT |
### 4. Extension Systématique
- **Problèmes Similaires** : [Liste des endroits avec des problèmes similaires]
- **Amélioration de Conception** : [Suggestions au niveau de l'architecture]
- **Amélioration de Processus** : [Suggestions pour le processus de développement]
### 5. Capture des Connaissances
- [ ] [Documents à mettre à jour / tickets à créer]
Philosophie Centrale
La valeur du débogage n'est pas de corriger le bogue, mais de faire en sorte que cette classe de bogues ne se reproduise jamais.
Trois niveaux de perspicacité :
- Tactique : Comment corriger CE bogue
- Stratégique : Comment empêcher CETTE CLASSE de bogues
- Philosophique : Comment élargir les schémas de pensée
30 minutes d'analyse permettent d'économiser 30 heures de débogage futur.
Cadre de Réflexion : Raisonnement Bayésien
Lorsque plusieurs causes racines sont plausibles et que les preuves sont incomplètes, mettez à jour vos croyances proportionnellement aux nouvelles preuves plutôt que de vous accrocher aux hypothèses initiales.
Étape 1 : Établir les A Priori
Avant d'enquêter, énoncez ce que vous croyez et pourquoi :
| Hypothèse | A Priori | Raisonnement |
|---|---|---|
| H1 : [cause A] | 40 % | La plus courante pour ce schéma |
| H2 : [cause B] | 30 % | Plausible compte tenu de l'environnement |
| H3 : [autre] | 30 % | Catégorie fourre-tout |
Les a priori doivent totaliser 100 %. Si vous ne pouvez pas attribuer de probabilités, enquêtez d'abord.
Étape 2 : Observer les Preuves
Documentez ce que vous avez trouvé — soyez précis sur la fiabilité :
- Qu'avez-vous observé exactement ?
- Quelle est sa fiabilité ? (sortie de test > message de log > rapport utilisateur > intuition)
- Plusieurs hypothèses pourraient-elles expliquer cela ?
Étape 3 : Mettre à Jour les Croyances
Pour chaque hypothèse, demandez : Quelle est la probabilité de cette preuve si cette hypothèse était vraie ?
La direction de la mise à jour importe plus que le calcul :
- Preuve fortement prédite par H1 → La probabilité de H1 augmente
- Preuve contredit H2 → La probabilité de H2 diminue
- Preuve également probable sous toutes les hypothèses → aucune mise à jour
Étape 4 : Rechercher des Preuves Discriminantes
Ne recueillez pas plus de la même chose. Trouvez des preuves qui diffèrent fortement entre les hypothèses principales.
Si H1 et H3 sont proches : « Que verrais-je si H1 est vrai mais pas si H3 est vrai ? » Vérifiez ensuite cela.
Étape 5 : Énoncer la Confiance
| Confiance | Action |
|---|---|
| 90 %+ | Procéder à la correction, surveiller |
| 70-90 % | Procéder, ajouter une vérification de repli |
| 50-70 % | Tester l'hypothèse avant de s'engager |
| <50 % | Besoin de plus de preuves, ne pas deviner |
N'exprimez jamais une certitude binaire lorsque les preuves sont incomplètes. Utilisez « très probablement », « plausible mais peu probable », « vaut la peine d'être investigué ».
Erreurs Courantes
| Erreur | Exemple | Correction |
|---|---|---|
| Négligence du taux de base | « Le test a échoué → le code est cassé » | À quelle fréquence les tests échouent-ils pour d'autres raisons ? |
| Biais de confirmation | « Ce doit être une condition de course, trouvons des preuves de course » | Cherchez activement des preuves CONTRE votre hypothèse principale |
| Ancrage | « La dernière fois c'était le cache, probablement encore le cache » | Établissez des a priori à partir du contexte actuel, pas du bogue d'hier |
Après l'Analyse : Actions Immédiates
IMPORTANT : Après avoir terminé l'analyse ci-dessus, vous DEVEZ immédiatement :
-
Mettre à jour spec/guides - Ne vous contentez pas de lister les tâches, mettez à jour les fichiers pertinents :
- S'il s'agit d'un problème multiplateforme → mettre à jour
cross-platform-thinking-guide.md - S'il s'agit d'un problème inter-couches → mettre à jour
cross-layer-thinking-guide.md - S'il s'agit d'un problème de réutilisation de code → mettre à jour
code-reuse-thinking-guide.md - S'il est spécifique à un domaine → mettre à jour
backend/*.mdoufrontend/*.md
- S'il s'agit d'un problème multiplateforme → mettre à jour
-
Synchroniser les modèles - Après avoir mis à jour
.trellis/spec/, synchroniser verssrc/templates/markdown/spec/ -
Valider les mises à jour des spécifications - C'est le résultat principal, pas seulement le texte d'analyse
L'analyse ne vaut rien si elle reste dans la conversation. La valeur réside dans les spécifications mises à jour.