lesson-learned

Vue d’ensemble de la skill lesson-learned

La skill lesson-learned transforme l’activité Git récente en enseignements concrets d’ingénierie logicielle. Au lieu de donner des conseils abstraits, elle inspecte de vrais diffs, l’historique des commits et les fichiers modifiés, puis relie ce qui s’est passé à des principes nommés comme SRP, DRY, KISS, YAGNI, ainsi qu’aux anti-patterns associés. lesson-learned est donc particulièrement utile pour les développeurs qui ont déjà modifié du code et veulent répondre à ces questions : qu’est-ce que ce travail nous a appris, quel compromis avons-nous fait, et que faut-il reproduire — ou éviter — la prochaine fois ?

À qui s’adresse la skill lesson-learned

Les profils pour lesquels elle convient le mieux sont :

• les développeurs qui terminent une feature, un refactoring, un correctif ou un nettoyage
• les reviewers qui veulent un résumé orienté apprentissage après une PR
• les leads qui souhaitent instaurer des habitudes légères de réflexion d’ingénierie
• les agents qui doivent expliquer le principe derrière des changements de code récents

Si vous cherchez une analyse réflexive du design appuyée sur le véritable historique du dépôt, la lesson-learned skill est plus pertinente qu’un prompt générique du type « review ce code ».

Ce que fait réellement cette skill

Son rôle principal n’est pas la code review au sens habituel de validation ou rejet. lesson-learned regarde le travail déjà fait — ou en cours — et en extrait 1 à 3 enseignements étayés par le diff. Les bonnes sorties incluent généralement :

• le nom du principe
• la manière dont le changement l’illustre
• pourquoi c’est important
• une recommandation pour la suite

Ce cadrage la rend particulièrement utile pour les rétrospectives, le mentorat et les notes d’apprentissage autour des PR.

Ce qui distingue lesson-learned d’un prompt générique

Deux points font la différence :

1. Elle est pilotée par l’historique Git, donc elle analyse de vrais changements plutôt que des extraits hypothétiques.
2. Elle nécessite un catalogue de principes, en particulier references/se-principles.md, qui donne au modèle le vocabulaire nécessaire pour nommer les patterns de façon cohérente.

Cette combinaison aide la skill à produire des enseignements qui semblent réellement tirés du code, et non copiés depuis un manuel de génie logiciel.

Quand ne pas choisir lesson-learned

Évitez lesson-learned si votre objectif réel est plutôt :

• la détection ligne par ligne de bugs avant merge
• un audit de sécurité
• un retour limité au style ou au lint
• de la planification d’architecture sans changement de code à analyser
• la revue d’un gros codebase sans périmètre clair

Dans ces cas-là, une skill de code review, de sécurité ou de design sera généralement un meilleur premier choix.

Comment utiliser la skill lesson-learned

Contexte d’installation de lesson-learned

Le dépôt ne publie pas de commande d’installation dédiée dans skills/lesson-learned/SKILL.md. L’installation dépend donc de la manière dont votre environnement charge les skills depuis softaworks/agent-toolkit. Si votre setup permet d’ajouter une skill depuis ce dépôt, le schéma le plus courant est :

npx skills add softaworks/agent-toolkit --skill lesson-learned

Si votre agent charge les skills directement depuis le repo, utilisez le chemin suivant :

skills/lesson-learned

Dans les deux cas, considérez SKILL.md comme la spécification du comportement à l’exécution, pas simplement comme un README.

Fichiers à lire avant la première utilisation

Pour démarrer vite et limiter les suppositions, lisez les fichiers dans cet ordre :

1. skills/lesson-learned/SKILL.md
2. skills/lesson-learned/references/se-principles.md
3. skills/lesson-learned/references/anti-patterns.md
4. skills/lesson-learned/README.md

Le point d’adoption le plus important est facile à rater : la skill précise explicitement qu’il ne faut pas continuer avant d’avoir chargé se-principles.md.

Les entrées nécessaires à la skill lesson-learned

L’usage de lesson-learned fonctionne le mieux quand le modèle peut accéder à :

• un dépôt avec un historique Git
• le nom de la branche courante ou une cible de comparaison nommée comme main
• une plage de commits, un SHA, un diff de branche ou un diff du working tree
• suffisamment de contexte fichier pour inspecter les fichiers les plus modifiés

Sans contexte Git, la sortie devient très vite générique.

Choisir d’abord le bon périmètre d’analyse

