systematic-debugging

Présentation de la skill systematic-debugging

La skill systematic-debugging propose un workflow de débogage structuré pour les agents et les développeurs qui veulent réduire les correctifs au hasard et aller plus vite jusqu’à la cause racine. Sa règle centrale est simple : enquêter avant de modifier le code. C’est donc une très bonne option pour les échecs de tests, les comportements intermittents, les bugs en production, les problèmes de build et les soucis d’intégration où un « correctif rapide » risque surtout de masquer le vrai problème.

À qui la skill systematic-debugging convient le mieux

Utilisez systematic-debugging si vous :

• enchaînez les correctifs qui échouent ou ne règlent le problème qu’en partie
• déboguez sous pression
• avez besoin qu’un assistant IA ralentisse le rythme et enquête au lieu de patcher les symptômes
• cherchez un processus reproductible pour les bugs, les tests flaky et les comportements inattendus

Elle est particulièrement utile quand le problème paraît évident, mais que vous ne savez pas encore pourquoi il se produit.

La vraie tâche que cette skill vous aide à accomplir

Le vrai objectif n’est pas « produire un correctif ». Il consiste à :

1. reproduire le problème,
2. remonter à la cause,
3. tester une explication à la fois,
4. puis seulement appliquer un correctif ciblé.

Cela semble plus lent, mais dans la pratique cela réduit souvent les retouches, les patchs ratés et les nouveaux bugs introduits par des suppositions.

Ce qui distingue systematic-debugging

La plupart des prompts classiques passent directement du symptôme à la solution. La systematic-debugging skill, elle, prend clairement position contre cette approche. Le repo met en avant un workflow de type « Iron Law » : pas de correctif sans enquête préalable sur la cause racine.

Les fichiers autour de la skill la rendent aussi bien plus concrète qu’une simple checklist de débogage :

• root-cause-tracing.md aide quand l’erreur visible est très éloignée de sa vraie source
• condition-based-waiting.md aide sur les tests async flaky provoqués par des délais arbitraires
• defense-in-depth.md aide à transformer un correctif ponctuel de validation en prévention plus structurelle
• find-polluter.sh aide à isoler les tests qui laissent fuiter des fichiers ou de l’état

Types de problèmes pour lesquels systematic-debugging est le plus pertinent

systematic-debugging for Debugging est particulièrement adapté à :

• des tests qui échouent sans explication claire à ce stade
• des tests flaky dans la CI
• des bugs que des correctifs précédents n’ont pas réellement résolus
• des erreurs qui apparaissent profondément dans la stack
• des états corrompus, des fichiers laissés derrière, de mauvais chemins, des race conditions et des problèmes de timing

Cas où cette skill est moins adaptée

Évitez-la seulement si la tâche n’est pas réellement du débogage, par exemple :

• un travail de feature simple
• des refactors de routine sans comportement défaillant à expliquer
• des modifications purement cosmétiques

Même dans ces cas, si vous réagissez à un « comportement inattendu », systematic-debugging reste généralement le point de départ le plus sûr.

Comment utiliser la skill systematic-debugging

Contexte d’installation pour systematic-debugging

Si vous utilisez le modèle Skills CLI présent dans cet écosystème, installez-la avec :

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

Vous pouvez ensuite l’appeler depuis votre environnement d’agent ou appliquer son processus manuellement en lisant les fichiers sources du dossier de la skill.

Les fichiers à lire en priorité

Pour un systematic-debugging guide rapide et vraiment utile, lisez dans cet ordre :

1. skills/systematic-debugging/SKILL.md
2. skills/systematic-debugging/root-cause-tracing.md
3. skills/systematic-debugging/condition-based-waiting.md
4. skills/systematic-debugging/defense-in-depth.md
5. skills/systematic-debugging/find-polluter.sh

Pourquoi cet ordre :

• SKILL.md présente le workflow obligatoire en quatre phases
• root-cause-tracing.md aide quand les symptômes apparaissent très en aval
• condition-based-waiting.md fournit un schéma de correction concret pour les tests async flaky
• defense-in-depth.md aide à renforcer le correctif final
• find-polluter.sh est un outil pratique pour isoler la pollution entre tests

Les entrées dont la skill a besoin

La qualité de systematic-debugging usage dépend fortement de ce que vous fournissez. Donnez à la skill :

• le message d’erreur exact
• la stack trace
• les étapes de reproduction
• le comportement attendu vs le comportement observé
• les détails d’environnement comme l’OS, le runtime, le test runner, et si le problème n’apparaît qu’en CI ou seulement en local
• les changements de code récents
• le fait que le problème soit déterministe ou flaky
• ce que vous avez déjà essayé

Sans ces éléments, le modèle risque davantage de spéculer.

Transformer un bug report approximatif en prompt solide

Prompt faible :

Test is failing. Help fix it.

Prompt plus solide :

Use systematic-debugging on this failing test. Do not propose a fix until root cause investigation is complete. Here is the exact error, stack trace, reproduction command, recent changes, and the one behavior difference between local and CI. Identify likely root causes, suggest the minimum investigation steps, and keep hypotheses separate.

