Que fait Apprentissage par Rétrospective ?
Utilisez cette compétence pour transformer les leçons vérifiées en contexte durable pour les agents futurs, afin qu'un problème résolu une fois ne soit jamais résolu de nouveau par essais et erreurs. Gardez la tâche principale en mouvement ; la rétrospective doit être une courte boucle de contrôle, pas un nouveau projet.
L'échec n'est pas une erreur. Les tentatives répétées sur un problème nouveau sont une exploration légitime et ne doivent pas être supprimées - la seule discipline dont un problème nouveau a besoin est de ne pas répéter textuellement les mêmes commandes et de faire une seule hypothèse explicite par tentative. Le comportement que cette compétence existe pour éliminer est différent : se débattre avec le même problème une seconde fois parce que la première solution n'a jamais été capturée, ou a été capturée mais pas rappelée. La compétence a donc deux modes aux forces différentes :
- Problème connu (une leçon stockée ou un souvenir couvre cette signature d'échec) : intervenir tôt - rappeler la leçon avant la prochaine tentative et la suivre.
- Problème nouveau (aucune leçon antérieure) : ne pas interrompre l'exploration. Varier l'approche au lieu de réessayer textuellement, résoudre, puis capturer la leçon après.
Capture Post-Résolution
C'est le mode automatique principal. Après la réussite d'une tâche, vérifiez une question avant de terminer le tour : le fait d'arriver ici a-t-il impliqué deux tentatives échouées ou plus, une solution de contournement non évidente, un fait spécifique à la machine, ou un ordre des opérations qu'un agent futur devrait redécouvrir ? Si oui, exécutez les étapes 5 à 6 du Workflow (capturer la leçon, la stocker dans la bonne surface, soumise à la Gate d'Autorisation d'Écriture). Si non, terminez normalement - ne fabriquez pas de leçons à partir d'un travail de routine.
La capture doit avoir lieu pendant que la preuve est encore en contexte : commandes exactes, texte d'erreur exact, ce qui a été essayé et pourquoi cela a échoué. Une leçon écrite de mémoire après la lutte vaut moins qu'une leçon écrite à partir de la transcription de celle-ci.
Signaux de Boucle
Déclenchez une rétrospective lorsqu'un ou plusieurs signaux apparaissent :
- La même commande, le même test, la même conversion, la même installation, le même appel API ou la même action UI échoue deux fois.
- L'agent commence une découverte large après qu'un fait local vérifié aurait dû être vérifié.
- L'agent change d'outils à plusieurs reprises sans nouvelle hypothèse.
- L'utilisateur dit que l'agent boucle, a oublié le travail antérieur, ou devrait se souvenir de la leçon.
- Un correctif dépend de chemins spécifiques à la machine, de variables d'environnement, d'outils installés, de flux d'identification, de l'état du compte ou de conventions de projet.
- Un échec a été résolu par une commande non évidente, une solution de contournement locale ou un ordre des opérations.
N'exécutez pas ce workflow pour chaque petite erreur. Utilisez-le lorsque la leçon est réutilisable ou que le comportement actuel commence à faire perdre du temps.
Non-Déclencheurs
N'invoquez pas cette compétence pour :
- Une erreur ordinaire de première fois avec un correctif évident suivant.
- Un débogage normal où chaque tentative produit de nouvelles preuves.
- Des tâches de pure explication, résumé, traduction ou rédaction.
- Une revue large de projet à moins qu'un schéma d'échec répété ne soit déjà apparu.
- Des mises à jour de mémoire demandées par l'utilisateur qui n'impliquent pas une leçon de workflow.
Gate d'Autorisation d'Écriture
Avant d'écrire dans la mémoire utilisateur, la documentation du dépôt, les règles du projet ou une autre compétence :
- Si l'utilisateur a explicitement demandé de sauvegarder, mettre à jour ou écrire la leçon, procédez.
- Sinon, présentez d'abord la leçon proposée et la surface cible.
- Ne modifiez jamais silencieusement les instructions du projet, les compétences ou la mémoire persistante.
- Ne stockez jamais de secrets, jetons, identifiants, cookies, données privées ou longs journaux bruts.
Workflow
-
Pausez la boucle.
- Arrêtez les tentatives textuelles répétées, la recherche large sans focus et les modifications spéculatives.
- Énoncez l'objectif immédiat, la dernière action en échec et l'erreur ou le symptôme exact.
- Préservez tout processus en cours ou donnée utilisateur avant de changer de cap.
-
Reconstruisez la preuve et classez le problème.
- Cherchez d'abord dans la mémoire existante et les directives du projet cette signature d'échec. Si une leçon antérieure la couvre, il s'agit d'un problème connu : suivez la leçon au lieu de la redériver.
- Si rien ne la couvre, il s'agit d'un problème nouveau : continuez à explorer avec des hypothèses variées et planifiez de capturer la leçon après résolution.
- Listez ce qui est déjà vérifié, y compris les chemins, versions, commandes, sorties et fichiers.
- Préférez une vérification peu coûteuse des faits sujets à dérive plutôt que des hypothèses.
-
Choisissez une seule hypothèse suivante.
- Choisissez la plus petite commande ou modification qui teste directement l'hypothèse principale.
- Ajoutez une porte d'échec : définissez quel résultat signifie succès, quel résultat signifie arrêt, et quel repli est autorisé.
- Évitez de tomber dans une découverte de repli sans rapport lorsque la porte échoue.
-
Terminez d'abord la tâche utilisateur.
- Corrigez, convertissez, installez, testez ou configurez la cible réelle.
- Vérifiez avec des preuves observées, pas par confiance.
- Gardez les sauvegardes temporaires et supprimez-les après que l'utilisateur a confirmé qu'elles ne sont plus nécessaires.
-
Capturez la leçon.
- Enregistrez seulement les leçons qui sont vérifiées, réutilisables et non évidentes.
- Incluez les commandes exactes, chemins, versions, texte d'échec et le meilleur ordre des opérations.
- Excluez les secrets, données privées, longs journaux et suppositions non vérifiées.
- Préférez une petite mise à jour de mémoire plutôt qu'un long récit.
-
Stockez-la dans la bonne surface.
- Passez la Gate d'Autorisation d'Écriture avant de faire des modifications persistantes.
- Utilisez la mémoire au niveau utilisateur pour les faits de machine ou de préférence transversaux aux projets.
- Utilisez les docs du dépôt/projet pour les conventions spécifiques au projet.
- Mettez à jour une compétence existante uniquement lorsque la leçon modifie une procédure réutilisable.
- Créez une nouvelle compétence uniquement lorsque la procédure est récurrente, portable et vaut la peine d'être déclenchée automatiquement.
- Voir
references/memory-surfaces.mdpour des conseils de placement indépendants de la plateforme.
-
Optionnellement, demandez un relecteur indépendant.
- Utilisez tout agent secondaire, modèle, invite de relecteur ou session fraîche disponible ; n'exigez pas un fournisseur ou modèle spécifique.
- Donnez-lui seulement les chemins des artefacts, le résumé de la boucle échouée et les questions de validation concrètes.
- Demandez la plus petite amélioration de sécurité ou de clarté.
- S'il n'existe pas de sous-agent, exécutez vous-même la même liste de vérification.
- Voir
references/reviewer-prompt.md.
Activation Automatique
Cette compétence est normalement rappelée via sa description, qui est la plus faible exactement lorsqu'un agent est en milieu de boucle. Si votre hôte prend en charge les hooks ou les callbacks d'événements d'outils, câblez un détecteur d'échec répété qui injecte un rappel pour invoquer cette compétence. Les scripts détecteurs exécutables se trouvent dans hooks/ (variantes Claude Code et Codex) avec une suite de tests automatisée dans tests/ ; voir references/hook-activation.md pour l'enregistrement, les exigences de confiance et le modèle général pour les autres hôtes. Traitez toute configuration de hook que vous écrivez comme un artefact soumis aux propres règles de cette compétence : exécutez la suite de tests, puis forcez un vrai échec pour prouver qu'il se déclenche, avant de lui faire confiance.
Exemples
Utilisez les exemples comme ancres pour le déclencheur et le comportement d'exécution :
examples/pdf-rendering-loop.mdexamples/github-actions-loop.mdexamples/docx-conversion-loop.mdexamples/zotero-linked-attachment-loop.mdexamples/dependency-install-loop.mdexamples/filled-lesson-libreoffice.md(une leçon complétée, pas un modèle)examples/bad-lessons.md(anti-exemples : des captures qui empoisonnent la mémoire)
Modèle de Leçon
# Leçon : <nom court>
## Déclencheur
- Quel schéma devrait faire qu'un agent futur se souvienne de ceci ?
## Faits Vérifiés
- Chemins, versions, commandes, fichiers ou état du compte exacts.
## Tentatives Échouées À Éviter
- Tentatives qui ont été essayées et pourquoi elles étaient erronées ou inutiles.
## Procédure Préférée
1. Première commande/vérification.
2. Porte de validation.
3. Repli uniquement si la porte échoue.
## Preuve de Validation
- La commande exacte et la sortie observée qui ont prouvé que la procédure préférée fonctionne.
## Risque de Dérive
- Ce qui peut invalider cette leçon : version, chemin, forme de l'API, état du compte, OS, permissions.
## Dernière Vérification
- YYYY-MM-DD
## Portée
- S'applique à : <machine/projet/outil/contexte>
- Ne s'applique pas à : <limites connues>
Réponse Finale
Dites à l'utilisateur :
- Quelle boucle a été détectée.
- Quel résultat de tâche a été atteint.
- Quelle leçon a été capturée et où elle a été écrite.
- Quelle limitation persiste, surtout si les agents futurs doivent explicitement charger la mémoire ou invoquer la compétence.