Débogage systématique

Présentation

Les corrections aléatoires font perdre du temps et créent de nouveaux bugs. Les correctifs rapides ne font que masquer les problèmes sous-jacents.

Principe fondamental : il faut TOUJOURS identifier la cause première avant de tenter toute correction. Se contenter de corriger les symptômes est voué à l'échec.

Enfreindre la lettre de ce processus revient à enfreindre l’esprit même du débogage.

La règle d’or

PAS DE CORRECTION SANS ENQUÊTE PRÉALABLE SUR LA CAUSE PROFONDE

Si vous n’avez pas terminé la phase 1, vous ne pouvez pas proposer de corrections.

Quand l'utiliser

À utiliser pour TOUT problème technique :

• Échecs de test
• Bugs en production
• Comportement inattendu
• Problèmes de performances
• Échecs de compilation
• Problèmes d'intégration

Utilisez cette option NOTAMMENT lorsque :

• Vous êtes pressé par le temps (les situations d’urgence incitent à agir à l’aveuglette)
• Une « solution rapide » semble évidente
• Vous avez déjà essayé plusieurs solutions
• La solution précédente n’a pas fonctionné
• Vous ne comprenez pas entièrement le problème

Ne passez pas à l’étape suivante lorsque :

• Le problème semble simple (les bugs simples ont eux aussi des causes profondes)
• Vous êtes pressé (la précipitation garantit des retouches)
• Votre responsable veut que le problème soit résolu IMMÉDIATEMENT (une approche systématique est plus rapide que de s’agiter dans tous les sens)

Les quatre phases

Vous DEVEZ mener à bien chaque phase avant de passer à la suivante.

Phase 1 : Recherche de la cause profonde

AVANT de tenter TOUTE correction :

1. Lisez attentivement les messages d'erreur

   • Ne passez pas outre les erreurs ou les avertissements
   • Ils contiennent souvent la solution exacte
   • Lisez intégralement les traces de pile
   • Notez les numéros de ligne, les chemins d'accès aux fichiers et les codes d'erreur

2. Reproduisez l'erreur de manière cohérente

   • Pouvez-vous reproduire le problème de manière fiable ?
   • Quelles sont les étapes exactes ?
   • Cela se produit-il à chaque fois ?
   • Si le problème n'est pas reproductible → recueillez davantage de données, ne vous fiez pas à des suppositions

3. Vérifier les modifications récentes

   • Quels changements ont pu provoquer cela ?
   • Git diff, commits récents
   • Nouvelles dépendances, modifications de configuration
   • Différences d'environnement

4. Recueillir des preuves dans les systèmes à composants multiples

   LORSQUE le système comporte plusieurs composants (CI → build → signature, API → service → base de données) :

   AVANT de proposer des corrections, ajoutez des outils de diagnostic :

   Pour CHAQUE limite de composant :
     - Enregistrer les données entrant dans le composant
     - Enregistrer les données sortant du composant
     - Vérifier la propagation de l’environnement et de la configuration
     - Vérifier l’état à chaque couche
   
   Exécuter une fois pour recueillir des preuves indiquant OÙ se produit la défaillance
   PUIS analyser les preuves pour identifier le composant défaillant
   PUIS examiner ce composant spécifique
   

   Exemple (système multicouche) :

   # Couche 1 : Workflow
   echo "=== Secrets disponibles dans le workflow : ==="
   echo "IDENTITY : ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   
   # Couche 2 : script de compilation
   echo "=== Variables d’environnement dans le script de compilation : ==="
   env | grep IDENTITY || echo "IDENTITY absent de l’environnement"
   
   # Couche 3 : script de signature
   echo "=== État du trousseau : ==="
   security list-keychains
   security find-identity -v
   
   # Couche 4 : signature proprement dite
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   

   Cela permet de déterminer : quelle couche échoue (secrets → workflow ✓, workflow → compilation ✗)

