2D0/claude-skills

blackbox

Présentation

Une boîte noire est l'enregistreur de vol d'un élément : un enregistrement de décision non résumé par unité de changement approuvée par le propriétaire — ce que le propriétaire a réellement dit (textuellement), ce que cela signifiait dans son contexte, ce que l'assistant a recommandé et construit, pourquoi, les preuves qui ont motivé chaque choix, et ce que l'assistant a fait de travers en cours de route — rattaché au contenu qu'il explique et lu uniquement à la demande. Elle existe pour qu'une future session audite l'origine d'une règle au lieu de la redébattre.

Deux choses qu'elle n'est pas :

• Pas une transcription. Sélectionner n'est pas résumer. L'entrée est écrite à partir de la piste de décision, pas du journal de discussion : les enseignements, analogies et détours qui ont aidé le propriétaire à comprendre mais n'ont changé aucune décision sont laissés de côté. Ce qui est conservé l'est en entier.
• Pas un journal sur le propriétaire. Elle enregistre ce qui a été dit et décidé, pas qui est le propriétaire. Les observations sur le style de travail appartiennent à la mémoire de l'assistant, jamais ici.

Cet élément a-t-il une boîte noire ?

• blackbox/README.md se trouve à côté de l'élément (ou à la racine du dépôt) → la convention s'applique. Lisez ce README ET l'entrée la plus récente avant d'écrire la vôtre — le schéma vient d'eux, jamais de votre esprit.
• Pas de marqueur, et le propriétaire demande d'en adopter un → amorcer : copiez blackbox/README.md du répertoire de cette compétence dans l'élément, sans rien changer sauf le nom de l'élément, puis enregistrez l'adoption elle-même comme première entrée.
• Pas de marqueur, et vous êtes sur le point de modifier un document de spécification / convention / conception pour la première fois de cette session → vérifiez la présence du marqueur. S'il est absent, proposez l'adoption une fois, en une phrase, puis poursuivez la tâche du propriétaire. L'adoption est la décision du propriétaire ; s'il refuse, notez-le dans la mémoire pour que le dépôt ne soit plus sollicité.

L'unité d'adoption est le répertoire contenant le marqueur — une compétence, un paquet, ou un dépôt entier. N'importe quel dépôt, n'importe quelle méthode de fusion.

Unité et calendrier

• Une entrée par unité approuvée par le propriétaire : une spécification confirmée, un PR fusionné, une convention révisée. Pas par commit, pas par tour de conversation. Une unité qui a produit plusieurs commits reçoit une entrée.
• Rédigée dans la session où les décisions ont eu lieu. L'échange brut ne vit que dans le contexte actuel ; une fois la session terminée, seuls les résumés survivent et les citations textuelles disparaissent. Si une unité est longue ou s'étend sur plusieurs sessions, enregistrez un brouillon tôt — Refs: en attente, les citations du propriétaire et l'index remplis — et finalisez (épinglez les blobs, complétez le corps) lors de l'approbation. Un brouillon vaut mieux qu'une mémoire reconstruite.

La recette (par unité approuvée par le propriétaire)

1. Effectuez la modification.
2. Épinglez les résultats par contenu. Pour chaque fichier modifié, git hash-object <chemin> sur l'arbre de travail. Les SHA de blob sont indexés par contenu — les mêmes octets donnent le même hash pour toujours, donc l'épingle survit au squash, au rebase et à toute réécriture d'historique, et elle existe avant tout commit.
3. Rédigez l'entrée blackbox/YYYY-MM-DD-<slug>.md dans la forme ci-dessous : un index qui pointe vers le corps, puis le corps brut.
4. Faites atterrir l'entrée avec la modification — même commit ou même PR, fusionné comme le dépôt fusionne normalement.

Vérifiez une épingle : git hash-object <chemin> et comparez. Récupérez un état épinglé : git log --find-object=<sha> ou l'API des blobs GitHub.

Règle de lecture : ne chargez jamais blackbox/ pendant le travail normal sur l'élément. Lisez-le uniquement pour des questions de provenance.

Forme de l'entrée

# YYYY-MM-DD — <titre>

Refs:           <chemin> @ blob <sha>            (une ligne par fichier modifié)
Decisions:      <décision> <poids> [→ <nouveau poids>, voir §…] · …
Reversals:      §… · §…   (ou : aucune)
Owner caught:   §… · …    (ou : aucune)
Declined:       §… · …    (ou : aucune)
Evidence:       <commande / nombre / lien> · …
Understanding:  §…        (ou : n/a)
---
<coprs brut, avec des titres § vers lesquels l'index pointe>

