Communitygithub.com

T0mSIlver/skills

Supprime les métacommentaires auto-narratifs dans le texte de l'interface utilisateur, la documentation, les commentaires de code, les messages de commit et les descriptions de PR.

Qu'est-ce que skills ?

Cette compétence (skill) est un assistant éditorial conçu pour identifier et supprimer les métacommentaires superflus que les agents d'IA produisent systématiquement dans le texte. Son objectif est d'éliminer tout contenu qui décrit l'artefact dans lequel il se trouve, reformule ce que le lecteur voit déjà, ou narre le processus de création. Cela s'applique à toutes les surfaces d'écriture : copie d'interface utilisateur, documentation, commentaires de code, messages de commit et descriptions de pull request. La compétence propose un « test de suppression » simple : si la phrase ne perd rien à être supprimée mentalement, ou si elle pourrait être déplacée sans changement dans un autre projet, elle doit être coupée. Elle fournit aussi des listes détaillées de ce qu'il faut conserver (commentaires expliquant le « pourquoi », instructions formatées, textes alternatifs réels) et la procédure à suivre en combinaison avec l'outil `unslop`. Cette compétence est conçue pour être utilisée avec tout agent ou outil d'écriture IA (Claude Code, Cursor, Codex, etc.) et améliore la clarté, la concision et le professionnalisme du texte produit.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/T0mSIlver/skills/tree/HEAD/unnarrate

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Dénarrer

Compagnon de unslop. Unslop corrige la sonorité de la prose IA ; celui-ci supprime le texte qui ne devrait pas exister du tout : les métacommentaires — une écriture qui narre l'artefact à son propre public. Une barre de progression annonce déjà la progression ; « la progression est affichée pendant son exécution » à côté est un signifiant redondant supplémentaire. Les agents produisent cela constamment car ils narrent leur chaîne de pensée dans chaque surface qu'ils touchent.

Le test de suppression

Supprimez toute phrase, étiquette ou commentaire dont le seul contenu est :

  1. une description de l'artefact dans lequel il se trouve (« Cette section décrit… »),
  2. quelque chose que le lecteur peut déjà voir (une info-bulle reformulant l'étiquette, un commentaire reformulant la ligne suivante), ou
  3. le processus qui l'a produit (// Comme demandé, extrait dans un helper).

Deux vérifications tranchent les cas limites :

  • Supprimez-le mentalement. Si le lecteur ne perd rien, c'était une opération nulle — un texte qui semble faire quelque chose mais ne change rien.
  • Portabilité. Si la ligne pourrait apparaître inchangée dans un autre projet, une autre PR, ou au-dessus d'un code différent, elle ne dit rien sur celui-ci. Coupez-la.

Quoi couper, par surface

Copie UI

  • Copie décrivant un comportement que l'interface effectue déjà : « La progression est affichée lors de l'installation », « Un spinner apparaît lors du chargement », « La liste se met à jour automatiquement ». Le widget est le signifiant ; n'ajoutez pas un signifiant verbal.
  • Texte « Chargement… » à côté d'un spinner visible ; « Fichier téléchargé avec succès » → « Fichier téléchargé ».
  • Infobulles et textes d'aide reformulant l'étiquette : champ « Ville de naissance », info-bulle « Saisissez la ville de votre naissance ».
  • Narration positionnelle : « Cliquez sur le bouton ci-dessous pour soumettre », « Sélectionnez une option dans la liste déroulante ».
  • Copie d'intégration / marqueurs de coach qui inventorie chaque contrôle au lieu de pointer vers la seule action non évidente.
  • Doublons d'accessibilité : aria-label="Bouton Soumettre" sur un <button>, alt="Image d'un graphique" (les lecteurs d'écran annoncent déjà le rôle).

Documentation et README

  • « Ce document décrit… », « Dans ce guide, nous allons… », « Bienvenue dans la documentation de X ». Commencez par le contenu.
  • Sections d'aperçu qui ne font qu'annoncer les sections suivantes ; paragraphes de conclusion « En résumé » reformulant la page.
  • Docstrings reformulant la signature (get_user(id) — « Récupère l'utilisateur par id ») ; <summary>Obtient ou définit le X</summary>. PEP 257 interdit exactement cela.
  • « L'exemple suivant montre comment… » au-dessus d'un exemple ; prose reformulant le bloc de code adjacent.
  • Listes à puces de fonctionnalités et introductions de section qui seraient vraies pour n'importe quel projet.

Commentaires de code

  • Reformulation de la ligne suivante : // Importer React, // Retourner la valeur, // Boucler sur les éléments.
  • Bannières de section : // ===== HELPERS =====, // --- Étape 3 : Valider ---.
  • Narration de plan et de phase : // Phase 2 : refactoriser, // Utilisation du modèle Foo nouvellement créé.
  • Narration de journal des modifications : // Passé de useState à useReducer, // Supprimé l'ancien gestionnaire. L'historique Git contient cela.
  • Commentaires adressés au relecteur plutôt qu'au futur lecteur : // Remarque : j'ai conservé ce comportement intact.

Commits et PR

  • Listes à puces reformulant le diff fichier par fichier ; « Cette PR ajoute… » suivi du titre textuellement.
  • Sections de modèle remplies de reformulation ; « Plan de test : exécuté les tests » sans détails.
  • Narration d'effort : « Refactorisation complète », « Rétrocompatibilité soigneusement préservée ». Énoncez des faits qu'un relecteur peut vérifier plutôt.

Conserver — tout ce qui narre n'est pas une opération nulle

  • La narration en direct est un signifiant ; la narration statique est le révélateur. Un agent diffusant « Installation des dépendances… » pendant qu'il travaille est un retour d'information réel. Une copie décrivant que ce retour existe est l'anti-modèle.
  • Les commentaires « pourquoi » restent : justifications, invariants, avertissements sur un comportement non évident, liens vers des problèmes et incidents. La règle supprime la reformulation, pas les commentaires — adaptez-vous à la densité de commentaires du code environnant.
  • Les instructions apportant des informations que la surface ne peut pas afficher restent : formats (« AAAA-MM-JJ »), contraintes (« 8+ caractères »), effets secondaires (« cela envoie un e-mail à l'équipe »), avertissements d'irréversibilité.
  • Le vrai texte alternatif reste. Supprimez le préfixe « Image de… », conservez la description de ce que montre l'image.
  • Les TODO avec un lien de suivi restent ; le // TODO : améliorer ceci nu disparaît.

Application

  1. Parcourez les surfaces modifiées pour les modèles ci-dessus. Supprimez, ne réécrivez pas — la plupart des cas ne nécessitent aucun remplacement.
  2. Lorsque la suppression laisse un vrai vide, corrigez l'artefact (étiquette plus claire, contrôle explicite), pas la narration.
  3. Exécutez ensuite unslop sur ce qui subsiste.

reference/terminology.md nomme le phénomène par communauté (métadiscours, happy talk, commentaires évidents, opérations nulles) avec des sources, pour citer ou étendre la liste de contrôle.

Skills associés