morzecrew/agent-skills

Rédaction et Maintenance de RFC

Cette compétence rédige et maintient des RFC légères — des propositions de conception numérotées en Markdown qui vivent dans le dépôt à côté du code qu'elles décrivent. Une RFC capture une conception avant (ou pendant) sa réalisation : le problème, l'état actuel du code, les décisions verrouillées avec leur justification, et ce qui est délibérément hors de portée. La collection est suivie via un seul INDEX.md afin que l'ensemble de l'historique de conception soit visible en un coup d'œil dans un tableau.

Les RFC sont ici des documents de travail, pas de la bureaucratie : elles existent pour que les décisions survivent aux pertes de contexte, pour qu'une conception reprise soit « une seule petite PR, rien de plus », et pour que les alternatives rejetées ne soient pas rediscutées inutilement.

Utiliser cette compétence quand

• L'utilisateur demande d'écrire une RFC, un document de conception, une proposition de design, une spécification technique ou une proposition d'architecture
• L'utilisateur souhaite enregistrer ou verrouiller une décision de conception — avec les alternatives qu'elle a écartées, ou pourquoi une approche a été rejetée — avant de l'implémenter
• L'utilisateur demande de mettre à jour une RFC (changement de statut, notes d'exécution, marquage comme livrée ou rejetée)
• L'utilisateur demande de créer, indexer ou réorganiser un répertoire rfcs/ (ou rfc/)
• Une discussion sur une fonctionnalité importante doit être capturée dans un document durable

Ne pas utiliser cette compétence quand

• L'utilisateur souhaite de la documentation produit, un README ou des documents destinés aux utilisateurs (pas une proposition de conception)
• L'utilisateur veut un ADR dans un dépôt qui a déjà une convention ADR établie — suivre cette convention à la place
• Le changement est suffisamment trivial pour être porté par un message de commit ou une description de PR

Répertoire et index

Emplacement. Les RFC se trouvent dans un seul répertoire plat à la racine du dépôt : rfcs/ (par défaut recommandé) ou rfc/. Avant de créer quoi que ce soit, chercher un répertoire existant de l'un ou l'autre nom et le suivre. Si aucun n'existe, créer rfcs/.

Gitignore est le choix de l'utilisateur, pas le vôtre. Certains projets versionnent les RFC ; d'autres les placent dans .gitignore comme notes de travail locales. Ne jamais ajouter ni supprimer d'entrée .gitignore pour le répertoire des RFC sauf demande explicite. Si le répertoire est ignoré par git, l'en-tête de INDEX.md doit le mentionner (voir le modèle) pour que les lecteurs sachent pourquoi il n'est pas dans l'historique du dépôt.

INDEX.md est la source de vérité pour la collection. Il contient trois éléments :

1. Le prochain numéro libre, indiqué explicitement — les numéros entrent en collision lorsqu'ils sont attribués en parallèle, donc l'index nomme le suivant et chaque création de RFC le met à jour dans la même modification.
2. Le tableau d'index : | # | Titre | Statut | Une ligne |, une ligne par RFC, le numéro lié au fichier.
3. La légende des statuts.

Si le répertoire existe mais a un README.md dans ce rôle, le traiter comme l'index. Si on demande une configuration fraîche, utiliser INDEX.md — copier references/index-template.md.

Numérotation et noms de fichiers