5. Suivi du flux de données

   LORSQUE l’erreur se trouve profondément dans la pile d’appels :

   Consultez le fichier root-cause-tracing.md dans ce répertoire pour découvrir la technique complète de traçage en amont.

   Version rapide :

   • D’où provient la valeur erronée ?
   • Qu'est-ce qui a appelé cette fonction avec cette valeur erronée ?
   • Continuez à remonter la piste jusqu’à ce que vous trouviez la source
   • Corrigez le problème à la source, pas au niveau du symptôme

Phase 2 : Analyse des schémas

Identifiez le schéma avant de corriger :

1. Trouvez des exemples qui fonctionnent

   • Repérez du code fonctionnel similaire dans la même base de code
   • Qu'est-ce qui fonctionne et qui est similaire à ce qui ne fonctionne pas ?

2. Comparez avec les références

   • Si vous implémentez un modèle, lisez l'implémentation de référence DANS SON INTÉGRALITÉ
   • Ne vous contentez pas de survoler le texte : lisez chaque ligne
   • Comprenez parfaitement le modèle avant de l'appliquer

3. Identifiez les différences

   • Qu'est-ce qui différencie une implémentation qui fonctionne d'une qui ne fonctionne pas ?
   • Énumérez toutes les différences, aussi minimes soient-elles
   • Ne partez pas du principe que « ça n’a pas d’importance »

4. Comprenez les dépendances

   • De quels autres composants cela a-t-il besoin ?
   • Quels paramètres, quelle configuration, quel environnement ?
   • Sur quelles hypothèses repose-t-il ?

Phase 3 : Hypothèses et tests

Méthode scientifique :

1. Formuler une hypothèse unique

   • Formuler clairement : « Je pense que X est la cause première parce que Y »
   • Notez-la par écrit
   • Soyez précis, ne restez pas vague

2. Tester de manière minimale

   • Apportez la plus PETITE modification possible pour tester l’hypothèse
   • Une variable à la fois
   • Ne corrigez pas plusieurs éléments à la fois

3. Vérifiez avant de continuer

   • Ça a marché ? Oui → Phase 4
   • Ça n’a pas fonctionné ? Formulez une NOUVELLE hypothèse
   • N'ajoutez PAS d'autres corrections par-dessus

4. Quand vous ne comprenez pas

   • Dites « Je ne comprends pas X »
   • Ne faites pas semblant de savoir
   • Demandez de l'aide
   • Faites des recherches supplémentaires

Phase 4 : Mise en œuvre

Traitez la cause profonde, pas le symptôme :

1. Créez un cas de test défaillant

   • Reproduction la plus simple possible
   • Test automatisé si possible
   • Script de test ponctuel en l’absence de framework
   • À réaliser IMPÉRATIVEMENT avant toute correction
   • Utiliser la compétence « superpowers:test-driven-development » pour écrire des tests échouant correctement

2. Mettre en œuvre une correction unique

   • Traiter la cause première identifiée
   • UNE modification à la fois
   • Pas d’améliorations du type « tant que j’y suis »
   • Pas de refactorisation groupée

3. Vérifier la correction

   • Le test est-il réussi maintenant ?
   • Aucun autre test n'est-il défaillant ?
   • Le problème est-il réellement résolu ?

4. Si la correction ne fonctionne pas

   • ARRÊTEZ
   • Nombre : combien de solutions avez-vous essayées ?
   • Si < 3 : revenez à la phase 1, réanalysez en tenant compte des nouvelles informations
   • Si ≥ 3 : ARRÊTEZ et remettez en question l'architecture (étape 5 ci-dessous)
   • N'essayez PAS la solution n° 4 sans discussion sur l'architecture

