Ephasme/refine-document

Affiner un document

Prenez un document et produisez une version qu'un lecteur sans historique du projet peut utiliser : sans héritage, factuel, concis, organisé et adapté au lecteur déclaré.

Quatre passes, ordre fixe, puis une porte de vérification. Tout ce qui est supprimé est écrit dans un fichier d'enregistrement, afin qu'une erreur soit récupérable.

Invocation

refine-document <chemin> [--target=agent|humain] [--no-record]

Drapeau	Défaut	Effet
--target	agent	Lecteur pour lequel la dernière passe optimise. Change le document, pas seulement le ton — voir Passe 4.
--no-record	désactivé	Ignorer le fichier d'enregistrement. Les suppressions deviennent irrécupérables sauf par le contrôle de version.

Avant de toucher au fichier :

1. Confirmez que la demande nomme ce document. Cette opération réécrit le fichier de l'utilisateur sur place.
2. Confirmez que le fichier est suivi et propre dans le contrôle de version. Sinon, dites-le et obtenez un feu vert explicite — sous --no-record, c'est la seule voie de récupération restante.
3. Indiquez la cible avec laquelle vous exécutez dans votre premier message, y compris lorsqu'il s'agit de la valeur par défaut. Un silence par défaut fait qu'un document est façonné pour le mauvais lecteur.
4. Plusieurs documents : exécutez cette procédure une fois par document, un sous-agent chacun lorsque les sous-agents sont disponibles, en passant la même cible et les mêmes drapeaux à chacun. Un sous-agent possède exactement un fichier.

Sorties

Sortie	Chemin	Contenu
Document affiné	le chemin d'origine, sur place	état actuel uniquement, façonné pour la cible
Enregistrement	{nom}.changelog.md, même répertoire	tout ce qui a été supprimé, textuellement, localisé — ajouté à travers les exécutions
Rapport	votre réponse	voir Rapport

Ordre des passes

Exécutez les passes dans cet ordre, comme quatre lectures séparées du document. Chacune réduit l'entrée pour la suivante, et dans le désordre elles s'annulent mutuellement — compresser une prose que la passe 1 allait supprimer gaspille le travail, et organiser avant de compresser organise du remplissage.

1. Supprimer l'héritage — supprimez tout ce qui n'a de sens que comme référence au passé.
2. Factuel — chaque affirmation survivante est vérifiée, citée ou marquée.
3. Concis — un fait, un endroit, la forme la plus courte qui conserve le fait.
4. Organiser — critique en premier, puis la forme de la cible.

Passe 1 — supprimer l'héritage

SOUS-COMPÉTENCE REQUISE : utilisez strip-legacy-content pour cette passe. Elle possède la taxonomie de l'héritage, la règle de supprimer sans réécrire, et le format {nom}.changelog.md que cette compétence écrit également. Mappez --no-record à son --no-changelog.

Lorsque cette compétence n'est pas disponible, supprimez : les récits d'historique et d'évolution, les dossiers de décision et ADR, les avis de dépréciation, les guides de migration et de mise à niveau, les journaux de modifications et notes de version intégrés, les sections de rétrocompatibilité, les alternatives rejetées, les commentaires datés, les sections obsolètes. Supprimez les passages ; ne réécrivez pas la prose survivante — les passes 2 à 4 le feront.

La règle de la fonctionnalité dépréciée. Une fonctionnalité marquée comme dépréciée n'est pas automatiquement de l'héritage. Appliquez ce test, et enregistrez la branche que vous avez prise :

La fonctionnalité a-t-elle une utilisation qui n'est pas "soutenir l'ancien système" ?

• Non — elle n'existe que pour la rétrocompatibilité. Supprimez la fonctionnalité et son avis.
• Oui — c'est un comportement actuel. Conservez-la, supprimez le calendrier de suppression et le cadrage "depuis v1", et signalez-la dans l'enregistrement.

Passe 2 — factuel

