Que fait research-log ?
Documente la recherche comme les ingénieurs la racontent après coup : un récit de mesures, un cahier des charges assez précis pour être réimplémenté, un relevé de vérification avec des chiffres, et une liste honnête de ce qui reste inconnu — livré sous forme d’un fichier HTML autonome (CSS et images intégrés, aucune ressource externe).
L’engagement fondamental : chaque affirmation est soit étayée par une mesure, soit marquée comme non prouvée, soit listée comme ouverte. La phrase directrice, si besoin : lire les artefacts vous dit ce que quelqu’un a écrit ; seul le système réel vous dit ce que cela signifie.
Workflow
1. Inventorier d’abord les preuves
Collecter, avant d’écrire quoi que ce soit, à partir de la conversation, du dépôt, des logs et de l’utilisateur :
- la chronologie : dates, ce qui a été essayé, ce qui a échoué, ce qui a surpris
- chaque mesure avec des chiffres exacts et comment elle a été obtenue
- les exécutions de vérification : ce qui a été comparé à quoi, et les chiffres d’erreur
- les outils, chemins de fichiers et commandes dont quelqu’un a besoin pour répéter le travail
- les questions non résolues et les hypothèses pures
N’inventez pas de mesures, de dates ou de chiffres. Si un nombre manque, demandez-le ou marquez-le OPEN. Un compte-rendu avec des données inventées est pire que pas de compte-rendu — les lacunes dans le relevé font partie du relevé.
2. Apprendre les conventions
Lisez references/style-guide.md avant d’écrire — le style vit dans ses détails (légendes qui prouvent un point, échecs conservés dans le récit, chiffres exacts, zéro marketing). Lisez references/content-format.md quand vous êtes prêt à écrire le module de contenu.
3. Choisir le squelette
Six sections principales, numérotées, dans cet ordre. N’en omettre une que pour une raison explicitée ; insérer des sections d’étude de cas entre le cahier des charges et les outils lorsqu’il y a un arc « construction du vrai système ».
| # | section | doit contenir |
|---|---|---|
| 1 | L’histoire | chronologie jour par jour ; chaque étape attribuée à une mesure ; impasses et surprises incluses |
| 2 | Méthode | une phrase d’épistémologie + le tableau : artefact de test → question → réponse |
| 3+ | Le cahier des charges | tableaux octets/protocole/format assez précis pour être réimplémentés, avec des tags de confiance ; les maths sous forme de blocs de code |
| −2 | Outils et mode d’emploi | vraies commandes et chemins qui fonctionnent quand copiés textuellement |
| −1 | Relevé de vérification | chaque exécution de mesure avec erreurs quantitatives + un encart Résultat final |
| −0 | Questions ouvertes | inconnues honnêtes, chacune taguée OPEN ou HYP |
4. Écrire et construire
Écrire le contenu sous forme d’un module Python définissant DOC (format dans references/content-format.md), le conserver dans le projet pour que le doc puisse être régénéré, puis :
python3 <skill-dir>/scripts/build_doc.py content.py out.html
Ouvrir le résultat et vérifier son rendu avant de le montrer à l’utilisateur.
5. Auto-audit
- chaque affirmation factuelle porte un tag ou se trouve dans le relevé de vérification
- l’histoire inclut au moins une surprise, un échec ou une correction — si le travail n’en a pas eu, dites-le franchement au lieu de fabriquer du drame
- les chiffres sont exacts et portent des unités (0,445 s, pas « rapide » ; 64 779 pixels, pas « beaucoup »)
- chaque légende de figure indique ce que l’image prouve, pas ce qu’elle montre
- les commandes du mode d’emploi ont été réellement exécutées, ou sont clairement étiquetées comme non testées
- des questions ouvertes existent (il y a toujours des questions ouvertes)
- le résultat final est une phrase que quelqu’un pourrait répéter de mémoire
Les tags
Quatre tags de confiance, placés en ligne à la fin de l’affirmation qu’ils qualifient :
- HW (vert) — mesuré sur le vrai système testé. Pour les travaux non matériels, cela s’applique encore : mesuré lors d’une exécution en direct, sur le banc, en production.
- FILE (bleu) — vrai dans tous les artefacts examinés (fichiers, captures, logs).
- HYP (violet) — cohérent avec toutes les preuves, mais non prouvé.
- OPEN (gris) — inconnu ; aucune preuve dans un sens ou dans l’autre.
Les faits portent des tags ; les commentaires non. Si le domaine a de meilleurs noms pour ceux-ci, renommez-les une fois en haut du document et utilisez-les de manière cohérente — mais gardez exactement cette division à quatre niveaux.
Ton
Ingénieur pair, première personne du pluriel, zéro marketing. Chiffres exacts avec unités. Phrases courtes. Humour sec et rare. Les échecs et corrections font partie de l’histoire, pas d’une note de bas de page. Les collègues sont crédités par leur rôle (« un collègue a livré deux séquences PNG… »).
Origine
Distillé à partir du journal de recherche TriCaster DVE (waldobjekt.org, 1–3 novembre 2026, rédigé avec Claude) — le document d’origine contient son propre build_doc.py ; cette compétence généralise cette configuration.