| name | debug-methodical |
| description | Debugging méthodique en 4 phases (reproduce → isolate → fix → verify). Use when investigating a bug, regression, flaky test, or unexpected behavior. |
| context | fork |
Debug-Methodical — Debugging en 4 phases
Skill inspiré de obra/superpowers. Objectif : forcer une méthode rigoureuse au lieu de "try random fixes until it works".
Règle d'or : un bug sans reproduction stable est un bug mal compris. Ne JAMAIS fixer avant de reproduire.
Les 4 phases (strictes, dans l'ordre)
Phase 1 : REPRODUCE
Objectif : exécuter le bug à volonté, dans un environnement contrôlé.
Checklist :
Sortie : test automatisé qui échoue en exposant le bug (test de régression).
Signal rouge : "ça marche sur ma machine" / "parfois ça fail" → reproduction insuffisante, retour Phase 1.
Phase 2 : ISOLATE
Objectif : identifier la cause racine, pas juste un symptôme.
Techniques :
- Bisect :
git bisect pour trouver le commit fautif
- Binary search dans le code : commenter la moitié, puis itérer
- Print-driven debugging : logs aux frontières (entrée/sortie fonctions)
- Debugger : breakpoints, step-through, variable watch
- Diff environnements : que diffère-t-il entre "qui marche" et "qui casse" ?
- Question the premise : l'hypothèse initiale est-elle correcte ?
Checklist :
Signal rouge : "je pense que c'est X" sans preuve → retour isolate avec instrumentation.
Phase 3 : FIX
Objectif : corriger la cause racine avec le minimum de changement.
Checklist :
Signaux rouges :
- Fix qui ajoute un
try/catch pour masquer l'erreur → traite le symptôme, pas la cause
- Fix qui nécessite de modifier les tests existants de façon suspecte
- Fix qui "marche" sans que tu saches pourquoi
Phase 4 : VERIFY
Objectif : prouver que le fix marche ET n'a rien cassé d'autre.
Checklist :
Règle de régression : le test écrit en Phase 1 reste dans la codebase pour toujours. Un bug fixé ne doit JAMAIS réapparaître (voir /qa:regression).
Anti-patterns critiques
| Anti-pattern | Pourquoi c'est mal |
|---|
| Shotgun debugging | Changer 10 trucs au hasard, aucun apprentissage |
| Fix du symptôme | Bug revient sous une autre forme |
| Skip reproduction | Fix impossible à valider |
| Skip verification | "ça devrait marcher" — preuve ou pas fini |
| Pas de test de régression | Bug réapparaît dans 3 mois |
Fix avec catch (Exception) générique | Masque d'autres bugs |
| Commit mélangé fix + refactor | git bisect impossible |
Techniques avancées
Pour bugs de concurrence
- Forcer les interleavings (sleep stratégique, stress test)
- Thread dumps / profiler
- Vérifier les invariants atomiquement
Pour bugs d'intégration
- Snapshot du payload exact (HAR, logs)
- Reproduire avec
curl ou client minimal
- Vérifier versions exactes des dépendances
Pour flaky tests
- Run 100x pour mesurer le taux de flakiness
- Identifier la dépendance (temps, ordre, ressource partagée)
- Ne JAMAIS marquer un test
@Flaky sans ticket de correction
Intégration Claude Craft
/qa:tdd — bug fix en mode TDD (test qui échoue d'abord)/qa:fix — correction automatisée des bugs QA/qa:regression — registre des tests de régression- Skill
atomic-tasks — découper le debug en phases atomiques
- Rule 07 (testing) — bug fix = test de régression obligatoire
Ressources
- obra/superpowers
- Rule
.claude/rules/07-testing.md
- Command
/qa:tdd, /qa:regression
Date de dernière mise à jour : 2026-04-15
Version : 1.0.0
