Debrief

Que fait Debrief ?

Un débriefing est l'instrument d'un méta-objectif permanent : un processus qui améliore nos processus. Il examine comment la personne et l'agent ont travaillé ensemble, avec des preuves, et transforme ce qu'il trouve en trois types de résultats : des leçons pour l'agent (instructions, compétences, workflows, hooks), des leçons pour la personne (comment mieux diriger l'agent) et des modifications de la configuration du projet. Il est honnête dans les deux sens et ne fabrique jamais de critique : une session qui s'est bien déroulée donne un rapport court.

Structure et règles adaptées de deux compétences sous licence MIT, avec remerciements : debrief par Wavez (les quatre groupes de vérification, « chaque constat cite un moment », rien n'est appliqué sans approbation) et retrospective par florianbuetow (rapports conservés comme historique, recommandations antérieures vérifiées et problèmes récurrents escaladés, cause racine et suggestion par constat). La section de coaching, l'habitude des cinq pourquoi et le script d'utilisation sont propres à cette compétence.

Entrées

1. La conversation. La source principale : appels d'outils, questions et quand elles ont été posées, corrections et confirmations par l'utilisateur, rapports des sous-agents, erreurs et tentatives. Si la session a été compactée, mentionnez-le dans le rapport et traitez le résumé comme une preuve de moindre confiance ; n'inventez pas de moments pour la partie que vous ne pouvez pas voir.

2. Les chiffres. Exécutez le script fourni pour l'utilisation de la session : tours, appels d'outils par nom, sous-agents et workflows avec leurs tokens, modèles utilisés, tokens de sortie par modèle, durée, compactages. Il lit la transcription de la session sous ~/.claude/projects/<slug-du-projet>/ et le répertoire subagents/ à côté. L'utilisateur peut demander une autre session ; passez alors son identifiant.

   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/usage.py            # la session en cours (transcription la plus récente de ce projet)
   python3 ${CLAUDE_PLUGIN_ROOT}/scripts/usage.py <id-de-session>
   

3. Le dossier du projet. Les fichiers d'instructions (CLAUDE.md, AGENTS.md), le backlog et le journal de décisions si le projet les conserve, et les mémoires de feedback de l'agent pour ce projet (~/.claude/projects/<slug-du-projet>/memory/), afin qu'une erreur répétée soit reconnue comme une répétition.

4. Les débriefings antérieurs. Les trois derniers rapports dans le répertoire des rapports (ci-dessous). Pour chaque recommandation qu'ils contiennent, notez si elle a été suivie d'effet, si elle est récurrente ou si son statut est inconnu ; un problème récurrent est escaladé en sévérité.

Adaptez l'effort à la période : une session courte et propre reçoit un passage rapide ; une session de plusieurs semaines reçoit le traitement complet, et les cinq pourquoi sur les schémas les plus importants.

Ce qu'il faut examiner

Parcourez ces quatre groupes. Pour chaque constat, citez le moment (ce qui a été dit ou fait, approximativement quand), dites pourquoi cela a eu de l'importance, et demandez « pourquoi » au-delà de l'instance jusqu'à atteindre une cause processuelle ou un principe, ou jusqu'à ce que la réponse sorte du contrôle du projet. Gardez observations et prescriptions séparées : une observation peut être juste tandis que la solution proposée est erronée.

1. Efficacité. Appels d'outils redondants ou répétés, logique écrite à la main qu'un script ou une compétence aurait dû porter, cycles de build ou de test supplémentaires, travail qui aurait pu être regroupé, sous-agents qui ont été manqués ou qui ont payé, retravail après compactage, travail en arrière-plan mort avec la session.
2. Collaboration. Questions posées trop tôt, trop tard ou pas du tout ; instructions permanentes non suivies ; exemples pris au pied de la lettre alors qu'une règle était visée ; verbosité ; si l'agent a dit quelle interprétation d'une demande ambiguë il a retenue ; si les questions bloquantes ont effectivement bloqué.
3. Correction et discipline. Affirmations faites sans preuve ; contraintes découvertes tardivement ; actions destructrices ou irréversibles sans confirmation ; conventions du projet négligées ; les questions « quel scénario demande cela » et « qu'est-ce qui aurait attrapé cela » sautées.
4. À reporter. Préférences et décisions qui valent la peine d'être sauvegardées comme mémoire ou documentation du projet ; propositions qui sont une compétence, un workflow, un hook, une règle permanente ou un élément du backlog ; outils qui auraient facilité la période ; étapes qui pourraient être automatisées la prochaine fois. Deux répétitions écrites à la main signalent un actif réutilisable manquant.

Ensuite, les deux parties qui rendent cette compétence personnelle :

• Coaching pour la personne. Comment la personne qui rédige les prompts aurait-elle pu être plus efficace ? Quelles de ses actions ont le plus aidé (nommez-les, pour qu'elles soient répétées) et lesquelles ont coûté (périmètre vague, une étiquette manquante sur un exemple, une décision retenue dont l'agent avait besoin, une revue sautée) ? Écrivez-le directement à la personne, comme le ferait un pair dans un groupe de supervision : spécifique, fondé sur des preuves, sans flatterie et sans adoucir.
• Modèles et effort. D'après les chiffres : le modèle et le niveau d'effort étaient-ils proportionnés au travail ? Où sont allés les tokens (boucle principale, sous-agents, workflows), et un modèle moins cher ou un effort plus faible auraient-ils suffi pour certaines parties ? Où un effort élevé a-t-il payé ?

Rapport

Écrivez le rapport dans le répertoire des rapports et montrez un court résumé dans la réponse. Le répertoire est docs/debriefs/ dans le dépôt actuel lorsque le dépôt a un répertoire docs/, sinon ~/.claude/debriefs/<slug-du-projet>/ ; l'utilisateur peut en nommer un autre. Nom du fichier AAAA-MM-JJ.md, avec un suffixe -2 si un fichier existe déjà.

Court et dense : le lecteur est la personne qui a vécu la session, donc le rapport rappelle plutôt qu'il ne raconte. La nuance réside dans la preuve et la cause, pas dans la prose qui les entoure. Utilisez ce modèle :

# Debrief <date> : <sujet de la période>

Couverture : <ce que le débriefing a pu voir ; compactage noté>. Débriefings antérieurs : <dates ou aucun>.

## En cinq lignes
- <ce que la période a accompli>
- <ce qui l'a fait fonctionner>
- <ce qui a coûté>
- <le coaching en une ligne>
- <combien de propositions, et celle qui n'est pas mineure>

## Chiffres
<un paragraphe du script : durée, tours, appels d'outils avec les principaux, tokens de sortie par modèle, sous-agents, compactages>

## Ce qui s'est bien passé
- **<étiquette de deux mots>.** <le moment> → <ce que cela a apporté>.

## Ce qui a coûté
- 🔴 / 🟡 / 🟢 **<étiquette>.** <le moment, une ligne>.
  Cause : <la cause processuelle après avoir demandé pourquoi>. <Corrigé, ou ce qui reste.>

## Coaching pour <la personne>
À garder : <les actions qui ont aidé, sous forme de liste en une ligne>.
1. **<habitude>.** <preuve> et <quoi faire à la place>, une ou deux phrases.

## Modèles et effort
<un paragraphe : proportionné ou non, et les chiffres qui le disent>

## Propositions
| # | Proposition | Destination | Effort | Décision |
|---|---|---|---|---|
Destinations : règle AGENTS.md ou CLAUDE.md, mémoire, compétence, workflow, hook, backlog, le guide partagé, un outil à adopter.

## Recommandations antérieures
| Provenance | Recommandation | Statut (suivie d'effet / récurrente / inconnue) |

Sévérité : 🔴 a coûté du travail réel ou risqué des dommages ; 🟡 a coûté du temps ou de l'attention ; 🟢 une petite habitude.

Règles

• Un rapport uniquement. Rien n'est écrit dans les fichiers d'instructions, la mémoire ou le backlog tant que l'utilisateur n'a pas approuvé une proposition ; ensuite, appliquez exactement celle-là.
• Chaque constat cite un moment. Si vous ne pouvez pas en pointer un, abandonnez le constat.
• N'enflammez pas : trois constats réels valent mieux que dix gonflés, et « cette période s'est bien passée » est un résultat valide.
• Le coaching est pour le bénéfice de la personne, il doit donc être franc ; il est aussi privé par défaut, donc gardez-le en dehors de tout ce que la personne n'a pas demandé à partager.
• Langage simple et actionnable : écrivez chaque élément de sorte qu'une personne ou un agent qui n'était pas dans la session puisse agir dessus. Nommez une pratique comme un comportement (ce que quelqu'un fait et ce que cela accomplit : « spécifiez le résultat, pas la solution »), jamais par un surnom inventé pendant la session (« la solution retenue », « les sceptiques », « à l'œil ») ; si l'abréviation aide à la reconnaissance, mettez-la après la forme complète entre parenthèses. Le test : un collègue pourrait-il copier la ligne dans son propre guide et la suivre ?
• Bref : une étiquette en gras, puis une ligne de preuve, puis la cause. Si un constat nécessite un paragraphe, c'est qu'il s'agit de deux constats ou qu'il n'est pas encore compris. Visez un écran par section.
• Leçons versus friction : une leçon est quelque chose que vous diriez à un autre agent sur un autre projet ; ce qui ne s'applique qu'à cette session est de la friction et va dans les constats, pas dans les propositions de règles permanentes.