Les lignes d'index pointent vers le corps ; elles ne le remplacent jamais.

• Decisions — chaque décision que l'unité contient, avec le poids que l'assistant a attribué en demandant (🔴 doit décider maintenant · 🟡 décider, révisable · 🟢 prendre la recommandation). Si un poids a été modifié plus tard, dites-le et pointez vers pourquoi. Avec le temps, cette ligne est la façon dont le propriétaire audite sa propre délibération par rapport au poids que la décision méritait.
• Reversals — tout ce que l'assistant a affirmé et plus tard retiré ou corrigé : une affirmation erronée, une recommandation inversée par une mesure, une décision qu'il a prise sans demander. none est une valeur valide et doit être écrite explicitement.
• Owner caught — incohérences ou défauts que le propriétaire a repérés (un mauvais décompte, un élément manquant, un bug structurel). L'audit du propriétaire, pas seulement celui de l'assistant.
• Declined — options, valeurs par défaut de l'outil, ou recommandations externes délibérément non retenues, avec la raison dans le corps.
• Evidence — ce qui a réellement été consulté lors de la décision : la commande exécutée, les chiffres qu'elle a produits, la page ou le fichier affiché. Enregistrez la reproduction, pas l'image — un diagramme est régénéré à partir de sa commande ; une capture d'écran ne l'est pas.
• Understanding — lorsque le propriétaire a approuvé en disant ne pas comprendre pleinement, sa déclaration et ce qui doit être réexpliqué plus tard.

Langue

• Corps : anglais, indépendamment de la langue des documents du dépôt.
• Saisie du propriétaire : le texte original textuellement, puis une réécriture en anglais. Le texte original en premier, dans un bloc de citation >, exactement comme tapé — fautes de frappe, abréviations, ㅇ et tout. Puis la réécriture : complète en contenu, naturelle dans la forme, autonome (un lecteur sans autre contexte la comprend). Le texte original est la preuve — une faute de frappe qui a changé une décision ne peut être trouvée que là. La réécriture est la lecture de l'assistant à ce moment-là — si les deux divergent, l'entrée a déjà enregistré la faute.
• Réponses de l'assistant, justification et traitement interne : anglais, sous forme complète pour tout ce qui concerne une décision. > ㅇ suivi de Le propriétaire a approuvé l'option (a). est un enregistrement complet ; ne le gonflez pas.

Formes strictes

Règle	Pas ça
Saisie du propriétaire = citation textuelle et réécriture en anglais	Texte original seul (illisible sans contexte), réécriture seule (preuve perdue), ou un résumé d'une ligne
Index en haut, corps brut en dessous, lignes d'index pointant vers des titres §	Un index qui résume au lieu de pointer ; un corps sans index ; des sections remplies d'une ligne
Corps issu de la piste de décision	Enseignements, analogies ou détours qui n'ont changé aucune décision
Reversals: présent, même en tant que none	Une entrée qui ne liste que ce qui a bien fonctionné
Refs: = SHA de blob par fichier (git hash-object)	Un numéro de commit ou de PR comme ancrage — les réécritures d'historique les tuent
L'entrée atterrit dans le même commit ou PR que la modification	Un PR de suivi « plus tard »
Rédigée dans la session où les décisions ont eu lieu	Reconstruite la session suivante de mémoire
Schéma de l'entrée depuis le README et l'entrée la plus récente	Un format inventé

Signaux d'alarme

• Une entrée sans ligne Refs:, ou une ligne Refs: nommant un commit ou un PR au lieu de blobs
• Une saisie du propriétaire sans citation >, ou une citation sans réécriture après elle
• Absence de ligne Reversals:
• Des lignes d'index qui ressemblent à des résumés plutôt qu'à des pointeurs
• Un corps qui explique des concepts au lecteur au lieu d'enregistrer ce qui a été décidé
• Une modification fusionnée sans son entrée
• Une entrée rédigée lors de la session après les décisions qu'elle enregistre (mentionnez-le dans l'entrée si inévitable)

Provenance

blackbox/ contient l'enregistrement complet des décisions pour cet élément — saisies du propriétaire (textuelles + réécritures en anglais), raisonnement de l'assistant, preuves et revirements, épinglés par contenu par modification approuvée. Lisez-le uniquement lorsque vous enquêtez sur la raison d'être d'une règle ou ce que le propriétaire a initialement demandé. Ne le chargez jamais pendant une utilisation normale.