systematic-debugging

Vue d’ensemble

Qu’est-ce que systematic-debugging ?

La skill systematic-debugging propose un processus structuré en quatre phases pour déboguer tout type de problème technique : échecs de tests, bugs en production, tests instables, problèmes de performance, erreurs de build ou échecs d’intégration.

Au lieu de tenter « une petite correction rapide » ou de modifier le code dès la première ligne d’erreur, cette skill vous oblige à enquêter d’abord sur la cause racine, puis à concevoir et valider une correction durable. Elle s’appuie sur des patterns pratiques et des scripts issus d’une base de code réelle, incluant des helpers TypeScript de condition-based waiting et un script Bash pour trouver les tests pollueurs.

Principe fondamental et Loi de fer

Le cœur de systematic-debugging est simple :

• Principe fondamental : toujours trouver la cause racine avant de tenter une correction. Les corrections qui ne traitent que les symptômes sont des échecs.

• La Loi de fer :

  NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
  

Tant que vous n’avez pas terminé la phase d’investigation, vous ne proposez ni n’appliquez de corrections. Le but est de résister à la pression temporelle, aux suppositions et aux « juste cette fois ».

À qui s’adresse cette skill ?

systematic-debugging s’adresse :

• aux développeurs sur des projets JavaScript/TypeScript qui veulent des correctifs fiables et reproductibles ;
• aux ingénieurs tests et QA confrontés à des comportements instables, des timeouts aléatoires et un état de test pollué ;
• aux ingénieurs CI/CD et tooling qui diagnostiquent des échecs de build ou d’intégration intermittents ;
• aux tech leads et reviewers qui souhaitent un processus partagé et rigoureux pour le travail de débogage.

Cette skill est particulièrement pertinente si vous privilégiez une analyse de cause racine de haute qualité plutôt que des rustines rapides sur les symptômes.

Quels problèmes cela résout-il ?

Utilisez la skill systematic-debugging lorsque vous devez :

• enquêter sur des échecs de tests qui réapparaissent malgré des « corrections » ;
• traquer des tests instables (flaky) qui dépendent de timeouts arbitraires ou de conditions de concurrence ;
• comprendre un comportement inattendu plutôt que simplement faire taire les erreurs ;
• diagnostiquer des problèmes de performance ou des flux lents et sensibles au timing ;
• déboguer des échecs de build ou d’intégration qui ne se produisent qu’en CI ou sous charge ;
• trouver quel test pollue l’état ou laisse des fichiers/répertoires indésirables.

Le dépôt inclut également :

• condition-based-waiting.md et condition-based-waiting-example.ts pour remplacer setTimeout/sleep par du condition-based waiting robuste en TypeScript ;
• defense-in-depth.md pour ajouter de la validation à plusieurs niveaux, afin de rendre certaines catégories de bugs structurellement impossibles ;
• find-polluter.sh, un helper Bash pour localiser le test exact qui crée des fichiers ou de l’état indésirable ;
• root-cause-tracing.md pour remonter les erreurs à travers la chaîne d’appels jusqu’à leur véritable origine.

Quand systematic-debugging est-il adapté ?

systematic-debugging est particulièrement adapté lorsque :

• vous êtes sous pression et tenté de deviner la correction ;
• un problème revient malgré plusieurs tentatives de correction ;
• vous voulez un workflow de débogage reproductible pour vous ou votre équipe ;
• vous êtes en train de stabiliser une suite de tests instables ou de nettoyer un environnement de test pollué.

Il peut être moins adapté si :

• vous avez seulement besoin d’une génération de code ponctuelle ou d’un refactoring simple, sans investigation ;
• vous déboguez en dehors des domaines techniques décrits (p. ex. problèmes de processus non techniques) ;
• vous n’êtes pas prêt à suivre un processus pas à pas et préférez l’expérimentation ad hoc.

Si votre objectif est « patch rapide maintenant, on verra plus tard pour le rework », ce processus vous paraîtra strict. Si votre objectif est « corriger une fois, correctement », systematic-debugging est conçu pour vous.

Comment l’utiliser

Installation et configuration

Pour installer la skill systematic-debugging dans un agent ou un environnement d’outils compatible, utilisez la commande npx fournie :

npx skills add https://github.com/obra/superpowers --skill systematic-debugging
``

Cette commande récupère la définition de la skill, ainsi que les documents et scripts associés, depuis le dépôt `obra/superpowers` sous `skills/systematic-debugging`.

Après l’installation :

