chrislacey89/compound

Que fait compound ?

Documentez un problème récemment résolu ou une fonctionnalité livrée pour capitaliser les connaissances de votre projet. Chaque solution documentée rend la planification et l'implémentation futures plus rapides — l'agent consulte docs/solutions/ lors de /research et /write-a-prd, donc les leçons apprises aujourd'hui évitent les erreurs demain.

Lorsque le travail a révélé des surprises de planification ou d'estimation, capturez-les également. Le calibrage de type McConnell ne se produit que si le travail réel alimente la modélisation future.

Position d'invocation

Il s'agit d'une compétence de pipeline primaire qui ferme la boucle de capitalisation. Elle s'exécute vers la fin du chemin de livraison par défaut, après que /pre-merge a créé la PR.

Par défaut — capturez la leçon dans la PR, avant la fusion. Lorsqu'une leçon durable est déjà connue au moment de la PR, exécutez /compound sur la branche de la PR ouverte afin que l'entrée docs/solutions/ accompagne la même PR que le code qui l'a enseignée — examinée avant la même fusion et fusionnée atomiquement avec elle. Cela place /compound entre /pre-merge et /closeout, et retourne via /pre-merge une fois :

… → /pre-merge → /compound (dans la PR, lorsqu'une leçon existe) → /pre-merge (réexécution : le commit compound est le delta post-tampon ; re-tamponne) → /closeout (fusion + démantèlement) → nettoyage

Le retour n'est pas une décoration. Commiter sur la branche déplace la tête au-delà du tampon que /pre-merge Phase 4 a écrit, et /pre-merge est le seul rédacteur du tampon — donc sans la réexécution, l'entrée est fusionnée avec le code et lue par personne, ce qui est exactement ce que le défaut dans la PR était censé éviter. La Phase 5 énonce la transition ; c'est pourquoi elle existe.

Secours — capturez après fusion. Certaines leçons n'émergent que pendant ou après la fusion : surprises d'intégration, résultats de QA, comportement observé une fois mis en production. Pour celles-ci, exécutez /compound après que /closeout a fusionné. C'est le chemin de secours, pas celui par défaut.

Dans les deux cas, /compound n'effectue jamais la fusion ni le démantèlement de l'arbre de travail — c'est le rôle de /closeout — et n'écrit jamais le tampon de révision, qui est exclusif à /pre-merge. Capturer dans la PR signifie commiter sur la branche de la PR ouverte et revenir pour la révision qui la couvre ; cela ne signifie pas fusionner.

Ne l'utilisez pas pour des modifications triviales ou pour des leçons qui appartiennent entièrement à un artefact de plus haute fidélité comme un test, une règle de linter ou un commentaire de code sans apprentissage durable au niveau du projet. Que ce soit dans la PR ou après fusion, la garde "Quand ne PAS utiliser" ci-dessous s'applique toujours — la plupart des PR n'apportent aucune leçon durable, et il n'y a pas d'emplacement fixe par PR docs/solutions/ à remplir.

Pourquoi cela existe

Sans cette étape, vous avez fait de l'ingénierie traditionnelle avec assistance IA. Les trois premières étapes du flux de travail (planifier, travailler, réviser) produisent une fonctionnalité. Cette quatrième étape produit un système qui construit les fonctionnalités mieux à chaque fois.

Quand l'utiliser

• Lorsque la PR d'une fonctionnalité est prête et a enseigné une leçon durable — capturez-la sur la PR avant la fusion (le chemin heureux)
• Après la mise en production, lorsqu'une leçon n'est devenue claire que pendant ou après la fusion (le chemin de secours post-fusion)
• Après avoir corrigé un bug délicat où la cause racine n'était pas évidente
• Après qu'un cycle de QA a révélé des problèmes qui auraient pu être détectés plus tôt
• Après avoir pris une décision architecturale avec des compromis significatifs
• Lorsque vous avez découvert un motif qui devrait être réutilisé

Quand ne PAS l'utiliser

• Pour des corrections triviales (corrections de fautes de frappe, modifications de configuration simples)
• Lorsque la solution est déjà bien documentée dans la documentation officielle des bibliothèques
• Lorsque la leçon est spécifique au projet mais que vous allez bientôt déprécier ce code
• Lorsque le travail était une exécution propre d'un plan pré-établi — pas de surprises, pas de refonte, pas de décisions non évidentes. Le corps de l'issue et la description de la PR portent déjà cet enregistrement ; une entrée docs/solutions/ sans leçon réutilisable habitue les futurs lecteurs à ignorer
• En cas de doute — ignorer ne coûte rien car l'issue et la PR persistent dans GitHub. Capturer une leçon de faible valeur coûte l'attention des futurs planificateurs à chaque fois qu'ils consultent docs/solutions/

Flux d'exécution

Phase 1 : Identifier ce qu'il faut capturer

Sur le chemin par défaut dans la PR, le travail en cours de révision est la branche de la PR ouverte, donc les commandes ci-dessous le lisent directement — un git log et un git diff de la branche par rapport à la base dans laquelle elle va fusionner, alors qu'elle n'est pas encore fusionnée. Sur le chemin de secours post-fusion, exécutez-les dans une session qui peut encore voir l'historique de la fonctionnalité fusionnée — une fois que /closeout a nettoyé la branche et tiré la base, ce diff est vide et vous devez lire le diff de la PR via gh pr diff <n> à la place. Dans les deux cas, examinez le travail récent.

Résolvez d'abord la base. Ne codez pas en dur main — ce dépôt lui-même utilise prod, et un nom n'est pas une ref : dans un workflow d'arbre de travail, personne ne consulte la branche de base, donc la branche locale est figée à l'instant du checkout tandis que origin/<base> avance. Demandez à sidecar.sh base-ref ; ne dérivez pas la base.

SC="<ce répertoire de compétence>/references/sidecar.sh"
BASE_REF="$(bash "$SC" base-ref)" || { echo "base-ref a échoué : je ne devine pas de base" >&2; exit 1; }
git log --oneline "$BASE_REF..HEAD"
git diff --stat "$BASE_REF...HEAD"

Examinez :

1. Git log — Quels commits ont été faits ? Qu'est-ce qui a changé ? Relativement à la base, pas -20 : un nombre fixe lit l'historique de la base elle-même comme "le travail en cours de révision" sur toute branche plus courte que lui. Le double point est correct ici — ce sont les commits sur cette branche et non sur la base. (Le git diff est à trois points pour la raison miroir : il diffère à partir de la base de fusion plutôt que de soustraire le travail côté base.) Sur le chemin de secours post-fusion, la branche a disparu, utilisez donc gh pr diff <n> comme ci-dessus.

2. Fil de l'issue — Quel était le problème original ? Qu'est-ce qui a été discuté ?

3. Le diff — Quels fichiers ont changé ? Quels motifs ont émergé ?

Demandez à l'utilisateur : "Quelle a été la chose la plus importante que vous avez apprise ou la partie la plus délicate de cette fonctionnalité ?" Leur réponse révèle souvent la leçon de la plus haute valeur à capturer.

Avant d'écrire, classez la leçon au bon niveau :

• Événement — un incident ponctuel ou une défaillance visible
• Motif — quelque chose qui s'est produit de manière répétée à travers les fonctionnalités, les bugs ou les transferts
• Structure — une condition récurrente dans la base de code, le flux de travail, les incitations ou le processus de décision qui continue de produire le motif

Préférez capturer le niveau le plus élevé que vous pouvez soutenir avec des preuves. Si la leçon est structurelle, nommez la boucle de rétroaction, la rétroaction manquante ou l'effet retardé qui a rendu le résultat probable.

Avant de procéder, répondez à quatre questions :

1. Est-ce vraiment nouveau ? Consultez la documentation officielle des bibliothèques et les magasins que la recherche de chevauchement de la Phase 4 couvre. Si la leçon est déjà bien documentée ailleurs, ignorez-la ou liez-la à la source existante.
2. Sera-t-elle encore exacte dans 3 mois ? Si la leçon est étroitement liée à une version de dépendance ou à un contournement temporaire, notez-le — cela affecte la classification de volatilité ci-dessous.
3. Cette leçon pourrait-elle être capturée plus près de la source ? Un invariant comportemental est mieux dans un test. Une convention est mieux dans une règle de linter. Une explication "pourquoi" est mieux dans un commentaire de code colocalisé avec la décision — limité au pourquoi actuel, la raison pour laquelle un lecteur doit comprendre le code tel qu'il se présente maintenant. L'incident qui l'a découverte appartient au message de commit et au corps de la PR, là où un lecteur reconstituant l'historique cherche déjà ; /execute Étape 3 énonce ce routage au moment où le commentaire est écrit, et cette question est le contrôle rétrospectif. Si la leçon peut être capturée dans un artefact de plus haute fidélité, faites cela plutôt que d'écrire de la prose. Il s'agit de porter la leçon — la vérification de regroupement de la Phase 4 pose une question différente, à savoir si un mécanisme devrait attraper la prochaine instance, et une récurrence peut en nécessiter un même si la leçon elle-même nécessitait de la prose.
4. Le processus a-t-il été corrigé ? (Uniquement pour les corrections de bugs.) La correction était-elle une correction (a supprimé le défaut) ou un contournement (a supprimé la défaillance) ? Des motifs structurellement similaires ailleurs dans la base de code ont-ils été trouvés et traités ? Quel changement de processus empêcherait cette classe de défaut de réintégrer la base de code — un test plus fort, une règle de linter, une assertion, un élément de checklist de planification ou une issue déposée dans chrislacey89/skills (voir Dépôt contre le pack ci-dessous) ? Si la réponse est "rien", le mécanisme qui a produit ce défaut est toujours actif.

Dépôt contre le pack — le cinquième mécanisme

Cette sous-section n'est pas limitée aux corrections de bugs. La Q4 ci-dessus l'est (son titre le dit), mais la Q4 et la règle de promotion en mécanisme de la Phase 4 citent toutes deux les règles ci-dessous, et la Phase 4 n'est pas limitée aux corrections de bugs. L'incident pour lequel ce mécanisme existe était un compound de fonctionnalité. Une procédure accessible uniquement depuis le chemin que son propre incident n'a pas emprunté est le défaut que l'on corrige, un niveau plus bas — donc les règles sont déclarées ici, une fois, et les deux phases les désignent.

Le cinquième nom est limité par la propriété, pas par la difficulté. Les quatre premiers sont des artefacts de cette base de code ; le cinquième existe parce que certains changements préventifs ne le sont pas — ce sont des changements dans la prose d'une compétence, sa porte, sa transmission ou son test de contrat dans chrislacey89/skills, ce qu'aucun artefact en aval ne peut porter du tout. C'est cela, et seulement cela, qui qualifie le cinquième nom. Il ne se qualifie pas parce que les quatre premiers sont difficiles, coûteux ou peu clairs ici : c'est la sortie de conformité que chrislacey89/skills#257 a délibérément laissée fermée, et "je n'ai pas pu en construire un" résout toujours comme il l'a toujours fait — en nommant dans l'entrée lequel des quatre s'est approché le plus et ce qui l'a bloqué.

Garde de propriété de dépôt (DO-CONFIRM — vérifiez avant d'écrire quoi que ce soit en sortie)

Déposer déplace les mots du dépôt dans lequel vous vous trouvez vers un dépôt public. C'est un acte différent de tout autre mécanisme de la liste — un test, une règle de linter, une assertion et un élément de checklist restent tous sur place. Donc, avant de composer un corps, confirmez que le propriétaire du dépôt actuel est l'un de ceux que vous êtes autorisé à déposer depuis :

git remote get-url origin | sed -E 's#(git@[^:]+:|https://[^/]+/)([^/]+)/.*#\2#'

Comparez-le à la liste blanche ci-dessous. La liste blanche est la porte entière — un propriétaire qui n'y figure pas n'est pas autorisé, y compris un propriétaire que vous ne reconnaissez pas. N'inversez pas cela en "bloquez les propriétaires que je sais être liés au travail" : une organisation cliente intégrée la semaine dernière n'est sur la liste de personne, donc une liste noire admet exactement le dépôt avec la posture de confidentialité la moins connue. Échouez en mode fermé sur l'inconnu.

chrislacey89

Les marqueurs autour de ce cadre sont porteurs : cette sous-section contient plusieurs blocs encadrés, donc "la liste est le bloc de code ci-dessous" est ambigu pour quiconque lit mécaniquement — un lecteur qui devine mal extrait de la prose et chaque propriétaire échoue alors à la vérification. Faites correspondre les marqueurs, pas la position.

Ajoutez un propriétaire à cette liste uniquement comme une modification délibérée et révisée — une ligne, hors ligne, fouillable. Un dépôt public auquel vous contribuez se qualifie une fois que vous le nommez ; il ne se qualifie pas simplement pour être public. La visibilité est une propriété distante mutable, un fork public peut faire face à un parent privé, et — la raison pour laquelle cela compte ici — ce qui est déposé est un récit sur le travail, pas le code du dépôt. Une source publique et un engagement confidentiel autour d'elle est une combinaison ordinaire, et "nous avons rencontré cela en construisant X pour Y" fuit la relation même lorsque chaque ligne est lisible mondialement.

Lorsque le propriétaire n'est pas sur la liste blanche, le cinquième nom est indisponible. Revenez au comportement qui a précédé ce mécanisme : enregistrez la prescription dans le créneau Prévention → Niveau processus de l'entrée, recommandez /improve-pipeline, et laissez un humain la transporter. La leçon n'est pas perdue ; elle ne voyage simplement pas automatiquement.

Composition et dépôt

Lorsque la garde de propriété et la porte de dépôt passent toutes deux, le dépôt est le mécanisme, et /compound le dépose — la prescription atteignant ce dépôt est l'artefact, pas une phrase recommandant à quelqu'un de la transporter là-bas. Vérifiez d'abord les chevauchements et commentez sur l'issue existante plutôt que d'en déposer une nouvelle ; un nouveau canal sortant dans un backlog n'en vaut la peine que s'il ne se remplit pas de redites.

gh issue list -R chrislacey89/skills --state all --search "<domaine du pipeline> <mots-clés du mode de défaillance>"
gh issue create -R chrislacey89/skills --title "[improve-pipeline] <domaine du pipeline> — <prescription>" --body-file <fichier>

--title et --body* sont obligatoires, pas stylistiques : gh issue create sans l'un ni l'autre échoue sous n'importe quel exécuteur non interactif, ce qui est tous les chemins AFK que ce mécanisme est censé survivre.

Rédigez le corps anonymisé et traitez cela comme faisant partie du contrat plutôt que comme de bonnes manières. La porte ci-dessus décide si vous pouvez déposer ; celle-ci décide ce qui traverse. Décrivez la forme de l'incident, pas son sujet :

• Nommez le fichier du pack que le changement cible, l'étape du pipeline qui l'a manqué, et ce qu'elle aurait dû faire à la place.
• Ne nommez pas le dépôt en aval, son propriétaire, son client, ses chemins, ses identifiants, ni ses numéros d'issue et de PR. Caractérisez-le — "un dépôt TypeScript web/analyse de page en aval" — comme chrislacey89/skills#266 l'a fait, ce qui est l'exemple travaillé : il ouvre Triggering repo: anonymisé et enregistre que la source a été délibérément dépouillée des identifiants.
• Ne citez pas le chemin de cette entrée comme preuve. Un chemin docs/solutions/… est un nom de fichier d'un dépôt auquel le lecteur peut ne pas avoir accès, donc il ne prouve rien pour lui et identifie le travail pour tous les autres. Transportez plutôt le raisonnement ; l'entrée reste à la maison.

Le fichier du pack et la forme de la défaillance sont ce qui rend une proposition actionnable ici. Tout ce que la règle d'anonymisation retire est un détail qui n'était jamais lisible que dans le dépôt d'où il venait.

Restez court. Ceci est une ébauche de proposition, pas une proposition travaillée — /improve-pipeline est ce qui en développe une, et la recommandation /improve-pipeline plus loin dans cette phase tient toujours : recommandez-la, ne l'invoquez pas. Citez le numéro d'issue dans l'entrée. Un dépôt non cité est de la prose à nouveau : l'entrée nomme #N, ou le cinquième nom n'a pas été utilisé.