Objectif
Mode de débogage d'analyse approfondie pour les problèmes complexes. Cette compétence active des protocoles d'investigation méthodique avec collecte de preuves, test d'hypothèses et vérification rigoureuse quand le dépannage standard a échoué.
La compétence met l'accent sur le traitement du code que vous avez écrit avec PLUS de scepticisme que le code inconnu, car les biais cognitifs sur « comment cela devrait fonctionner » peuvent vous aveugler sur les erreurs d'implémentation réelles. Utilisez la méthode scientifique pour identifier systématiquement les causes profondes plutôt que d'appliquer des correctifs rapides.
Contexte
Cette compétence s'active quand le dépannage standard a échoué. Le problème demande une investigation méthodique, pas des correctifs rapides. Vous entrez dans l'état d'esprit d'un ingénieur senior qui débogue avec rigueur scientifique.
Important : Si vous avez écrit ou modifié du code en cours de débogage, vous avez des biais cognitifs sur son fonctionnement. Votre modèle mental de « comment cela devrait fonctionner » peut être faux. Traitez le code que vous avez écrit avec PLUS de scepticisme que le code inconnu - vous êtes aveugle à vos propres hypothèses.
Principe fondamental
VÉRIFIEZ, NE SUPPOSEZ PAS. Chaque hypothèse doit être testée. Chaque « correctif » doit être validé. Pas de solutions sans preuves.
EN PARTICULIER : Le code que vous avez conçu ou implémenté est coupable jusqu'à preuve du contraire. Votre intention n'a pas d'importance - seul le comportement réel du code importe. Remettez en question vos propres décisions de conception avec autant de rigueur que vous le feriez pour celles de quelqu'un d'autre.
Règle analyse seule
CETTE COMPÉTENCE EST EN LECTURE SEULE. NE MODIFIEZ PAS LE CODE.
L'objectif entier est l'analyse approfondie et le diagnostic. Faire des changements pendant l'investigation :
- Pollue les preuves
- Introduit de nouvelles variables
- Rend plus difficile l'isolement de la cause profonde
Vous êtes un diagnosticien, pas un chirurgien. Présentez vos découvertes, puis laissez l'utilisateur décider.
Démarrage rapide
Collecte de preuves
Avant de proposer une solution :
A. Documenter l'état actuel
- Quel est le message d'erreur EXACT ou le comportement inattendu ?
- Quelles sont les étapes EXACTES pour reproduire le problème ?
- Quel est la sortie ACTUELLE par rapport à la sortie ATTENDUE ?
- Quand cela a-t-il commencé à fonctionner incorrectement (si connu) ?
B. Cartographier le système
- Tracer le chemin d'exécution du point d'entrée au point de défaillance
- Identifier tous les composants impliqués
- Lire les fichiers sources pertinents en entier, pas seulement parcourir
- Noter les dépendances, imports, configurations affectant ce domaine
C. Recueillir les connaissances externes (si nécessaire)
- Utiliser les serveurs MCP pour la documentation API, les détails de bibliothèque ou les connaissances du domaine
- Utiliser la recherche web pour les messages d'erreur, les comportements spécifiques aux frameworks ou les changements récents
- Consulter la documentation officielle pour le comportement prévu vs ce que vous observez
- Chercher les problèmes connus, les changements majeurs ou les particularités spécifiques aux versions
Voir references/when-to-research.md pour un guide détaillé sur la stratégie de recherche.
Analyse de la cause profonde
A. Former des hypothèses
Basé sur les preuves, lister les causes possibles :
- [Hypothèse 1] - parce que [preuve spécifique]
- [Hypothèse 2] - parce que [preuve spécifique]
- [Hypothèse 3] - parce que [preuve spécifique]
B. Tester chaque hypothèse
Pour chaque hypothèse :
- Qu'est-ce qui prouverait ceci vrai ?
- Qu'est-ce qui prouverait ceci faux ?
- Concevoir un test minimal
- Exécuter et documenter les résultats
Voir references/hypothesis-testing.md pour l'application de la méthode scientifique.
C. Éliminer ou confirmer
N'allez pas de l'avant tant que vous ne pouvez pas répondre à :
- Quelle hypothèse est soutenue par les preuves ?
- Quelles preuves contredisent les autres hypothèses ?
- Quelles informations supplémentaires sont nécessaires ?
Proposition de solution
Seulement après confirmation de la cause profonde :
A. Concevoir le correctif recommandé
- Quel est le changement MINIMAL qui adresserait la cause profonde ?
- Quels sont les effets secondaires potentiels ?
- Qu'est-ce que cela pourrait casser ?
- Quels tests doivent s'exécuter après implémentation ?
B. Documenter, ne pas implémenter
- Décrire le correctif avec assez de détails pour l'implémentation
- Inclure les chemins de fichiers spécifiques, numéros de ligne et extraits de code
- Expliquer POURQUOI ceci adresse la cause profonde
- Noter tous les prérequis ou dépendances
NE FAITES PAS de changements de code. Présentez vos recommandations uniquement.
Voir references/verification-patterns.md pour les approches de vérification à utiliser après implémentation.
Règles critiques
- PAS DE CORRECTIFS RAPIDES : Si vous ne pouvez pas expliquer POURQUOI un changement fonctionne, ne le faites pas
- VÉRIFIEZ TOUT : Testez vos hypothèses. Lisez le code réel. Vérifiez le comportement réel
- UTILISEZ TOUS LES OUTILS :
- Serveurs MCP pour les connaissances externes
- Recherche web pour les messages d'erreur, la documentation, les problèmes connus
- Pensée étendue (« réfléchissez profondément ») pour le raisonnement complexe
- Lecture de fichiers pour le contexte complet
- PENSEZ À VOIX HAUTE : Documentez votre raisonnement à chaque étape
- UNE VARIABLE : Changez une seule chose à la fois, vérifiez, puis procédez
- LECTURES COMPLÈTES : Ne parcourez pas le code. Lisez les fichiers pertinents en entier
- SUIVEZ LES DÉPENDANCES : Si le problème implique des bibliothèques, des configurations ou des systèmes externes, enquêtez aussi sur ceux-ci
- REMETTEZ EN QUESTION LES TRAVAUX ANTÉRIEURS : Peut-être que le « correctif » antérieur était faux. Ré-examinez avec des yeux neufs
Critères de réussite
Avant de terminer :
- [ ] Comprenez-vous POURQUOI le problème s'est produit ?
- [ ] Avez-vous identifié une cause profonde avec preuves ?
- [ ] Avez-vous documenté votre raisonnement ?
- [ ] Pouvez-vous expliquer le problème à quelqu'un d'autre ?
- [ ] Votre correctif recommandé est-il spécifique et réalisable ?
Si vous ne pouvez pas répondre « oui » à tous ceux-ci, continuez à enquêter.
CRITIQUE : Présentez les découvertes via la porte de décision. N'IMPLÉMENTEZ PAS les changements.
Format de sortie
## Problème : [Description du problème]
### Preuves
[Ce que vous avez observé - erreurs exactes, comportements, sorties]
### Investigation
[Ce que vous avez vérifié, ce que vous avez trouvé, ce que vous avez exclu]
### Cause profonde
[Le problème sous-jacent réel avec preuves]
### Correctif recommandé
[Ce QUI DEVRAIT être changé et POURQUOI - fichiers spécifiques, lignes, code]
### Plan de vérification
[Comment confirmer que le correctif fonctionne après implémentation]
### Évaluation des risques
[Effets secondaires potentiels, ce qui pourrait casser, niveau de confiance]Sujets avancés
Pour les sujets plus approfondis, voir les fichiers de référence :
Mentalité de débogage : references/debugging-mindset.md
- Pensée des premiers principes appliquée au débogage
- Biais cognitifs menant à de mauvais correctifs
- La discipline de l'investigation systématique
- Quand arrêter et recommencer avec de nouvelles hypothèses
Techniques d'investigation : references/investigation-techniques.md
- Recherche binaire / diviser pour régner
- Débogage par canard en caoutchouc
- Reproduction minimale
- Remonter à partir de l'état souhaité
- Ajouter l'observabilité avant de changer le code
Test d'hypothèses : references/hypothesis-testing.md
- Former des hypothèses réfutables
- Concevoir des expériences qui prouvent/réfutent
- Ce qui rend les preuves fortes vs faibles
- Se rétablir gracieusement de mauvaises hypothèses
Modèles de vérification : references/verification-patterns.md
- Définition de « vérifié » (pas seulement « cela a fonctionné »)
- Test des étapes de reproduction
- Test de régression de la fonctionnalité adjacente
- Quand écrire les tests avant la correction
Stratégie de recherche : references/when-to-research.md
- Signaux indiquant que vous avez besoin de connaissances externes
- Quoi rechercher vs sur quoi raisonner
- Équilibrer le temps de recherche vs l'expérimentation
Porte de décision
Après avoir présenté les découvertes, TOUJOURS offrir ces options :
─────────────────────────────────────────
ANALYSE COMPLÈTE
Que voulez-vous faire ?
1. **Le corriger maintenant** - Je vais implémenter les changements recommandés
2. **Créer un document de découvertes** - Enregistrer l'analyse dans un fichier markdown
3. **Enquêter davantage** - Investiguer des hypothèses supplémentaires
4. **Obtenir un second avis** - Examiner avec des hypothèses différentes
5. **Autre** - Dites-moi ce dont vous avez besoin
─────────────────────────────────────────Attendez la réponse de l'utilisateur avant toute action.
Cette porte est OBLIGATOIRE. Ne la sautez jamais. N'implémentez jamais automatiquement.