Cette skill n’est bonne que si le périmètre que vous lui donnez l’est aussi. Le dépôt définit des valeurs par défaut pratiques :

• branche de feature : comparer le travail de la branche à main
• branche main : analyser les 5 derniers commits
• commit précis : inspecter un SHA
• changements en cours : inspecter les diffs staged et unstaged

Un bon lesson-learned guide commence par imposer ce choix très tôt. Si le périmètre reste flou, le résultat mélange généralement des enseignements sans rapport entre eux.

Commandes Git utiles pour mieux utiliser lesson-learned

Le workflow de la skill s’appuie lui-même sur des vues Git courantes, comme :

• git log main..HEAD --oneline
• git diff main...HEAD
• git log --oneline -5
• git diff HEAD~5..HEAD
• git show <sha>
• git diff
• git diff --cached

Vous n’avez pas besoin de toutes les commandes à chaque fois. Choisissez simplement celle qui correspond à l’histoire que vous voulez faire expliquer par la skill.

Transformer une demande vague en prompt solide

Prompt faible :

« Réfléchis à mon travail récent. »

Prompt plus solide :

« Use lesson-learned on my feature branch versus main. Read references/se-principles.md first. Focus on the 3 files with the largest behavioral changes. Give me 2 lessons grounded in the diff, each with the principle name, code evidence, trade-off, and one thing I should repeat in future PRs. »

Pourquoi cela fonctionne :

• le périmètre est défini
• le fichier de référence dont la skill dépend est nommé
• la surface d’analyse est limitée
• le format de sortie est précisé

Modèle de prompt pour lesson-learned en Code Review

lesson-learned for Code Review fonctionne mieux comme couche de recul ajoutée après une review classique, pas comme son remplaçant. Un prompt pratique est :

« Run lesson-learned on this PR branch against main. Summarize the engineering lesson behind the changes, not just defects. Highlight 1 positive principle demonstrated, 1 anti-pattern risk if relevant, and cite the changed files that support each point. »

C’est utile quand vous voulez un commentaire de review qui fasse apprendre quelque chose, et pas seulement bloquer.

Format de sortie conseillé à demander

Demandez une structure compacte du type :

• Lesson
• Principle
• Evidence from changes
• Why it matters
• Next step

Cela correspond à l’intention du dépôt et réduit le remplissage générique.

Comment gérer les gros diffs

Pour les grosses PR, ne demandez pas à la skill d’« analyser tout ». À la place :

• identifiez les fichiers les plus modifiés
• regroupez les changements par thème
• ignorez les modifications mécaniques évidentes
• demandez seulement 1 à 3 enseignements

La skill excelle pour extraire des patterns, pas pour cataloguer exhaustivement chaque modification de fichier.

Workflow courant qui fait gagner du temps

Un workflow fiable ressemble à ceci :

1. charger se-principles.md
2. choisir le périmètre
3. inspecter le log Git et le diff
4. lire les fichiers les plus modifiés
5. charger éventuellement anti-patterns.md
6. générer 1 à 3 enseignements avec preuves à l’appui
7. affiner si le résultat est trop large ou trop moralisateur

Cet enchaînement compte, car le catalogue de principes donne à l’analyse un vocabulaire plus solide.

FAQ sur la skill lesson-learned

Est-ce que lesson-learned convient aux débutants ?

Oui, à condition que le débutant ait de vrais changements à analyser. La skill explique les principes à travers un travail qu’il vient réellement de faire, ce qui est souvent plus facile à assimiler qu’une lecture théorique d’abord. Elle est moins utile pour quelqu’un qui n’a pas accès au repo ou pas de diff récent.

Est-ce que lesson-learned, c’est la même chose qu’une code review ?

Non. lesson-learned est rétrospective et orientée principes. La code review est généralement orientée correction, risque et maintenabilité. Il existe un recouvrement, mais l’objectif de sortie n’est pas le même.

La skill lesson-learned a-t-elle besoin d’un accès Git ?

Pour de bons résultats, oui. Le dépôt est conçu autour de l’historique Git et des diffs. Si vous collez uniquement un extrait de code, le modèle peut encore commenter des principes, mais il n’utilise alors plus la skill dans son mode le plus fort.

Qu’est-ce qui rend lesson-learned meilleure qu’un prompt ordinaire ?

