Débogage Systématique

Aperçu

Les corrections aléatoires gaspillent du temps et créent de nouveaux bugs. Les rustines rapides masquent les problèmes sous-jacents.

Principe fondamental : TOUJOURS trouver la cause racine avant de tenter des corrections. Les corrections de symptômes sont un échec.

Violer la lettre de ce processus, c'est violer l'esprit du débogage.

La Loi de Fer

AUCUNE CORRECTION SANS INVESTIGATION DE LA CAUSE RACINE D'ABORD

Si vous n'avez pas complété la Phase 1, vous ne pouvez pas proposer de corrections.

Quand l'Utiliser

Utilisez-le pour TOUT problème technique :

• Échecs de tests
• Bugs en production
• Comportement inattendu
• Problèmes de performance
• Échecs de build
• Problèmes d'intégration

Utilisez-le PARTICULIÈREMENT quand :

• Vous êtes sous pression temporelle (les urgences rendent la devination tentante)
• « Juste une petite correction rapide » semble évidente
• Vous avez déjà essayé plusieurs corrections
• La correction précédente n'a pas fonctionné
• Vous ne comprenez pas complètement le problème

Ne sautez pas quand :

• Le problème semble simple (les bugs simples ont aussi des causes racines)
• Vous êtes pressé (la précipitation garantit des refonte)
• Le manager veut que ce soit corrigé MAINTENANT (systématique est plus rapide que le chaos)

Les Quatre Phases

Vous DEVEZ compléter chaque phase avant de passer à la suivante.

Phase 1 : Investigation de la Cause Racine

AVANT de tenter TOUTE correction :

1. Lisez les Messages d'Erreur Attentivement

   • Ne sautez pas les erreurs ou avertissements
   • Ils contiennent souvent la solution exacte
   • Lisez les stack traces complètement
   • Notez les numéros de ligne, chemins de fichiers, codes d'erreur

2. Reproduisez de Manière Cohérente

   • Pouvez-vous le déclencher de manière fiable ?
   • Quelles sont les étapes exactes ?
   • Cela se produit-il à chaque fois ?
   • Si non reproductible → collectez plus de données, ne devinez pas

3. Vérifiez les Changements Récents

   • Qu'est-ce qui a changé et qui pourrait causer ceci ?
   • Git diff, commits récents
   • Nouvelles dépendances, changements de config
   • Différences d'environnement

4. Collectez les Preuves dans les Systèmes Multi-Composants

   QUAND le système a plusieurs composants (CI → build → signing, API → service → database) :

   AVANT de proposer des corrections, ajoutez une instrumentation de diagnostic :

   Pour CHAQUE limite de composant :
     - Consignez les données qui entrent dans le composant
     - Consignez les données qui sortent du composant
     - Vérifiez la propagation d'environnement/config
     - Vérifiez l'état à chaque couche
   
   Exécutez une fois pour collecter les preuves montrant OÙ cela casse
   PUIS analysez les preuves pour identifier le composant défaillant
   PUIS enquêtez sur ce composant spécifique

   Exemple (système multi-couches) :

   # Couche 1 : Workflow
   echo "=== Secrets disponibles dans le workflow : ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   
   # Couche 2 : Script de build
   echo "=== Variables d'env dans le script de build : ==="
   env | grep IDENTITY || echo "IDENTITY pas dans l'environnement"
   
   # Couche 3 : Script de signing
   echo "=== État du keychain : ==="
   security list-keychains
   security find-identity -v
   
   # Couche 4 : Signing réel
   codesign --sign "$IDENTITY" --verbose=4 "$APP"

   Ceci révèle : Quelle couche échoue (secrets → workflow ✓, workflow → build ✗)

5. Tracez le Flux de Données

   QUAND l'erreur est profonde dans la call stack :

   Voir skills/root-cause-tracing pour la technique de traçage rétroactif

   Version rapide :

   • D'où vient la mauvaise valeur ?
   • Qui a appelé ceci avec une mauvaise valeur ?
   • Continuez à tracer jusqu'à trouver la source
   • Corrigez à la source, pas au symptôme

Phase 2 : Analyse de Patterns

Trouvez le pattern avant de corriger :

1. Trouvez des Exemples Fonctionnels

   • Localisez du code similaire fonctionnant dans le même codebase
   • Qu'est-ce qui fonctionne et qui est similaire à ce qui est cassé ?

2. Comparez Avec les Références

   • Si vous implémentez un pattern, lisez la documentation de référence COMPLÈTEMENT
   • Ne survolez pas - lisez chaque ligne
   • Comprenez le pattern complètement avant de l'appliquer

3. Identifiez les Différences

   • Qu'est-ce qui est différent entre le fonctionnel et le cassé ?
   • Listez chaque différence, si petite soit-elle
   • Ne supposez pas « cela ne peut pas avoir d'importance »

4. Comprenez les Dépendances

   • Quels autres composants cela nécessite-t-il ?
   • Quels paramètres, config, environnement ?
   • Quelles hypothèses fait-il ?

Phase 3 : Hypothèse et Test

Méthode scientifique :