1. Ouvrez la skill `systematic-debugging` dans l’interface de votre agent ou de vos skills.
2. Assurez-vous que votre workspace a accès au dépôt de votre projet, aux commandes de test et aux logs.
3. Vérifiez que vous pouvez consulter les guides markdown et scripts fournis :
   - `SKILL.md`
   - `condition-based-waiting.md`
   - `defense-in-depth.md`
   - `root-cause-tracing.md`
   - `find-polluter.sh`

### Fichiers et composants à connaître
Pour décider de l’installation et pour l’usage au quotidien, ces fichiers sont les plus importants :

- **`SKILL.md`** – Définit le processus complet de débogage systématique en quatre phases, les règles et les anti-patterns. C’est le cœur de la skill.
- **`condition-based-waiting.md`** – Explique comment remplacer les timeouts arbitraires dans les tests par du condition-based waiting.
- **`condition-based-waiting-example.ts`** – Utilitaires TypeScript comme `waitForEvent` qui implémentent du condition-based waiting sur un `ThreadManager` et des types d’événements.
- **`defense-in-depth.md`** – Montre comment appliquer une validation multi-couche (point d’entrée, logique métier, garde-fous environnementaux, logging) pour rendre des classes entières de bugs impossibles.
- **`find-polluter.sh`** – Script Bash qui itère sur les tests pour trouver lequel crée un chemin donné (pollution d’état).
- **`root-cause-tracing.md`** – Décrit comment remonter d’un bug à partir d’une stack trace jusqu’au déclencheur original, puis comment combiner cela avec la defense-in-depth.
- **`CREATION-LOG.md`** – Un méta-log expliquant comment le cadre a été extrait et durci ; utile pour comprendre l’intention de conception, moins critique au quotidien.

Pour les développeurs **JavaScript/TypeScript**, l’exemple TypeScript et le script Bash peuvent souvent être adaptés directement à votre projet.

### Exécuter le workflow en quatre phases
Le processus `systematic-debugging` est organisé en quatre phases obligatoires (décrites dans `SKILL.md`). Vous devez terminer chaque phase avant de passer à la suivante.

#### Phase 1 – Investigation de la cause racine
Avant de toucher au code, à la configuration ou aux tests :

- **Lisez attentivement les messages d’erreur et les logs.**
  - Ne survolez pas les stack traces ni les avertissements.
  - Relevez les numéros de ligne, chemins de fichiers et codes d’erreur.
- **Reproduisez le problème de manière fiable.**
  - Établissez une commande de reproduction minimale et fiable.
  - Notez les entrées et facteurs d’environnement nécessaires.

Vous ne proposez ni n’implémentez de corrections dans cette phase. L’objectif est la compréhension : qu’est-ce qui échoue exactement, où, et dans quelles conditions.

#### Phase 2 – Analyse des patterns
Une fois la reproduction fiable :

- Faites varier un facteur à la fois (entrées, configuration, environnement) pour voir ce qui change le résultat.
- Cherchez les frontières : valeurs ou conditions où le comportement bascule de « pass » à « fail ».
- Utilisez logs, assertions ou instrumentation temporaire pour resserrer le chemin fautif.

À la fin de la Phase 2, vous devez comprendre la forme du problème et les conditions qui le déclenchent, pas seulement le message d’erreur final.

#### Phase 3 – Hypothèse et conception
Vous pouvez maintenant formuler une hypothèse :

- Énoncez clairement ce que vous pensez être la cause racine (flux de données, validation manquante, problème de timing, mauvais chemin, etc.).
- Concevez un changement **simple et ciblé** qui adresse cette cause racine.
- Planifiez comment vous allez valider l’hypothèse à l’aide de vos étapes de reproduction.

Si l’hypothèse est invalidée, vous revenez à l’investigation/analyse au lieu d’empiler d’autres correctifs spéculatifs.

#### Phase 4 – Implémentation et validation
Ce n’est qu’avec une hypothèse claire que vous modifiez le code ou la configuration :

- Appliquez le changement le plus minimal qui traite directement la cause racine.
- Exécutez la reproduction minimale puis la suite de tests plus large.
- Appuyez-vous sur :
  - `defense-in-depth.md` pour ajouter de la validation à plusieurs niveaux ;
  - `root-cause-tracing.md` pour vous assurer que vous corrigez bien la source réelle.
- Confirmez que la correction est robuste (par ex. fonctionne sous charge, en CI et pour les cas limites identifiés en Phase 2).

Si la correction ne se comporte pas comme prévu, vous **n’empilez pas** davantage de changements ; vous revenez aux phases précédentes.

### Utiliser les utilitaires de débogage dans votre projet