Chaque affirmation que le document contient est une revendication, y compris celles qu'il a héritées. Classez chacune et prenez l'action correspondante. Il n'y a pas de cinquième option.

Classe	Signal	Action
Vérifiable, artefact accessible	comportement, drapeaux, valeurs par défaut, chemins, commandes, clés de configuration, et vous pouvez lire le code, la configuration ou le --help	Vérifiez-la. Vrai : conservez. Faux : corrigez-la.
Vérifiable, artefact inaccessible	les mêmes affirmations, sans dépôt, sans binaire et sans documentation à vérifier	Conservez l'affirmation exactement comme la source l'énonce, non marquée, et listez-la dans le rapport comme non vérifiée.
Sourceable en externe	normes, comportement de protocole, comportement de produit tiers, support de version	Citez la source primaire en ligne avec sa date ou sa version. Aucune source acceptable : supprimez l'affirmation.
Comparatif ou promotionnel	"10 fois plus rapide", "meilleur de sa catégorie", "éclatant", "élégant", "la plupart des ingénieurs sont d'accord", et toute comparaison dont l'autre terme ne fait pas partie du système actuel ("plus léger que Kafka")	Supprimez-la, à moins qu'une mesure citable n'existe — alors indiquez la mesure et sa source. Conservez le fait survivant : "met en file d'attente les tâches avec Redis Streams".
Non vérifiable et dangereux	une affirmation non vérifiée sur laquelle un lecteur pourrait agir de manière irrécupérable : perte de données, dépenses, identifiants, une commande destructive, une limite de sécurité	Conservez-la, marquez-la [non vérifié] dans le document, et listez-la dans le rapport.

Le marqueur est pour les dangers, pas pour la provenance. Un document sur un artefact que vous ne pouvez pas atteindre est principalement composé d'affirmations non vérifiées, et marquer chacune d'elles apprend au lecteur à ignorer le marqueur. La provenance non vérifiée appartient au rapport et à l'enregistrement ; [non vérifié] dans le document est réservé aux affirmations dont l'échec ne peut pas être annulé par le lecteur. Si plus d'une poignée de marqueurs survivent dans le document, vous avez classé la provenance comme un danger — reclassifiez.

N'inventez jamais un fait que le document source n'avait pas. Ni un emplacement de configuration, ni une valeur par défaut, ni un format de fichier, ni un prérequis — pas même un qui est presque certainement vrai. Un fait inféré énoncé platement est indiscernable d'un fait vérifié, et cette passe est tout ce qui se dresse entre le lecteur et une réponse erronée confiante. Si la source est silencieuse, le document affiné est silencieux.

N'adoucissez jamais une affirmation non sourcée en une version plus vague. "Environ 10 fois plus rapide" réécrit en "très rapide" est la même opinion avec moins de précision. Citez-la ou supprimez-la.

Ne supprimez jamais une instruction opérationnelle par manque de source. Marquer est mieux que supprimer : une instruction marquée peut être vérifiée par quelqu'un qui sait, une instruction supprimée est perdue.

Pour un document dont les affirmations sont principalement externes, exécutez cite-or-refuse pour le sourçage et fact-check-document pour un audit complet des affirmations avant de continuer.

Passe 3 — concis

Un fait, un endroit. Pour chaque fait, choisissez la section unique où un lecteur qui le cherche arrivera en premier. Énoncez-le là, en entier. Partout ailleurs, soit supprimez la reformulation, soit remplacez-la par un pointeur nommant cette section exactement.

Supprimez directement :

• Ouvertures de remplissage : "Il est à noter que", "Simplement", "En gros", "Comme vous pouvez le voir".
• Instructions pour faire ce que le lecteur fait déjà : "Pour installer, exécutez la commande d'installation".
• Titres de section reformulés comme premières phrases.
• Réserves défensives qui ne changent aucune action.
• Exemples qui démontrent la même chose qu'un exemple précédent.

Compressez :

• Plus de trois éléments comparés sur plus de deux attributs → un tableau.
• Un paragraphe qui énumère des choses parallèles → une liste.
• Une phrase dont le sujet est une nominalisation → le verbe ("prendre une décision" → "décider").