1. Formulez une Seule Hypothèse

   • Déclarez clairement : « Je pense que X est la cause racine parce que Y »
   • Écrivez-la
   • Soyez spécifique, pas vague

2. Testez Minimalement

   • Faites le PLUS PETIT changement possible pour tester l'hypothèse
   • Une variable à la fois
   • Ne corrigez pas plusieurs choses en même temps

3. Vérifiez Avant de Continuer

   • Cela a-t-il fonctionné ? Oui → Phase 4
   • N'a pas fonctionné ? Formulez une NOUVELLE hypothèse
   • N'AJOUTEZ pas plus de corrections par-dessus

4. Quand Vous Ne Savez Pas

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

Phase 4 : Implémentation

Corrigez la cause racine, pas le symptôme :

1. Créez un Cas de Test Échouant

   • Reproduction la plus simple possible
   • Test automatisé si possible
   • Script de test ponctuel si pas de framework
   • DOIT exister avant de corriger
   • Voir .claude/skills/test-driven-development pour écrire des tests échouants appropriés

2. Implémentez une Seule Correction

   • Adressez la cause racine identifiée
   • UN changement à la fois
   • Pas d'améliorations « pendant que j'y suis »
   • Pas de refactorisation groupée

3. Vérifiez la Correction

   • Le test passe maintenant ?
   • Aucun autre test cassé ?
   • Le problème est-il vraiment résolu ?

4. Si la Correction Ne Fonctionne Pas

   • ARRÊTEZ
   • Comptez : Combien de corrections avez-vous essayées ?
   • Si < 3 : Retournez à la Phase 1, réanalysez avec les nouvelles informations
   • Si ≥ 3 : ARRÊTEZ et remettez en question l'architecture (étape 5 ci-dessous)
   • N'ESSAYEZ PAS la Correction #4 sans discussion architecturale

5. Si 3+ Corrections Ont Échoué : Remettez en Question l'Architecture

   Pattern indiquant un problème architectural :

   • Chaque correction révèle un nouvel état partagé/couplage/problème ailleurs
   • Les corrections nécessitent une « refactorisation massive » pour être implémentées
   • Chaque correction crée de nouveaux symptômes ailleurs

   ARRÊTEZ et remettez en question les fondamentaux :

   • Ce pattern est-il fondamentalement sain ?
   • « Collons-nous à cela par pure inertie » ?
   • Devons-nous refactoriser l'architecture plutôt que continuer à corriger les symptômes ?

   Discutez avec votre partenaire humain avant de tenter plus de corrections

   Ce n'est PAS une hypothèse échouée - c'est une architecture erronée.

Signaux d'Alerte - ARRÊTEZ et Suivez le Processus

Si vous vous surprenez à penser :

• « Correction rapide pour maintenant, investigation plus tard »
• « Essayons juste de changer X et voyons si cela fonctionne »
• « Ajouter plusieurs changements, exécuter les tests »
• « Sauter le test, je vérifierai manuellement »
• « C'est probablement X, laissez-moi corriger cela »
• « Je ne comprends pas complètement mais cela pourrait fonctionner »
• « Le pattern dit X mais je vais l'adapter différemment »
• « Voici les problèmes principaux : [liste les corrections sans investigation] »
• Proposer des solutions avant de tracer le flux de données
• « Une tentative de correction de plus » (quand déjà essayé 2+)
• Chaque correction révèle un nouveau problème ailleurs

TOUS ces cas signifient : ARRÊTEZ. Retournez à la Phase 1.

Si 3+ corrections ont échoué : Remettez en question l'architecture (voir Phase 4.5)

Signaux de Votre Partenaire Humain Que Vous Vous Trompez

Surveillez ces réorientations :

• « Cela ne se produit pas ? » - Vous avez supposé sans vérifier
• « Cela nous montrera-t-il... ? » - Vous auriez dû ajouter une collecte de preuves
• « Arrêtez de deviner » - Vous proposez des corrections sans comprendre
• « Pensez à cela en profondeur » - Remettez en question les fondamentaux, pas juste les symptômes
• « On est coincés ? » (frustré) - Votre approche ne fonctionne pas

Quand vous voyez ceci : ARRÊTEZ. Retournez à la Phase 1.

Rationalisations Courantes

Référence Rapide

Quand le Processus Révèle « Aucune Cause Racine »

Si l'investigation systématique révèle que le problème est véritablement environnemental, dépendant du timing, ou externe :

1. Vous avez complété le processus
2. Documentez ce que vous avez enquêté
3. Implémentez une gestion appropriée (retry, timeout, message d'erreur)
4. Ajoutez du monitoring/logging pour une investigation future

Mais : 95% des cas « aucune cause racine » sont des investigations incomplètes.

Intégration avec d'Autres Skills

Ce skill fonctionne avec :

• skills/root-cause-tracing - Comment tracer à travers la call stack

Impact Réel

À partir des sessions de débogage :

• Approche systématique : 15-30 minutes pour corriger
• Approche corrections aléatoires : 2-3 heures de chaos
• Taux de correction première tentative : 95% vs 40%
• Nouveaux bugs introduits : Quasi zéro vs courants