• Les numéros sont sur 4 chiffres, remplis de zéros, croissants de manière monotone : 0001, 0002, …
• Pour allouer : lire le « prochain numéro libre » dans INDEX.md, vérifier par recoupement avec ls du répertoire (l'index peut être obsolète), et prendre le prochain entier non utilisé.
• Nom du fichier : NNNN-titre-en-kebab-case.md. Maintenir la cohérence entre le numéro dans le nom du fichier et le titre H1 # RFC NNNN — Titre — ils dérivent sinon, et les liens se cassent dans les deux sens.
• Ne jamais renuméroter des RFC existantes. Les numéros sont des identifiants, pas un ordre à réorganiser.

Statuts

• 📝 Brouillon — proposé, pas commencé (une RFC « conception verrouillée, conditionnée par la demande » est toujours Brouillon)
• 🚧 En cours — partiellement livré
• ✅ Terminé — entièrement livré
• ❌ Rejeté / retiré — conserver le fichier ; un rejet enregistré empêche de rediscuter

Le statut se trouve à deux endroits qui doivent être en accord : la ligne **Status:** dans l'en-tête de la RFC et la colonne Statut du tableau d'index. Mettre à jour les deux dans la même modification.

Anatomie d'une RFC

Lire references/rfc-template.md avant d'écrire une nouvelle RFC et partir de ce modèle. La structure :

Bloc d'en-tête (liste à puces directement sous le H1, avant toute section) :

• **Status:** — emoji + mot, éventuellement annoté (« prêt à exécuter — une PR », « conception verrouillée, non planifiée »)
• **Scope:** — un paragraphe dense : ce que cette RFC couvre et ce qu'elle ne couvre délibérément pas. C'est le paragraphe que quelqu'un lit pour décider de lire la suite.
• **Related:** — liens vers le code concerné (liens relatifs dans le dépôt), autres RFC, travaux antérieurs, références externes
• **Discussion:** (optionnel) — lien vers là où la conception a été ou est débattue (PR, issue, fil de discussion) ; un lecteur en désaccord s'y rend au lieu de fork le document
• **Origin:** (optionnel) — d'où la conception a été portée ou généralisée, le cas échéant

Sections numérotées. L'ensemble complet, pour une RFC substantielle :

1. Résumé — ce qui est livré, en quelques phrases
2. Motivation — le problème, avec des preuves issues du code lui-même
3. État actuel — ce qui existe aujourd'hui, vérifié en regardant le code, pas de mémoire
4. Objectifs / Non-objectifs — explicites dans les deux sens
5. Conception — le cœur ; sous-sections par flux de travail ou composant, avec de vraies signatures/schémas/blocs de code là où ils ancrent la conception. Là où un choix a été contesté, conserver l'alternative rejetée et pourquoi elle a perdu — une phrase pour les décisions mineures, une sous-section ### Alternatives considérées lorsque le choix a façonné la conception
6. Tests — comment la conception est vérifiée
7. Documentation — quelle documentation l'accompagne
8. Hors de portée — nommés et justifiés : chaque élément dit pourquoi il est exclu et ce qui changerait cela
9. Risques — modes d'échec honnêtes, y compris les risques de mauvaise lecture du document
10. Questions non résolues — ce qui doit être réglé avant que la conception soit considérée comme verrouillée, par opposition à ce que l'implémentation peut décider librement ; nommer une inconnue vaut mieux que la résoudre en silence en cours de réalisation
11. Décisions — un tableau numéroté des décisions verrouillées ; c'est ce qui rend la reprise bon marché et la rediscussion inutile. Là où une décision contraint le futur de manière non évidente, la ligne le dit — les conséquences d'une décision sont le contexte de la suivante
12. Phasage — ce qui arrive en premier, ce qui dépend de quoi

Adapter à l'importance de la RFC. Une petite RFC de verrouillage de conception n'a besoin que du bloc d'en-tête, de la section Conception, des Non-objectifs et du tableau des Décisions. Ne pas gonfler une RFC de deux pages avec douze sections ; ne pas réduire une proposition à l'échelle du système à trois sections. Maintenir la numérotation des sections contiguë pour le sous-ensemble utilisé.

Style d'écriture

• Appuyer chaque affirmation sur le code. « État actuel » et « Motivation » citent des fichiers, des faits au niveau des lignes et des nombres mesurés — les lier avec des chemins relatifs. Une RFC qui argumente de mémoire est une fiction avec des titres.
• Enregistrer les décisions avec leur pourquoi — et leur coût. Le tableau des décisions est le contrat ; le corps porte le raisonnement. Les alternatives rejetées reçoivent une phrase expliquant pourquoi elles ont perdu (une alternative enregistrée avec son compromis reste rejetée ; une enregistrée comme simplement « rejetée » sera reproposée). Une décision qui ferme une porte le dit plus tard dans sa ligne.
• À temps vaut mieux que poli. Une RFC approximative qui existe vaut mieux qu'une parfaite qui n'existe pas (règle RFD d'Oxide : « timely rather than polished »). Le texte d'un brouillon peut être approximatif ; le paragraphe de Scope et le tableau des décisions ne le peuvent peut-être pas.
• Être honnête sur les limites. Si un mécanisme est différé, conditionné ou connu comme incomplet, le dire dans la RFC plutôt que de laisser le lecteur le découvrir. Un langage qui échoue en position fermée (« refusé », « lève », « délibérément non planifié ») vaut mieux qu'une vague optimiste.
• Dense plutôt que long. Préférer un paragraphe porteur à trois paragraphes légers. La ligne d'une ligne de l'index en particulier : elle doit être suffisamment autonome pour qu'un lecteur puisse ignorer la RFC.

Flux de travail

La comptabilité — allocation de numéro, création de fichier à partir du modèle, mise à jour de la ligne d'index et du numéro libre, détection de dérive — est mécanique, et scripts/rfc_index.py le fait sans les collisions que produit l'allocation manuelle :

python3 scripts/rfc_index.py check          # index vs fichiers, H1 vs nom de fichier, statuts, prochain libre
python3 scripts/rfc_index.py next           # prochain numéro libre
python3 scripts/rfc_index.py new "Titre"    # allouer + instancier le modèle + ligne d'index + incrémenter
python3 scripts/rfc_index.py new "Titre" --number 42   # numéro réservé, ou recréation d'une RFC supprimée

(Chemin relatif au répertoire de cette compétence ; depuis la racine du dépôt, le script est dans skills/rfc-writer/scripts/rfc_index.py. Lecture seule sauf new ; ajouter --root DIR — avant ou après la sous-commande — si le dépôt n'est pas le répertoire courant.) La réflexion — ce que dit la conception, ce que prétend la ligne d'une ligne, quand un statut change — vous revient.

A — Créer une nouvelle RFC

1. Localiser le répertoire des RFC (rfcs/ ou rfc/) ; s'il n'y en a pas, exécuter d'abord le flux de travail D.
2. Allouer le prochain numéro et instancier le fichier : rfc_index.py new "Titre" — il génère le numéro, écrit le modèle, ajoute la ligne d'index et met à jour la revendication du prochain libre. Les étapes 3 et 4 restent les vôtres : il laisse le modèle non rempli et écrit un littéral TODO: résumé en une ligne dans l'index. Manuellement : lire le prochain numéro libre dans l'index et vérifier par recoupement avec ls — les numéros entrent en collision lorsqu'ils sont attribués en parallèle.
3. Remplir le fichier en suivant la structure de references/rfc-template.md, adaptée au poids de la conception. Enquêter sur le code réel avant d'écrire « État actuel » — c'est l'essentiel du travail.
4. Remplacer le texte provisoire de l'index par un résumé dense et autonome.

B — Mettre à jour une RFC existante

1. Lorsque le travail est partiellement ou totalement livré, mettre à jour la ligne **Status:** — et l'annoter avec ce qui a été livré et quand (« Livré le 2026-06-29 : … ; seul P5 reste »).
2. Si l'exécution a divergé de la conception, enregistrer la divergence dans la RFC (une note de statut ou un amendement dans la section pertinente) — ne pas réécrire l'historique en silence ; le journal des décisions reste en ajout seulement.
3. Refléter le statut (et, si la forme a changé, le résumé d'une ligne) dans le tableau d'index.
4. Les conceptions rejetées reçoivent ❌ et restent dans le répertoire.

C — Maintenir l'index

Exécuter rfc_index.py check — il signale tout fichier sans ligne d'index et vice versa, les incohérences H1-nom de fichier, les désaccords en-tête-tableau de statuts, les numéros en double, et un prochain numéro libre qui n'est pas libre. Corriger ce qu'il nomme (les corrections sont un jugement : quel statut est vrai, ce que le résumé d'une ligne devrait dire), puis réexécuter jusqu'à ce que tout soit vert. Signaler ce qui était désynchronisé.

D — Initialiser un répertoire de RFC

1. Créer rfcs/ (sauf si l'utilisateur veut rfc/ ou s'il en existe déjà un).
2. Créer INDEX.md à partir de references/index-template.md, en remplissant le nom du projet et en réglant le prochain numéro libre à 0001.
3. Ne pas toucher à .gitignore — mentionner que le versionnement ou l'ignorance du répertoire est le choix de l'utilisateur.

Références

• references/rfc-template.md — squelette de RFC avec des conseils par section ; lire avant d'écrire une nouvelle RFC
• references/index-template.md — squelette d'INDEX.md ; utiliser lors de l'initialisation d'un répertoire

Compétences associées

• altitude-docs — la documentation destinée aux utilisateurs qui est livrée après la conception ; la section Documentation de la RFC y pointe
• self-audit — révision contradictoire de la branche qui a exécuté une RFC, avant fusion
• keep-a-changelog — enregistre ce qui est livré ; la RFC enregistre pourquoi cela a été construit de cette façon