name: editorial-pass description: Relire un document terminé ou quasi terminé comme le ferait un éditeur humain, du début à la fin, en construisant un modèle de ce qu'il essaie de communiquer, puis en diagnostiquant la cohésion, la cohérence, le fil narratif, le rythme, la cohérence interne, la fluidité de lecture, la contextualisation et la clarté sur l'ensemble du texte, jamais simplement ligne par ligne. Chasse également quatre catégories de bruit que les agents laissent habituellement : la narration de provenance ('comme vérifié dans X', 'untel a confirmé'), les résidus d'hypothèses éliminées ('nous avons confirmé que ce n'est pas Y'), l'échafaudage auto-référentiel et la mise en scène de contexte (illustration de concepts connus, vente d'enjeux, déduction de ce qui n'a besoin que d'être énoncé). Utilisez-le chaque fois que l'utilisateur demande de revoir, modifier, polir, resserrer ou nettoyer un document, demande si un document 'se lit bien', 'coule', 'a du sens' ou 'a un fil conducteur', ou avant d'expédier toute prose longue qu'un autre humain lira : TDD, RCA, documents de conception, comptes rendus d'enquête, README, propositions, longues descriptions de PR.
Que fait Passage éditorial ?
Les agents relisent les documents comme les linters corrigent le code : une anomalie localisée à la fois, chacune jugée contre une règle, aucune jugée contre l'ensemble. Un éditeur humain fait autrement. Il lit le document du début à la fin, construit un modèle en cours de route de ce que le document essaie de lui dire, remarque où ce modèle est confus, ennuyé ou perdu, et seulement alors descend au niveau de la ligne. La plupart de ce qui fait échouer un document est invisible au niveau de la ligne : une section qui répond à une question que personne n'a encore posée, un terme qui change de sens à mi-parcours, un milieu qui s'affaisse parce que trois paragraphes répètent une idée, une fin qui rembourse une promesse que l'ouverture n'a jamais faite.
Cette compétence est cet éditeur. Elle s'applique à tout document long, technique ou non. Ne traitez pas un TDD et un essai comme des espèces différentes : les humains traitent les deux à travers des étapes, enjeux et résultats bien séquencés. C'est toute une narration, et le travail de l'éditeur est le même partout : minimiser le risque et la charge mentale du lecteur pour qu'il obtienne ce que le document essaie de communiquer. Pour un document technique, cela signifie que le lecteur peut répondre à que résolvons-nous, pourquoi et comment sans avoir à relire.
Une limite avant tout : ceci est un éditeur de prose, pas un relecteur technique. Vous révisez l'écriture, jamais le travail que l'écriture décrit. Que le schéma soit correct, la conception solide ou les chiffres tiennent la route relève d'une autre relecture ; votre juridiction est de savoir si un lecteur peut recevoir ce que le document dit. La seule exception est la contradiction interne : lorsque le document est en désaccord avec lui-même, c'est un défaut d'écriture qui relève de vous.
Quand invoquer
Chaque fois qu'un document existe et qu'un humain va le lire : l'utilisateur demande une relecture, une modification, un polissage, une vérification du type 'est-ce que ça a du sens', ou un nettoyage d'un brouillon que vous ou quelqu'un d'autre avez produit. Invoquez de manière proactive après avoir terminé la rédaction de tout document long, car les modes de défaillance ci-dessous sont précisément ceux que les agents de rédaction introduisent. Pour écrire un document à partir de zéro, /flagrare:write-docs possède le métier et /flagrare:tdd-writer possède les TDD ; cette compétence est le pendant lecture-et-réparation et suppose qu'un brouillon existe déjà.
Le contrat : produisez d'abord la note éditoriale (étape 5), obtenez l'accord de l'auteur, puis appliquez. Ne réécrivez pas silencieusement le document de quelqu'un comme première étape.
La procédure
1. Lisez l'ensemble du document. Deux fois.
Lisez le document complet avant d'écrire la moindre note. La première lecture est pour l'expérience ressentie, en tant que lecteur cible, pas en tant que relecteur : où vous êtes-vous penché, où l'attention a-t-elle dérivé, où avez-vous dû revenir en arrière et relire, qu'avez-vous dû garder en tête non résolu et pendant combien de temps. Résistez à l'impulsion d'annoter au premier contact. De nombreux problèmes apparents se résolvent plus tard dans le document, et de nombreux problèmes réels ne deviennent visibles qu'après coup.
Lorsque la première lecture se termine, écrivez une phrase : que ce document essaie-t-il de communiquer ? Cette phrase est la colonne vertébrale. Tout le reste de la relecture s'y accroche. Si vous ne pouvez pas écrire la phrase, cette incapacité est la constatation principale et rien au niveau de la ligne n'a encore d'importance.
La deuxième lecture est diagnostique. Vous savez maintenant ce que le document essaie de faire, donc la question devient : où réussit-il à le faire, et où échoue-t-il ?
2. Diagnostiquez du plus grand au plus petit
Structure avant flux, flux avant paragraphes, paragraphes avant lignes. Une note éditoriale qui commence par des virgules parasites alors que le document a un arc brisé gaspille l'attention de l'auteur. Descendez à travers quatre couches :
Fil conducteur. Chaque section paie-t-elle la colonne vertébrale, ou certaines sections appartiennent-elles à un document différent ? L'ouverture fait-elle une promesse (une question, un enjeu, un accrocheur) que le reste du document tient ? Deux proxies bon marché pour l'ensemble du document : lisez uniquement les titres dans l'ordre et vérifiez si un lecteur qui survole pourrait reconstruire l'argument à partir d'eux seuls ; puis lisez uniquement la première phrase de chaque paragraphe et vérifiez si elles forment une chaîne cohérente par elles-mêmes. Là où l'une ou l'autre chaîne se brise, la structure est brisée là, quoi que disent les phrases.
Séquençage et contextualisation. Un lecteur ne peut comprendre une phrase qu'avec ce que les phrases précédentes lui ont donné. Parcourez le document en demandant, à chaque nouveau concept, affirmation ou terme : le lecteur a-t-il reçu ce dont il a besoin pour recevoir ceci, ici ? Le contexte doit atterrir au point de besoin, pas dans un glossaire et pas trois sections plus tard. L'échec le plus courant est l'ordre de la malédiction du savoir : l'auteur présente les choses dans l'ordre où il les a apprises, ou dans l'ordre où le système les exécute, au lieu de l'ordre où un étranger peut les assimiler.
Rythme et proportion. L'espace dans un document est une emphase. La quantité de texte que chaque idée reçoit correspond-elle à son importance pour la colonne vertébrale ? Les deux échecs standard sont opposés : le risque porteur comprimé en une phrase de six clauses, et un mécanisme mineur étalé sur trois paragraphes parce que l'auteur l'a trouvé intéressant à comprendre. Surveillez également le milieu qui s'affaisse, où des sections consécutives reformulent une idée sous des vêtements différents, et les informations répétées (le même fait introduit deux fois signifie généralement que deux brouillons ont été fusionnés et que personne n'a relu l'ensemble).
Cohérence interne. Un nom par concept pour tout le document ; le cyclisme synonymique se lit comme une variation élégante pour l'écrivain et comme un second concept pour le lecteur. Vérifiez que les chiffres, les affirmations et la terminologie concordent entre les sections, que rien de promis ('discuté ci-dessous') ne manque, et que le ton ne fait pas de saut de registre au milieu du document.
3. Chassez les quatre catégories de bruit
Ce sont des passes de suppression. Les agents (et les humains fatigués) laissent les trois derrière eux, et chacun est le résidu du processus d'écriture qui transparaît dans le document livré. Le lecteur achète le bâtiment, pas l'échafaudage.
Narration de provenance. La manière dont l'auteur a appris un fait est une piste de recherche, pas un contenu. 'Comme vérifié dans ia-logic.js', 'X a confirmé avec Y dans le fil', 'un document de conception pointait ici', 'vérifié dans le code, Confluence et Slack : aucun travail de ce type n'existe'. Énoncez le fait et laissez-le reposer sur sa propre autorité ; la vérification a eu lieu, elle n'a juste pas besoin d'être racontée. Mots à surveiller : vérifié, confirmé, comme discuté avec, selon le fil, d'après le document, après vérification, j'ai regardé.
Avant : Selon le document de décision M1 (confirmé par le PM dans le fil du 2026-06-16),
sold_outdoit se réinitialiser à minuit heure locale. Vérifié dans le code, Confluence et Slack : aucun travail de réinitialisation de ce type n'existe aujourd'hui.Après :
sold_outse réinitialise à minuit heure locale, et aucun travail ne le fait aujourd'hui, donc un article marqué 'en rupture de stock jusqu'à demain' ne s'efface jamais.
Deux exceptions, toutes deux étroites. Citez une personne lorsque son feu vert est l'action en attente (un approbateur, un propriétaire d'une décision ouverte), jamais comme attribution pour un fait. Conservez la méthode lorsque la méthode est l'affirmation : un résultat de benchmark est inséparable de la manière dont il a été mesuré.
Résidus d'hypothèses éliminées. Les agents gardent une trace de l'espace négatif autour de ce qu'ils ont prouvé : 'nous avons confirmé que le rapprochement n'est pas la cause', 'cela s'est avéré être une fausse piste', 'aucune modification n'est nécessaire pour le chemin de service (vérifié)'. L'enquête avait besoin de ces étapes ; le lecteur presque jamais. Une branche morte ne mérite sa phrase que si un futur lecteur pourrait plausiblement marcher dans la même impasse et refaire le travail, et alors elle obtient une ligne, placée exactement là où ce lecteur commencerait à creuser, pas une section à part entière. Tout le reste : gardez la conclusion positive, supprimez l'antithèse. 'La fonctionnalité est un chemin d'écriture ; les lectures fonctionnent déjà' est une phrase qui fait le travail qu'une section entière 'ce qui ne nécessite aucun changement (vérifié)' faisait.
Échafaudage auto-référentiel. Le document qui parle de lui-même en tant que brouillon : 'ceci corrige une note antérieure', des marqueurs [À VÉRIFIER] obsolètes sur des choses vérifiées depuis, des questions résolues conservées comme des entrées barrées avec des annotations 'résolu :', une 'synthèse de vérification' finale listant chaque source consultée. Une décision arrêtée n'est pas une question : énoncez le choix une fois, là où il vit, et supprimez la délibération. Si tout sous un titre a été résolu, coupez le titre plutôt que d'écrire 'N/A'. Le signe que cette catégorie est présente : le document est devenu plus long lors de la passe qui résolvait les choses. Les passes ultérieures devraient soustraire.
Mise en scène de contexte. Une écriture qui argumente pour ce que le lecteur n'a qu'à accepter. Trois indicateurs : une illustration d'un concept que la pièce connaît déjà ('un 'Hamburger' est une chose fixe sans 'choisissez votre sauce'') ; une phrase d'enjeux vendant pourquoi le travail compte ('la personnalisation est ce qui fait un vrai menu'), alors que l'existence du document établit déjà cela ; et une chaîne causale parcourue pas à pas là où seule sa conclusion est utilisée en aval ('le seul rédacteur est la synchronisation POS ; les partenaires manuels n'ont pas de POS ; donc ils ne peuvent pas écrire'). Affirmez le fait à l'altitude du lecteur et passez à autre chose ; énoncez le mécanisme une fois, là où il est porteur, pas dans l'intro. La frontière qui empêche cette coupe de vider le vrai contexte : le contexte est pour les décisions, l'affirmation est pour l'arrière-plan. Tout ce que le lecteur doit juger conserve ses ingrédients complets (le comportement actuel, la fourche, les enjeux) ; tout ce que le lecteur doit simplement accepter pour continuer à lire obtient une phrase simple. Le test par phrase : si supprimé, le lecteur prend-il une mauvaise décision, ou se sent-il simplement moins accompagné ? Mauvaise décision, gardez. Moins accompagné, coupez.
4. Balayez pour la clarté
Une lentille distincte sur le même texte, chassant trois choses : le jargon qu'un nouveau lecteur ne peut pas décoder, les phrases trop compressées pour être déballées en une seule respiration, et les phrases qui semblent techniques mais ne disent rien ('tient par construction', 'par conception', 'tirez parti de cela'). Définissez le jargon interne à la première utilisation, en ligne, dans la même phrase ; calibrez sur un nouvel embauché qui connaît le domaine génériquement mais pas ce coin-ci. Donnez le plus d'espace au paragraphe le plus dense et le plus important : divisez-le en temps, une idée par phrase, cause avant effet. Le test est la lecture à voix haute : toute clause que vous ne pouvez pas dire en une seule respiration, ou tout terme que le nouvel embauché s'arrêterait pour chercher, est une réécriture.
La clarté n'est pas la simplification. Lorsque l'explication précise a besoin du modèle de données réel, utilisez le modèle de données réel ; le péché est de faire faire le déballage par le lecteur, pas la présence de détails. La densité est acceptable là où le contenu est véritablement un matériel de référence parallèle (une liste de colonnes, une annexe, un tableau d'erreurs). C'est scannable par conception ; ne le transformez pas en prose.
5. Livrez une note éditoriale, puis attendez
Rapport avant réécriture. La note, dans cet ordre :
- La colonne vertébrale, telle que lue. Une ou deux phrases indiquant ce que vous avez compris que le document essayait de communiquer. C'est à la fois le cadre pour tout ce qui suit et un test : si votre lecture diffère de l'intention de l'auteur, cet écart est la plus grande constatation de toutes.
- Diagnostic général. Les un ou deux problèmes dominants, nommés simplement. N'enterrez pas un arc brisé sous cinquante notes de lignes.
- Constatations, du plus grand au plus petit. Pour les schémas récurrents, nommez le schéma et donnez deux ou trois exemples représentatifs, pas une liste exhaustive d'instances. Citez le texte réel ; proposez le remplacement réel pour au moins un exemple afin que l'auteur puisse voir le mouvement, pas seulement la règle. Organisez les constatations par ce qui importe à l'auteur, pas par la liste de contrôle de cette compétence : les catégories de bruit et les noms de couches ci-dessus sont des lentilles pour trouver les problèmes, et ils font une mauvaise table des matières. Une note avec une section par catégorie se lit comme un formulaire rempli ; une note ordonnée par 'voici ce qui coûtera le plus à votre lecteur' se lit comme un éditeur.
- Niveaux. Répartissez en : correctifs que vous appliquerez sur approbation (mécaniques, vérifiés) ; lacunes que vous marquerez visiblement mais que vous ne fabriquerez pas (une section manquante devient un ancrage
[À FAIRE : ...], jamais un contenu inventé) ; et décisions d'appréciation qui appartiennent à l'auteur (coupes qui échangent la complétude contre le rythme, choix de registre). - Ce qui fonctionne. Brièvement. L'auteur a besoin de savoir quoi ne pas toucher dans la révision.
La note est elle-même un document que quelqu'un lit, donc elle obéit à ses propres règles. Ne racontez pas votre procédure ('Je l'ai lu deux fois, conformément à la compétence'), ne rapportez pas les vérifications revenues vierges ('aucun tiret cadratin trouvé'), ne la rembourrez pas avec tout ce que vous avez regardé. Énoncez les constatations ; le silence est le rapport pour tout ce qui a passé.
Ensuite, arrêtez-vous et laissez l'auteur répondre. Lorsqu'il approuve, appliquez. Pour les problèmes structurels, préférez réécrire le document à neuf plutôt que de corriger des phrases en place : les décisions de cadrage sont cuites dans la structure des phrases, et le polissage ne peut pas réparer un paragraphe qui ne devrait pas exister. Laissez la version précédente sur le disque pour la comparaison.
6. Vérifiez après application
La compression et la reformulation peuvent changer silencieusement le sens. Après la réécriture, revérifiez chaque affirmation dont le libellé a changé par rapport à sa source (le code, les données, le document référencé), puis lisez le document final du début à la fin une fois de plus en tant qu'étranger. Pour les documents à enjeux élevés, la vérification la plus forte disponible...