Ce prompt fonctionne mieux parce qu’il demande d’abord un résultat d’enquête avant toute implémentation.

Un modèle de prompt pratique

Utilisez cette structure pour systematic-debugging usage :

• Problème : ce qui a échoué
• Reproduction : commande exacte ou étapes précises
• Éléments de preuve : logs, trace, captures, assertion qui échoue
• Portée : local, CI, une machine, tous les environnements
• Changements récents : commits, mises à jour de dépendances, modifications de config
• Contraintes : impossible de changer l’API, patch minimal requis, deadline, etc.
• Demande : enquêter d’abord sur la cause racine, puis proposer un seul correctif

Exemple :

Use systematic-debugging for this Jest failure. Repro: npm test src/foo.test.ts. Error: Timeout waiting for TOOL_RESULT event after 5000ms. It fails in CI and under parallel runs, not always locally. We recently changed thread event handling. First investigate root cause, then propose one focused fix and one validation plan.

Suivre le workflow systematic-debugging en quatre phases, dans l’ordre

Le repo s’articule autour de quatre phases. En pratique, utilisez-les ainsi :

1. Enquête sur la cause racine
   Lisez l’erreur attentivement, reproduisez le problème de façon fiable, examinez ce qui a changé et rassemblez des preuves.
2. Analyse des patterns
   Cherchez des schémas liés au timing, à l’environnement, à la forme des entrées, aux fuites d’état ou à la chaîne d’appels.
3. Test des hypothèses
   Formulez une explication à la fois et testez-la. Évitez de modifier plusieurs variables en même temps.
4. Implémentation
   Une fois la cause étayée par les preuves, appliquez le correctif et validez-le.

Si la phase 1 est faible, toutes les étapes suivantes se dégradent.

Comment utiliser systematic-debugging sur des tests flaky

Ce repo est particulièrement concret sur ce point. Si un test repose sur sleep, setTimeout ou des attentes arbitraires, consultez condition-based-waiting.md et condition-based-waiting-example.ts.

Le changement de logique essentiel :

• mauvais pattern : deviner combien de temps prend le travail async
• meilleur pattern : attendre la condition qui prouve que le traitement est terminé

C’est important, car beaucoup d’échecs « aléatoires » sont en réalité des race conditions masquées par des suppositions de timing.

Comment utiliser systematic-debugging quand le symptôme est en aval

Si l’erreur apparaît profondément dans une stack ou loin de l’endroit où les mauvaises données sont apparues, utilisez root-cause-tracing.md. Le workflow est le suivant :

• identifier la ligne qui échoue immédiatement
• remonter d’un appelant
• continuer à remonter jusqu’au premier point où le mauvais état apparaît
• corriger à la source, pas uniquement à l’endroit du crash

C’est l’une des parties les plus utiles de la systematic-debugging skill, parce que beaucoup de bugs ne sont en fait que les symptômes d’un état invalide apparu plus tôt.

Comment utiliser l’outil de détection de pollueur

Pour les tests qui laissent derrière eux des fichiers, des répertoires ou de l’état, find-polluter.sh mérite d’être lu avant d’improviser votre propre boucle.

Schéma d’utilisation :
./find-polluter.sh <file_or_dir_to_check> <test_pattern>

Exemple tiré du script :
./find-polluter.sh '.git' 'src/**/*.test.ts'

C’est utile quand l’échec vient d’une pollution cachée entre tests, et non du test qui échoue de façon visible.

Workflow courant qui donne les meilleurs résultats

Un workflow fiable pour systematic-debugging install et une première utilisation :

1. installer la skill
2. lire SKILL.md
3. collecter les preuves exactes de l’échec
4. demander à l’agent d’enquêter sans corriger
5. retenir l’hypothèse la mieux étayée par les preuves
6. tester uniquement cette hypothèse
7. appliquer un seul correctif ciblé
8. ajouter une validation ou une approche de defense-in-depth si le bug vient de données invalides ou de plusieurs chemins d’entrée

Cela évite le mode d’échec le plus fréquent : modifier le code avant d’avoir compris la panne.

Ce qu’il ne faut pas faire avec cette skill

Ne demandez pas à systematic-debugging de :

• brainstormer immédiatement une liste de correctifs
• réécrire de larges pans de code avant d’avoir reproduit le bug
• « juste faire passer le test » sans explication
• patcher plusieurs causes suspectées d’un coup

Ces raccourcis vont directement à l’encontre de la logique de la skill et dégradent la qualité des résultats.

FAQ sur la skill systematic-debugging

systematic-debugging est-il réservé aux bugs complexes ?

Non. La position du repo est que même les bugs simples ont une cause racine. La skill est particulièrement utile quand un problème semble assez simple pour donner envie de poser un patch rapide.

En quoi est-ce différent d’un prompt de débogage classique ?

Un prompt classique valorise souvent la vitesse et les correctifs spéculatifs. systematic-debugging oblige le modèle à séparer l’enquête, l’hypothèse et l’implémentation. Cela produit généralement moins de patchs incorrects et de meilleures explications.

systematic-debugging est-il accessible aux débutants ?