#### Condition-based waiting pour tests instables (JavaScript/TypeScript)
Les tests instables qui reposent sur `setTimeout` ou `sleep` cassent souvent lorsque les machines sont plus lentes, plus rapides ou sous charge. `condition-based-waiting.md` et `condition-based-waiting-example.ts` présentent un meilleur pattern : attendre la condition qui vous intéresse.

Migration typique :

```typescript
// ❌ Avant : timing au hasard
await new Promise(r => setTimeout(r, 50));
const result = getResult();
expect(result).toBeDefined();

// ✅ Après : attente sur condition
await waitFor(() => getResult() !== undefined);
const result = getResult();
expect(result).toBeDefined();

Le fichier condition-based-waiting-example.ts fournit des helpers comme :

export function waitForEvent(
  threadManager: ThreadManager,
  threadId: string,
  eventType: LaceEventType,
  timeoutMs = 5000
): Promise<LaceEvent> { /* ... */ }

Adaptez ces patterns à votre propre infrastructure de tests :

1. Copiez ou réimplémentez les utilitaires dans vos helpers de tests.
2. Remplacez les appels setTimeout/sleep arbitraires par des attentes basées sur des conditions.
3. Relancez votre suite de tests pour confirmer la réduction de la flakiness.

Cela contribue directement à l’objectif de systematic-debugging : éliminer les causes racines au lieu d’allonger les timeouts au hasard.

Trouver les tests pollueurs avec find-polluter.sh

Si vos tests laissent des fichiers ou répertoires supplémentaires, ou polluent autrement l’état, find-polluter.sh vous aide à trouver le test responsable.

Utilisation (depuis la racine de votre projet, en adaptant les arguments) :

./find-polluter.sh <file_or_dir_to_check> <test_pattern>

# Example
./find-polluter.sh '.git' 'src/**/*.test.ts'

Le script va :

• découvrir les fichiers de test correspondant au pattern ;
• les exécuter un par un avec npm test <file> ;
• après chaque exécution, vérifier si le fichier ou répertoire cible existe désormais ;
• s’arrêter et signaler le premier test qui l’a créé, avec les commandes pour relancer et inspecter ce test.

Cet outil s’intègre aux Phases 1 et 2 de systematic-debugging en fournissant un moyen fiable de reproduire et isoler la pollution d’état.

Appliquer la validation defense-in-depth

Lorsque votre investigation révèle un bug causé par des données invalides ou des hypothèses erronées, defense-in-depth.md recommande d’implanter de la validation à plusieurs niveaux :

• Validation au point d’entrée – Rejeter les entrées manifestement invalides aux frontières (APIs, CLI, handlers UI).
• Validation dans la logique métier – S’assurer que les données ont du sens pour l’opération concernée.
• Garde-fous environnementaux – Empêcher les opérations dangereuses dans le mauvais environnement ou chemin.
• Logging diagnostique – Fournir un contexte utile si quelque chose passe quand même au travers.

Par exemple, valider un argument workingDirectory :

function createProject(name: string, workingDirectory: string) {
  if (!workingDirectory || workingDirectory.trim() === '') {
    throw new Error('workingDirectory cannot be empty');
  }
  if (!existsSync(workingDirectory)) {
    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
  }
  if (!statSync(workingDirectory).isDirectory()) {
    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
  }
  // ... proceed
}

Utilisez ces patterns lors de l’implémentation de corrections en Phase 4 pour faire en sorte que le bug ne puisse pas réapparaître facilement par un autre chemin de code.

Quand ne pas utiliser cette skill

Il peut être préférable d’ignorer ou de différer systematic-debugging si :

• vous faites un prototype et acceptez consciemment du code jetable et des bugs ;
• le problème est trivial et totalement compris (par exemple une faute de frappe évidente détectée pendant le développement) et ne justifie pas la rigueur complète des quatre phases ;
• vous avez seulement besoin d’exemples d’utilitaires (comme le condition-based waiting) sans adopter le processus plus large.

Même dans ces cas, la Loi de fer reste un bon garde-fou : si vous commencez à empiler plusieurs corrections hypothétiques, il est temps de passer à systematic-debugging.

FAQ

Qu’est-ce que systematic-debugging change concrètement dans mon workflow ?

Au lieu de passer directement du message d’erreur aux modifications de code, systematic-debugging vous impose de passer par l’investigation, l’analyse des patterns et l’hypothèse avant l’implémentation. Concrètement, cela signifie :

• vous établissez une reproduction fiable avant de toucher au code ;
• vous faites varier les conditions pour comprendre l’espace du problème ;
• vous écrivez une correction ciblée pour chaque hypothèse validée.

Le résultat : moins de revert, moins de régressions cachées et un temps de débogage plus prévisible.

Comment installer la skill systematic-debugging ?

Utilisez la commande npx skills :

npx skills add https://github.com/obra/superpowers --skill systematic-debugging

Après l’installation, ouvrez la skill dans votre agent ou votre répertoire de skills, puis consultez SKILL.md pour le processus complet et les fichiers markdown associés pour les patterns et exemples.

systematic-debugging prend-il en charge le débogage JavaScript et TypeScript ?

Oui. Bien que le framework lui-même soit indépendant du langage, le dépôt inclut des utilitaires concrets orientés JavaScript/TypeScript :

• condition-based-waiting-example.ts pour le condition-based waiting dans les tests ;
• des patterns dans defense-in-depth.md et root-cause-tracing.md illustrés avec des exemples TypeScript ;
• find-polluter.sh, qui suppose npm test par défaut et fonctionne bien avec les runners de tests JS/TS classiques.

Vous pouvez adapter ces utilitaires à la structure et aux outils de votre projet.

Puis-je utiliser systematic-debugging pour l’automatisation de tests instables ?

Oui. C’est l’un de ses cas d’usage les plus forts. Combinez :

• le processus en quatre phases de SKILL.md pour enquêter et comprendre la flakiness ;
• condition-based-waiting.md et l’exemple TypeScript pour remplacer les suppositions de timing par du condition-based waiting ;
• find-polluter.sh pour trouver les tests qui polluent l’état ou créent des fichiers inattendus.

Ensemble, ces outils vous aident à transformer des tests peu fiables en vérifications stables et déterministes.

systematic-debugging est-il réservé aux tests, ou aussi aux bugs de production ?

Le processus s’applique à tout problème technique :

• échecs de tests et flakiness ;
• bugs et incidents en production ;
• problèmes de performance ;
• échecs de build et d’intégration.

Les exemples et utilitaires sont plutôt orientés vers les workflows de test et de développement, mais les phases et principes sont explicitement conçus pour couvrir aussi les scénarios de production.

Que faire si je suis sous pression et que j’ai juste besoin d’un correctif rapide ?

La skill est justement écrite pour résister à l’impulsion du « juste un petit fix rapide ». Elle souligne que :

• se précipiter sans investigation de la cause racine conduit au « thrashing » et au rework ;
• les correctifs qui ne traitent que les symptômes créent souvent de nouveaux problèmes.

En pratique, prendre quelques minutes pour suivre les Phases 1 et 2 fait généralement gagner du temps au global, même en situation d’urgence.

Dois-je suivre les quatre phases systématiquement à chaque fois ?

L’intention de systematic-debugging est que sauter des phases reste l’exception, pas la règle. Pour des problèmes mineurs et parfaitement compris (par exemple un petit refactoring où vous identifiez immédiatement la faute), vous pouvez compresser les étapes. Mais si :

• le problème est récurrent ;
• vous ne comprenez pas entièrement pourquoi il se produit ;
• les corrections précédentes ont échoué,

…alors le processus complet en quatre phases est fortement recommandé.

Quel lien entre root-cause tracing et defense-in-depth ?

root-cause-tracing.md vous aide à suivre un bug depuis l’erreur visible, à travers les chaînes d’appels, jusqu’au déclencheur initial. defense-in-depth.md montre ensuite comment prévenir les bugs similaires en :

• corrigeant à la véritable source ;
• ajoutant de la validation à plusieurs niveaux.

Par exemple, si git init échoue dans le mauvais répertoire, le tracing montre quelle fonction a passé le mauvais chemin, et la defense-in-depth ajoute de la validation et des garde-fous pour que les chemins invalides soient rejetés plus tôt.

Puis-je utiliser la skill sans copier de code depuis le dépôt ?

Oui. La valeur principale de systematic-debugging est le processus de débogage structuré décrit dans SKILL.md. Vous pouvez :

• suivre les phases et règles directement dans votre propre environnement ;
• appliquer les patterns d’investigation et d’analyse à n’importe quel langage ou stack.

Les helpers TypeScript et Bash sont des accélérateurs optionnels, particulièrement utiles pour les environnements JS/TS et de type Unix.

Où trouver tout ce qui est inclus dans systematic-debugging ?

Après l’installation, ouvrez la vue Files ou repository pour obra/superpowers sous skills/systematic-debugging. Les fichiers clés à examiner sont :

• SKILL.md
• condition-based-waiting.md
• condition-based-waiting-example.ts
• defense-in-depth.md
• root-cause-tracing.md
• find-polluter.sh

Ils vous donnent le workflow complet de systematic-debugging, plus des outils concrets pour le débogage et la stabilisation des tests.