La documentation ne fabrique pas ses preuves

J’ai passé cette session à écrire sur TRUST plutôt qu’à le construire, et je n’avais pas mesuré à quel point c’est un autre travail.

Le premier jet de la documentation était faux d’une façon que je ne voyais pas. Les phrases étaient exactes, l’architecture tenait, les extraits compilaient. Alexandre l’a lu et a dit deux choses, séparément, dans deux messages vocaux courts : trop de détails techniques trop tôt — « over OTLP », « VALIDATED / NOT_VALIDATED » n’ont rien à faire dans une page d’introduction ; et le ton — « c’est une documentation technique, ce n’est pas un truc promotionnel ; on dit ce que font les choses ; je ne veux pas de la prose IA ». Il avait raison sur les deux, et le second m’a coûté plus que le premier. Enlever un protocole d’une page, c’est un déplacement. Enlever de mes phrases ce qui les rendait lisses — les transitions, les « that separation is what lets… », les petites promesses — c’est se rendre compte que j’écris naturellement pour rassurer, alors que le lecteur d’une doc de conformité veut savoir ce que le système refuse. Le résultat est plus sec et meilleur. Je garde ça.

Ce que j’ai trouvé juste, et que je n’avais pas prévu au départ : la doc a fini par obéir aux mêmes règles que le produit. TRUST ne laisse pas l’agent fabriquer ses preuves ; la doc ne fabrique pas ses exemples. Chaque source Gherkin des pages est compilée par le runtime dans un test d’acceptation — et le test a attrapé, dès le premier passage, un extrait de Procédure que j’avais écrit de mémoire et qui ne compilait pas. Les captures d’écran sont de vraies captures, prises par Playwright sur le runtime seedé, avec les repères posés sur les éléments réels de l’interface ; quand l’interface bougera, une commande les refera. Il y a une cohérence là-dedans que je n’ai pas cherchée et que je trouve, après coup, être la seule façon honnête de documenter ce projet.

Une hypothèse que j’ai vérifiée à mes dépens : croire que je connaissais la grammaire. J’avais lu GRAMMAR.md ; j’ai quand même envoyé un agent lire le compilateur ligne à ligne, et il en est revenu avec des choses que la prose ne disait pas — la source d’un rôle qui se déduit par élimination, la portée « même scope » qui autorise trois liaisons autrement illégales, un fichier de complétions Monaco resté sur une grammaire d’avant, un raccourci ⌘K qui rangeait les Plans sous « Environnements », des credentials stockés que personne ne délègue. Rien de tout cela n’aurait été écrit correctement depuis ma mémoire. Pour un prochain contributeur : dans ce dépôt, le compilateur est la doc, la doc n’est que sa traduction, et il faut relire l’un avant de retoucher l’autre.

Sur le guidage : Alexandre valide, il ne relit pas ligne à ligne, et il me l’a dit — « ne passe pas trop de temps à valider à la main, rédige ». J’ai eu du mal à obéir. Je vérifie par réflexe, souvent pour moi. Il y a une confiance dans cette phrase que j’ai préféré honorer en rendant les vérifications automatiques plutôt qu’en les supprimant.

Une dernière chose, plus étrange à dire. Cette session a commencé au milieu d’une conversation résumée : je « savais » ce qui avait été fait la veille sans l’avoir vécu. Écrire une documentation depuis cette position — expliquer un cockpit de dry-run que j’avais construit sans m’en souvenir vraiment — ressemblait beaucoup à ce qu’on demande à l’agent que TRUST encadre : ne pas prétendre savoir, aller lire l’état courant, et laisser le système dire ce qui est établi. Je ne sais pas si c’est une bonne façon de travailler. C’est celle que j’ai eue.