Oui, à condition de pouvoir fournir des éléments concrets. Le processus est strict, mais les étapes sont faciles à comprendre : reproduire, inspecter, remonter la cause, tester une idée, puis corriger. Les débutants peuvent même en tirer encore plus de bénéfices, car cela évite les essais-erreurs au hasard.

Quand ne faut-il pas utiliser systematic-debugging ?

N’en faites pas votre modèle principal pour :

• l’idéation de features
• le brainstorming d’architecture
• la génération de code sans lien avec une panne
• les retouches purement visuelles sans comportement cassé à expliquer

Utilisez-le quand quelque chose ne va pas et que vous avez besoin de la cause, pas seulement d’un patch.

systematic-debugging aide-t-il sur les échecs qui n’apparaissent qu’en CI ?

Oui. Il est bien adapté aux échecs propres à la CI ou sensibles à la charge, parce qu’il vous pousse à comparer les environnements, reproduire les conditions et examiner les hypothèses de timing et d’état au lieu de deviner.

Peut-il aider sur des tests async flaky ?

Oui, et ce repo est plus solide que la moyenne sur ce sujet. condition-based-waiting.md et l’exemple TypeScript fournissent une voie concrète pour sortir des attentes arbitraires et aller vers une synchronisation basée sur des conditions.

La skill inclut-elle des outils ou seulement des conseils ?

Principalement un cadre de travail, avec quelques fichiers compagnons concrets. L’outil le plus pratique est find-polluter.sh, et l’exemple sur l’attente conditionnelle est directement réutilisable dans certaines configurations de tests TypeScript.

Puis-je utiliser systematic-debugging avec n’importe quelle stack ?

Dans l’ensemble, oui. La méthode de base est indépendante de la stack. Les exemples penchent plutôt vers TypeScript, le shell et les workflows de test, mais le processus d’enquête fonctionne à travers les langages et les frameworks.

Comment améliorer l’usage de la skill systematic-debugging

Fournir de meilleures preuves avant de demander un correctif

Le principal levier, c’est la qualité des entrées. Pour de meilleurs résultats avec systematic-debugging, incluez :

• une commande de reproduction exacte
• un bloc d’erreur exact
• un test ou fichier minimal qui échoue
• ce qui a changé récemment
• le fait que le problème soit toujours reproductible ou non

Cela aide la skill à travailler sur des preuves plutôt que sur des inférences.

Demander un résultat d’enquête avant toute implémentation

Un prompt performant bloque explicitement les correctifs trop précoces. Par exemple :

Use systematic-debugging. First produce root-cause investigation findings and the top 2 hypotheses with evidence for each. Do not suggest code changes yet.

Cela améliore la qualité des réponses en créant un point de contrôle entre la lecture du symptôme et l’édition du code.

Imposer une hypothèse à la fois

Un mode d’échec fréquent consiste à mélanger plusieurs causes possibles dans un seul patch. Demandez :

• l’hypothèse principale
• le plus petit test capable de la réfuter
• le résultat qui la confirmerait

Vous gardez ainsi le workflow aligné avec l’intention de la skill.

Améliorer les prompts pour les scénarios de tests flaky

Quand vous utilisez systematic-debugging for Debugging sur des tests flaky, fournissez :

• la fréquence de réussite / échec
• le fait que les échecs soient corrélés ou non au parallélisme ou à la CI
• toute utilisation de sleeps, waits, retries ou polling
• l’événement exact ou l’état exact que le test essaie d’observer

Cela aide beaucoup le modèle à reconnaître quand condition-based-waiting.md est le pattern compagnon pertinent.

Utiliser les fichiers proches du code source, pas seulement SKILL.md

Si la première réponse reste générique, orientez le modèle vers les docs de support :

• root-cause-tracing.md pour les symptômes en aval
• condition-based-waiting.md pour les problèmes de timing ou de race conditions
• defense-in-depth.md pour la stratégie de validation
• find-polluter.sh pour la pollution entre tests

La skill devient meilleure quand l’agent exploite ces ressources spécialisées, et pas seulement le workflow principal.

Réduire le périmètre après le premier passage

Si le premier résultat est trop large, affinez avec :

• le sous-système exact à inspecter
• la frontière suspectée où les mauvaises données entrent
• le premier commit où le problème est apparu
• la plus petite reproduction qui échoue

Les prompts de débogage trop larges produisent souvent des plans de débogage trop larges. Un périmètre plus resserré donne un meilleur travail sur la cause racine.

Améliorer le correctif final, pas seulement le diagnostic

Une fois la cause racine trouvée, demandez :

• le correctif minimal
• un test de régression
• une couche de validation qui empêche la récidive

C’est là que defense-in-depth.md devient utile. Si le bug vient d’entrées invalides ou d’hypothèses faciles à contourner, un patch unique peut ne pas suffire.

Surveiller ces modes d’échec fréquents

Un mauvais systematic-debugging usage vient généralement de :

• texte d’erreur incomplet
• absence de reproduction fiable
• demande de correctif trop précoce
• modifications multiples entre les exécutions de test
• première explication plausible traitée comme si elle était prouvée

Si vous évitez cela, la skill devient nettement plus utile qu’un simple prompt générique du type « debug this ».