introspection-débogage-agent

Introspection-Débogage Agent

Utilisez cette compétence lorsqu'une exécution d'agent échoue de manière répétée, consomme des tokens sans progression, boucle sur les mêmes outils ou dérive de la tâche prévue.

Il s'agit d'une compétence de workflow, non d'un runtime caché. Elle apprend à l'agent à se déboguer systématiquement avant de faire appel à un humain.

Quand activer

• Limite maximale d'appels d'outils / boucles atteinte
• Relances répétées sans progression
• Croissance du contexte ou dérive des instructions qui dégrade la qualité des résultats
• Décalage entre l'état supposé du système de fichiers ou de l'environnement et la réalité
• Échecs d'outils probablement récupérables avec un diagnostic et une action corrective réduite

Périmètre

Activez cette compétence pour :

• capturer l'état de l'échec avant de relancer aveuglément
• diagnostiquer les schémas d'échec courants spécifiques aux agents
• appliquer des actions de récupération limitées
• produire un rapport de débogage structuré et lisible par un humain

N'utilisez pas cette compétence comme source principale pour :

• la vérification des fonctionnalités après des modifications de code ; utilisez verification-loop
• le débogage spécifique à un framework lorsqu'une compétence ECC plus ciblée existe déjà
• les promesses d'exécution que le harnais actuel ne peut pas appliquer automatiquement

Boucle en quatre phases

Phase 1 : Capture de l'échec

Avant d'essayer de récupérer, enregistrez précisément l'échec.

Capturez :

• le type d'erreur, le message et la trace de pile si disponible
• la dernière séquence significative d'appels d'outils
• ce que l'agent essayait de faire
• la pression actuelle sur le contexte : invites répétées, logs volumineux collés, plans dupliqués ou notes incontrôlées
• les hypothèses sur l'environnement : répertoire de travail, branche, état des services concernés, fichiers attendus

Modèle de capture minimal :

## Capture de l'échec
- Session / tâche :
- Objectif en cours :
- Erreur :
- Dernière étape réussie :
- Dernier outil / commande en échec :
- Schéma répété observé :
- Hypothèses sur l'environnement à vérifier :

Phase 2 : Diagnostic de la cause racine

Faites correspondre l'échec à un schéma connu avant de modifier quoi que ce soit.

Schéma	Cause probable	Vérification
Nombre maximal d'appels d'outils / même commande répétée	Boucle ou chemin d'observation sans sortie	Inspectez les N derniers appels d'outils pour détecter une répétition
Dépassement de contexte / raisonnement dégradé	Notes non limitées, plans répétés, logs volumineux	Inspectez le contexte récent à la recherche de duplication et de données peu significatives
ECONNREFUSED / délai d'attente	Service indisponible ou port erroné	Vérifiez l'état du service, l'URL et les hypothèses de port
429 / quota épuisé	Tempête de relances ou absence de backoff	Comptez les appels répétés et inspectez l'espacement des relances
Fichier manquant après écriture / diff obsolète	Condition de concurrence, mauvais répertoire de travail ou dérive de branche	Revérifiez le chemin, le répertoire de travail, le statut git et l'existence réelle du fichier
Tests toujours en échec après "correction"	Mauvaise hypothèse	Isolez le test exact en échec et redéduisez le bogue

Questions de diagnostic :

• s'agit-il d'un échec de logique, d'état, d'environnement ou de politique ?
• l'agent a-t-il perdu l'objectif réel pour optimiser une sous-tâche erronée ?
• l'échec est-il déterministe ou transitoire ?
• quelle est la plus petite action réversible qui validerait le diagnostic ?

Phase 3 : Récupération contrôlée

Récupérez avec la plus petite action qui modifie la surface de diagnostic.

Actions de récupération sûres :

• arrêtez les relances répétées et reformulez l'hypothèse
• réduisez le contexte peu pertinent et ne conservez que l'objectif actif, les obstacles et les preuves
• revérifiez l'état réel du système de fichiers / de la branche / du processus
• réduisez la tâche à une seule commande en échec, un seul fichier ou un seul test
• passez du raisonnement spéculatif à l'observation directe
• faites appel à un humain lorsque l'échec est à haut risque ou bloqué de manière externe

N'affirmez pas des actions de récupération non supportées comme "réinitialiser l'état de l'agent" ou "mettre à jour la configuration du harnais" à moins de les effectuer réellement via des outils réels dans l'environnement actuel.

Liste de vérification pour la récupération contrôlée :

## Action de récupération
- Diagnostic choisi :
- Plus petite action entreprise :
- Pourquoi c'est sûr :
- Quelle preuve prouverait que la correction a fonctionné :

Phase 4 : Rapport d'introspection

Terminez par un rapport qui rend la récupération compréhensible pour l'agent suivant ou un humain.

## Rapport d'auto-débogage de l'agent
- Session / tâche :
- Échec :
- Cause racine :
- Action de récupération :
- Résultat : succès | partiel | bloqué
- Risque de consommation de tokens / temps :
- Suivi nécessaire :
- Changement préventif à encoder ultérieurement :

Heuristiques de récupération

Privilégiez ces interventions dans l'ordre :

1. Reformulez l'objectif réel en une phrase.
2. Vérifiez l'état du monde au lieu de faire confiance à la mémoire.
3. Réduisez le périmètre de l'échec.
4. Exécutez une seule vérification discriminante.
5. Relancez seulement ensuite.

Mauvais schéma :

• relancer la même action trois fois avec un libellé légèrement différent

Bon schéma :

• capturer l'échec
• classifier le schéma
• exécuter une vérification directe
• modifier le plan uniquement si la vérification le justifie

Intégration avec ECC

• Utilisez verification-loop après la récupération si du code a été modifié.
• Utilisez continuous-learning-v2 lorsque le schéma d'échec mérite d'être transformé en instinct ou en compétence ultérieure.
• Utilisez council lorsque le problème n'est pas un échec technique mais une ambiguïté de décision.
• Utilisez workspace-surface-audit si l'échec provient d'un conflit d'état local ou d'une dérive du dépôt.

Standard de sortie

Lorsque cette compétence est active, ne terminez pas uniquement par "J'ai corrigé".

Fournissez toujours :

• le schéma d'échec
• l'hypothèse de cause racine
• l'action de récupération
• la preuve que la situation s'est améliorée ou est toujours bloquée