Son avantage, c’est la structure : choix explicite du périmètre, références de principes obligatoires et workflow qui rattache les enseignements à des signaux concrets dans le code. Les prompts ordinaires basculent souvent trop vite vers des « best practices » génériques.

Puis-je utiliser lesson-learned sur des changements non commités ?

Oui. La skill prend en charge les changements en cours via git diff et git diff --cached. C’est utile avant le commit, quand vous voulez comprendre l’enseignement ou le compromis contenu dans ce que vous êtes sur le point de livrer.

Dans quels cas lesson-learned est-elle mal adaptée ?

Mieux vaut l’éviter quand :

• il n’y a pas de changements récents significatifs
• le diff est surtout composé de code généré ou de bruit de formatting
• vous avez davantage besoin d’un triage de défauts que d’un travail de réflexion
• la branche mélange de nombreuses tâches sans lien

Dans ces cas, réduisez le périmètre ou utilisez d’abord une autre skill.

Comment améliorer la skill lesson-learned

Donner à lesson-learned une histoire plus resserrée

Le principal levier de qualité, c’est le cadrage. « Mon dernier mois de travail » est trop large. « Ce refactoring qui sépare les appels API du rendu UI » est bien meilleur. Un périmètre plus étroit produit des enseignements plus nets, avec des principes plus précis et de meilleures preuves.

Charger la référence de principes à chaque fois

Le dépôt est inhabituellement explicite sur ce point : references/se-principles.md doit être chargé avant l’analyse. Si vous l’ignorez, le modèle pourra encore produire des observations, mais il aura plus de mal à nommer les patterns de façon cohérente ou à les relier à des principes reconnus.

Utiliser les anti-patterns pour équilibrer, pas pour noircir le tableau

references/anti-patterns.md est surtout utile quand le diff contient des signaux de risque comme des modifications dispersées, une sur-abstraction ou des modules « god » qui grossissent. Demandez une formulation mesurée pour que le résultat reste utile au lieu de paraître punitif.

Demander des preuves reliées aux fichiers modifiés

Un mode d’échec fréquent consiste à produire des conseils de haut niveau sans démonstration. Pour améliorer la sortie de lesson-learned, demandez :

• les fichiers modifiés concernés
• le changement structurel observé
• le compromis que cela implique
• pourquoi cela correspond à un principe précis

C’est la preuve qui sépare un véritable enseignement d’un commentaire générique.

Limiter le nombre d’enseignements

Plus il y a d’enseignements, plus ils ont tendance à s’affaiblir. Demandez seulement 1 à 3 points clés. Cela force la priorisation et rend la sortie plus crédible et plus facile à réutiliser dans des notes de PR, des rétrospectives ou du coaching.

Indiquer à la skill le type d’enseignement attendu

Vous pouvez orienter l’analyse en ajoutant un angle :

• enseignement de maintenabilité
• enseignement de refactoring
• enseignement de bug fix
• enseignement de compromis de design
• enseignement de process d’équipe lié aux changements de code

Cela améliore la pertinence sans aller contre le workflow prévu par la skill.

Corriger un premier jet trop générique avec une seconde passe

Si le premier résultat reste vague, ne relancez pas immédiatement depuis zéro. Demandez plutôt :

• « Tie each lesson to a specific file or diff hunk. »
• « Replace general advice with what this branch actually demonstrates. »
• « Name the principle only if the code evidence clearly supports it. »
• « Drop any lesson that is not visible in the diff. »

En général, cela améliore la sortie plus vite qu’un nouveau prompt trop large.

Repérer ces modes d’échec fréquents de lesson-learned

Les sorties faibles ressemblent souvent à ceci :

• des principes nommés sans preuve dans le code
• trop d’enseignements tirés d’un seul diff
• une confusion entre défauts de code review et enseignements utiles
• un ton moralisateur au lieu d’une lecture pratique des compromis
• la tentative de résumer des changements sans rapport comme une seule leçon

Les identifier tôt rend l’itération beaucoup plus simple.

Meilleure voie d’amélioration pour un usage récurrent en équipe

Si une équipe prévoit d’utiliser lesson-learned régulièrement, standardisez un template de prompt avec :

• une règle de périmètre
• une cible de comparaison
• un nombre maximal d’enseignements
• un format de preuve obligatoire
• une vérification optionnelle des anti-patterns

Cela réduit les écarts d’une utilisation à l’autre et rend la lesson-learned skill nettement plus fiable au fil des PR et des rétrospectives.