Le plancher de compression. Arrêtez-vous lorsque la suppression du mot suivant supprime un fait. Un document plus court qui a perdu un fait est une régression, pas un gain. Le nombre de mots est un symptôme du travail, jamais son objectif.

La seule duplication conditionnellement autorisée est la reformulation en tête et en queue du bloc critique pour la cible agent, au-delà du seuil de longueur défini dans la Passe 4. En dessous de ce seuil, c'est une répétition comme une autre, et elle est supprimée.

Passe 4 — organiser pour le lecteur déclaré

Partagé : la loi d'ordonnancement

Ordonnez par ce qui bloque le lecteur, pas par l'historique du sujet :

1. Ce que c'est — une phrase, sans préambule.
2. Prérequis qui bloquent tout le reste — la variable d'environnement sans laquelle rien ne démarre, l'identifiant, la version requise.
3. Opérations destructrices et irréversibles — tout ce qui supprime, écrase, dépense de l'argent ou ne peut pas être annulé. C'est un placement par conséquence, pas par sujet : cela va près du haut même lorsque la commande est obscure, et c'est marqué, pas simplement mentionné.
4. Le chemin principal — la chose que la plupart des lecteurs sont venus faire, de bout en bout.
5. Tout le reste, le plus utilisé en premier.
6. Cas limites, dépannage et tables de référence en dernier.

Un bloc de résumé appartient en haut lorsque le document a plus d'environ cinq sections ; il énumère les faits dont un lecteur a besoin avant de pouvoir faire quoi que ce soit, pas un résumé de la prose.

--target=agent

Le lecteur est un modèle qui charge le document comme contexte, souvent après avoir cherché un terme et lu uniquement la tranche correspondante. Produisez un document avec cette forme :

