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 progrès, boucle sur les mêmes outils ou s'éloigne 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 solliciter un humain.

Quand Activer

• Limite maximale d'appels d'outils / boucles atteinte
• Nouvelles tentatives répétées sans avancement
• Croissance du contexte ou dérive de l'invite qui dégrade la qualité des résultats
• Écart entre l'état attendu et réel du système de fichiers ou de l'environnement
• Échecs d'outils probablement récupérables avec un diagnostic et une action corrective mineure

Périmètre

Activez cette compétence pour :

• capturer l'état d'échec avant de réessayer aveuglément
• diagnostiquer les schémas d'échec courants spécifiques aux agents
• appliquer des actions de récupération contenues
• 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 étroite existe déjà
• les promesses d'exécution que le harnais actuel ne peut pas appliquer automatiquement

Boucle en Quatre Phases

Phase 1 : Capture d'Échec

Avant de tenter 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 d'appels d'outils significative
• ce que l'agent essayait de faire
• la pression actuelle sur le contexte : invites répétées, journaux collés surdimensionnés, plans dupliqués ou notes hors de contrôle
• les hypothèses d'environnement actuelles : répertoire de travail, branche, état du service concerné, fichiers attendus

Modèle de capture minimal :

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

Phase 2 : Diagnostic de Cause Racine

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

Schéma	Cause probable	Vérification
Appels d'outils maximum / même commande répétée	boucle ou chemin d'observateur sans sortie	inspecter les N derniers appels d'outils pour détecter une répétition
Débordement de contexte / raisonnement dégradé	notes non limitées, plans répétés, journaux surdimensionnés	inspecter le contexte récent pour des duplications et du volume à faible signal
ECONNREFUSED / timeout	service indisponible ou mauvais port	vérifier l'état du service, l'URL et les hypothèses de port
429 / quota épuisé	tempête de nouvelles tentatives ou absence de backoff	compter les appels répétés et inspecter l'espacement des tentatives
fichier manquant après écriture / diff obsolète	condition de course, mauvais répertoire de travail ou dérive de branche	revérifier le chemin, le répertoire de travail, l'état git et l'existence réelle du fichier
tests toujours en échec après « correction »	mauvaise hypothèse	isoler le test exact qui échoue et redériver le bogue

Questions de diagnostic :

• s'agit-il d'un échec logique, d'un échec d'état, d'un échec d'environnement ou d'un échec de politique ?
• l'agent a-t-il perdu l'objectif réel et a-t-il commencé à optimiser la mauvaise sous-tâche ?
• 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 Contenue

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

Actions de récupération sûres :

• arrêter les tentatives répétées et reformuler l'hypothèse
• réduire le contexte à faible signal et ne conserver que l'objectif actif, les obstacles et les preuves
• revérifier l'état réel du système de fichiers / de la branche / du processus
• réduire la tâche à une seule commande en échec, un seul fichier ou un seul test
• passer du raisonnement spéculatif à l'observation directe
• solliciter un humain lorsque l'échec est à haut risque ou bloqué par une cause externe

Ne prétendez pas à des actions d'auto-guérison non prises en charge comme « réinitialiser l'état de l'agent » ou « mettre à jour la configuration du harnais » à moins de les exécuter réellement via des outils réels dans l'environnement actuel.

Liste de vérification de la récupération contenue :

## Action de Récupération
- Diagnostic choisi :
- Plus petite action effectuée :
- 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 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 plus tard :

Heuristiques de Récupération

Privilégiez ces interventions dans l'ordre :

1. Reformuler l'objectif réel en une phrase.
2. Vérifier l'état du monde au lieu de faire confiance à la mémoire.
3. Réduire le périmètre en échec.
4. Effectuer une vérification discriminante.
5. Ensuite seulement, réessayer.

Mauvais schéma :

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

Bon schéma :

• capturer l'échec
• classer le schéma
• effectuer une vérification directe
• modifier le plan uniquement si la vérification le soutient

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 état local conflictuel ou d'une dérive du dépôt.

Standard de Sortie

Lorsque cette compétence est active, ne terminez pas uniquement par « Je l'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 est maintenant meilleure ou toujours bloquée