debug-methodical

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 :

• Étapes de reproduction documentées (Given/When/Then)
• Reproduction déterministe (>= 3 runs consécutifs identiques)
• Environnement isolé (local, container, test env)
• Inputs minimaux (le moins de données/steps possible)
• Version/commit exacts identifiés

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 :

• Cause identifiée (ligne / condition / input exact)
• Explication du pourquoi (pas juste le quoi)
• Chaîne de causalité documentée (A cause B cause C)
• Autres manifestations potentielles du même bug identifiées

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 :

• Fix au bon niveau (cause racine, pas symptôme)
• Changement minimal (KISS, voir rule 05)
• Pas d'effet de bord sur autres features
• Pas de fix "au cas où" / spéculatif (voir rule 23 Karpathy)
• Fix dans le bon layer (domain / infra / UI)

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 :

• Test de régression (Phase 1) passe maintenant
• Suite de tests complète passe
• Reproduction manuelle ne montre plus le bug
• Scénarios adjacents testés (edge cases proches)
• Performance non dégradée
• Logs / monitoring vérifiés en staging si critique

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