1. Un bloc critique en premier, toujours ; le même bloc textuellement en dernier seulement au-delà d'environ 100 lignes. Les prérequis, opérations destructrices et contraintes strictes vont en premier, quelle que soit la longueur. La dégradation perdue-au-milieu (Liu et al., TACL 2024) est mesurée sur des contextes multi-documents dans la plage de milliers à dizaines de milliers de tokens — un document assez court pour être lu en un seul passage n'a pas de "milieu" en ce sens, et une copie en queue y est une pure duplication sans bénéfice de récupération. Ne dupliquez qu'une fois que le document dépasse le même seuil d'environ 100 lignes qui lui vaut une liste de contenu (#9 ci-dessous), où un lecteur qui cherche et tranche peut plausiblement atterrir au milieu du document et manquer le bloc. En dessous du seuil, énoncez-le une fois, en haut, et arrêtez-vous — une deuxième copie y est une régression que la passe 3 aurait dû attraper, pas une caractéristique de cette cible. Lorsque c'est justifié : intitulez la première copie ## Contraintes critiques et la dernière ## Contraintes critiques (répétition) — deux ancres uniques, un corps identique, le seul en-tête quasi-dupliqué que le document peut contenir.
2. Formulation positive. Énoncez l'action à entreprendre. Lorsqu'une interdiction est vraiment nécessaire, mettez l'alternative positive dans la même phrase : "écrivez dans state/, pas dans /tmp". Les modèles gèrent les énoncés négatifs de manière mesurablement moins bonne que les affirmatifs.
3. Un en-tête, une unité récupérable. Chaque en-tête est unique dans le document, littéral et composé des mots qu'un agent chercherait — à part la paire de blocs critiques ci-dessus. Sa section se tient seule : pas de "comme décrit ci-dessus", pas de pronom dont le référent est dans une autre section.
4. Identificateurs littéraux au point d'utilisation. Chemins complets, lignes de commande exactes, noms de variables d'environnement exacts, noms de fichiers exacts — à chaque fois, pas une fois avec des références après.
5. Énoncés vérifiables plutôt que narration. Une commande, un chemin, une valeur, une condition de sortie. Si une phrase ne peut pas être vérifiée, c'est probablement une justification — conservez-la uniquement là où elle change ce que l'agent fait.
6. Structure Markdown uniquement — en-têtes, listes, code délimité, petits tableaux. N'ajoutez pas de schéma de balisage XML à un document Markdown ; réservez les blocs JSON ou YAML pour le contenu qui sont véritablement des données lues par machine.
7. Forme la plus courte qui conserve chaque fait. La longueur d'entrée dégrade la récupération par elle-même, et le contenu topiquement adjacent qui ne répond à rien agit comme un distracteur — une prose quasi-exacte est pire que l'absence.
8. Pas de contradictions. Deux affirmations qui divergent sont pires qu'aucune. Résolvez-les avant d'écrire.
9. Une liste de contenu seulement au-delà d'environ 100 lignes, car l'agent peut lire une tranche plutôt que le fichier entier et ne peut autrement pas voir la portée.

Acceptation : un agent qui cherche un en-tête et lit uniquement cette section agit correctement.

--target=humain

Le lecteur parcourt avant de lire et lit une minorité des mots. Lorsque le formatage n'offre pas d'indices, ce parcours se dégrade en un balayage en forme de F le long du bord gauche — la structure est ce qui l'empêche, pas ce qui l'imite. Produisez un document avec cette forme :

1. Le propos dans la première phrase du document et de chaque section. Contenu le plus important dans les deux premiers paragraphes ; un lecteur qui s'arrête là a ce qu'il est venu chercher.
2. Lignes à charge frontale. Chaque en-tête, puce et paragraphe commence par ses mots porteurs d'information — les deux premiers mots d'une ligne sont lus, le reste est parcouru.
3. En-têtes descriptifs : "Configurer le répertoire d'état", jamais "Vue d'ensemble", "Notes", "Détails" ou "Section 3".
4. Une idée par paragraphe, environ quatre phrases au maximum.
5. Langage objectif. Un libellé neutre surpasse de manière mesurable un libellé promotionnel pour l'utilisabilité ; c'est un résultat de compréhension, pas une préférence de style.
6. Tableaux pour la comparaison, prose pour le raisonnement. Plus de trois éléments sur plus de deux attributs → tableau. L'explication connectée, causale ou nuancée reste en prose — fragmenter un argument en puces perd les liens.
7. Le vocabulaire du domaine reste. Définissez un terme une fois, en ligne, lors de la première utilisation. Ne simplifiez pas la précision technique, et ne réécrivez pas vers un score de formule de lisibilité — ces scores ne peuvent pas voir l'organisation et pénalisent la terminologie correcte.
8. Une liste de contenu au-delà d'environ deux écrans ou cinq sections.

Acceptation : un lecteur peut accomplir la tâche décrite par le document en utilisant uniquement le document.

Ce qui doit différer entre les cibles

Décision	--target=humain	--target=agent
Contraintes critiques	une fois, sur le premier écran, marquées	une fois en haut sous ~100 lignes ; d'abord et répétées textuellement en dernier au-delà
Indépendance des sections	les sections peuvent s'appuyer sur les précédentes	chaque section se suffit à elle-même
Références croisées	"voir ci-dessus" est acceptable	nommez l'en-tête exact
En-têtes	descriptifs et lisibles	uniques, littéraux, en forme de grep
Interdictions	"ne faites pas X" est acceptable	"faites Y" porte l'interdiction
Identificateurs	introduisez une fois, puis raccourcissez	complets et littéraux à chaque fois
Justification	la prose conserve les liens causaux	conservez uniquement là où cela change une action
Liste de contenu	au-delà d'environ 2 écrans	au-delà d'environ 100 lignes
Longueur	environ la moitié des mots d'origine	forme la plus courte conservant chaque fait

Vérification de divergence — REQUISE. Avant d'écrire le fichier, nommez au moins trois décisions que cette exécution a prises différemment à cause de la cible déclarée, et mettez-les dans le rapport.

...