| name | grimoire-systematic-debugging |
| description | Systematic debugging workflow with 4 phases. Use when: bug found, test failure, unexpected behavior, error diagnosis, debugging, root cause analysis, fix not working. |
Debugging Systématique
Processus en 4 phases pour trouver la cause racine avant de corriger. Adapté de superpowers.
Principe fondamental
AUCUN FIX SANS INVESTIGATION DE LA CAUSE RACINE D'ABORD
Si la Phase 1 n'est pas terminée, aucun fix ne peut être proposé.
Quand NE PAS utiliser
- Pour réparer un échec de workflow agentique Grimoire interne (agent, framework tool, pipeline interne) →
grimoire-self-heal.
- Pour répondre à une régression sur le code de production / build / CI →
grimoire-incident-response.
- Pour traquer des edge cases non gardés sans cause connue →
grimoire-edge-case-hunter.
Quand utiliser
- Toujours : échecs de tests, bugs, comportements inattendus, problèmes de performance
- Surtout quand : sous pression, "juste un quick fix" semble évident, déjà tenté plusieurs fixes
Les 4 phases
graph TD
P1["Phase 1<br/>Cause Racine"] --> P2["Phase 2<br/>Analyse de Pattern"]
P2 --> P3["Phase 3<br/>Hypothèse et Test"]
P3 --> P4["Phase 4<br/>Implémentation"]
P3 -->|hypothèse invalide| P1
P4 -->|fix échoue < 3×| P1
P4 -->|fix échoue ≥ 3×| ARCH["Questionner<br/>l'architecture"]
Phase 1 : Investigation de la cause racine
AVANT tout fix :
-
Lire les messages d'erreur attentivement
- Ne pas les ignorer — ils contiennent souvent la solution exacte
- Lire les stack traces complètement
- Noter les numéros de ligne, fichiers, codes d'erreur
-
Reproduire systématiquement
- Peut-on le déclencher de façon fiable ?
- Quelles sont les étapes exactes ?
- Si non reproductible → plus de données, pas de devinette
-
Vérifier les changements récents
git diff, commits récents
- Nouvelles dépendances, changements de config
- Différences d'environnement
-
Tracer le flux de données
- D'où vient la mauvaise valeur ?
- Qui a appelé cette fonction avec cette valeur ?
- Remonter jusqu'à la source — corriger à la source, pas au symptôme
-
Systèmes multi-composants : instrumenter chaque frontière de composant AVANT de proposer des fixes
Phase 2 : Analyse de pattern
- Trouver des exemples fonctionnels — code similaire qui marche dans le même codebase
- Comparer avec les références — lire l'implémentation de référence ENTIÈREMENT
- Identifier les différences — lister chaque différence, même minime
- Comprendre les dépendances — config, environnement, hypothèses
Phase 3 : Hypothèse et test
- Former UNE hypothèse : "Je pense que X est la cause parce que Y"
- Tester minimalement : le PLUS PETIT changement possible, une variable à la fois
- Vérifier : ça marche → Phase 4 | ça ne marche pas → nouvelle hypothèse
- Si inconnu : dire "je ne comprends pas X", pas prétendre savoir
Phase 4 : Implémentation
- Créer un test case failing (utiliser la skill
grimoire-tdd)
- Implémenter UN SEUL fix — la cause racine identifiée
- Vérifier le fix — test passe, pas de régression
- Si le fix échoue :
- Moins de 3 tentatives → retour Phase 1
- 3+ tentatives → STOP et questionner l'architecture
Questionner l'architecture (après 3+ échecs)
Signaux d'un problème architectural :
- Chaque fix révèle un nouveau problème ailleurs
- Les fixes nécessitent un "refactoring massif"
- Chaque fix crée de nouveaux symptômes
STOP et discuter avec l'utilisateur avant d'autres tentatives.
Red Flags — STOP et suivre le processus
Si vous pensez :
- "Quick fix pour l'instant"
- "Essayons de changer X"
- "Plusieurs changements d'un coup"
- "Je ne comprends pas tout mais ça devrait marcher"
- "Encore un essai" (après 2+ échecs)
TOUT cela signifie : STOP. Retour Phase 1.
Référence rapide
| Phase | Activités clés | Critère de succès |
|---|
| 1. Cause Racine | Lire erreurs, reproduire, vérifier changements | Comprendre QUOI et POURQUOI |
| 2. Pattern | Trouver exemples fonctionnels, comparer | Identifier les différences |
| 3. Hypothèse | Former théorie, tester minimalement | Confirmé ou nouvelle hypothèse |
| 4. Implémentation | Créer test, fixer, vérifier | Bug résolu, tests passent |