5. Si 3 solutions ou plus ont échoué : remettez en question l’architecture

   Modèle indiquant un problème d’architecture :

   • Chaque solution révèle un nouvel état partagé, un nouveau couplage ou un nouveau problème à un endroit différent
   • Les solutions nécessitent une « refactorisation massive » pour être mises en œuvre
   • Chaque solution crée de nouveaux symptômes ailleurs

   ARRÊTEZ-VOUS et remettez en question les principes fondamentaux :

   • Ce schéma est-il fondamentalement solide ?
   • Sommes-nous en train de « nous y accrocher par pure inertie » ?
   • Faut-il refactoriser l'architecture plutôt que de continuer à corriger les symptômes ?

   Discutez-en avec votre collègue avant de tenter d’autres corrections

   Ce n’est PAS une hypothèse erronée : c’est une architecture défaillante.

Signaux d'alerte : ARRÊTEZ-VOUS et suivez la procédure

Si vous vous surprenez à penser :

• « Une solution rapide pour l'instant, on verra plus tard »
• « Essayons simplement de modifier X et voyons si ça marche »
• « Ajoutez plusieurs modifications, puis lancez les tests »
• « Je passe le test, je vais vérifier manuellement »
• « C'est sûrement X, je vais corriger ça »
• « Je ne comprends pas tout, mais ça pourrait marcher »
• « Le modèle prévoit X, mais je vais l’adapter différemment. »
• « Voici les principaux problèmes : [liste des corrections sans analyse préalable] »
• Proposer des solutions avant d'avoir tracé le flux de données
• « Encore une tentative de correction » (alors qu’on en a déjà essayé au moins deux)
• Chaque correction révèle un nouveau problème à un autre endroit

TOUT cela signifie : ARRÊTEZ. Revenez à la phase 1.

Si 3 corrections ou plus ont échoué : remettez en question l’architecture (voir la phase 4.5)

Les signaux de votre partenaire humain indiquant que vous vous y prenez mal

Soyez attentif à ces réorientations :

• « Est-ce que ça ne se produit pas ? » – Vous avez émis une hypothèse sans vérifier
• « Est-ce que ça va nous montrer… ? » – Vous auriez dû collecter davantage de preuves
• « Arrête de deviner » – Tu proposes des solutions sans comprendre
• « Réfléchis-y à fond » – Remets en question les fondements, pas seulement les symptômes
• « On est bloqués ? » (frustré) – Votre approche ne fonctionne pas

Lorsque vous voyez ces phrases : ARRÊTEZ-VOUS. Revenez à la phase 1.

Rationalisations courantes

Référence rapide

Lorsque le processus révèle « aucune cause première »

Si une enquête systématique révèle que le problème est véritablement lié à l’environnement, dépendant du moment ou d’origine externe :

1. Vous avez terminé le processus
2. Documentez les éléments que vous avez examinés
3. Mettez en place la gestion appropriée (nouvelle tentative, délai d'expiration, message d'erreur)
4. Ajoutez des mécanismes de surveillance/journalisation pour de futures analyses

Mais : 95 % des cas où « aucune cause première » n’est identifiée sont dus à une analyse incomplète.

Techniques d'appui

Ces techniques font partie du débogage systématique et sont disponibles dans ce répertoire :

• root-cause-tracing.md - Remonter la piste des bogues à travers la pile d'appels pour trouver le déclencheur d'origine
• defense-in-depth.md - Ajouter des validations à plusieurs niveaux après avoir identifié la cause première
• condition-based-waiting.md - Remplacer les délais d’attente arbitraires par une interrogation conditionnelle

Compétences associées :

• superpowers:test-driven-development - Pour créer un cas de test échouant (Phase 4, Étape 1)
• superpowers:verification-before-completion - Vérifier que la correction a fonctionné avant de déclarer la réussite

Impact concret

À partir des sessions de débogage :

• Approche systématique : 15 à 30 minutes pour corriger le problème
• Approche par corrections aléatoires : 2 à 3 heures de tâtonnements
• Taux de résolution dès la première tentative : 95 % contre 40 %
• Nouveaux bugs introduits : quasi nul contre fréquents