Files
Support-Agent/vues-deplacements/contexte/aiguiser-la-lecture.md
T
maximeandClaude Opus 5.5 3b732adc52 Loop renamed events-learner; end benchmark on the same events; spec reduced to the why (D-092)
- /boucle becomes /events-learner: skill and scripts in
  .claude/skills/events-learner/, sessions in events-learner/, spec
  vues-deplacements/contexte/events-learner.md, end page
  out/events-learner_<session>.html, commits "Learn <STATION> ...";
  history keeps /boucle, the review page reads both.
- No benchmark-fin.txt: the end benchmark is the last kept
  modification's, on the same events as the start.
- The spec keeps only the why; the how lives in the skill and agents.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 10:27:05 +01:00

21 KiB

Aiguiser la lecture : conception

Point 42 du plan docs/superpowers/plans/2026-10-23-journal-du-matin.md, brainstorming du 2026-10-24. Statut : approuvée par l'utilisateur le 2026-10-24, construite le même jour (D-059) ; plan de construction : docs/superpowers/plans/2026-10-24-aiguiser-la-lecture.md. Pendant la construction, une règle du projet est venue s'ajouter (D-060) : chaque rendu finit par ## Difficultés, et l'orchestrateur appelle le releveur en fin de séance. Ce qui vient de l'utilisateur est dit « l'utilisateur » ; le reste est un choix de Claude, marqué (choix de Claude) ; « accepté » : proposé par Claude, accepté par l'utilisateur le 2026-10-24.

1. Pourquoi

L'analyste de /events-learner et l'agent de diagnostic prennent les données d'un lot et en font un jugement. Pour bien juger, il faut d'abord bien lire les données, et ce n'est pas facile (l'utilisateur). Il y a deux côtés : la lecture (comprendre ce que montrent les courbes et les images) et le diagnostic (les détecteurs du journal, que l'analyste critique et que /events-learner améliore). Les deux ne demandent pas les mêmes scripts. Si l'analyste lisait les données avec les détecteurs, il serait biaisé et tendrait à les valider (l'utilisateur).

On veut donc un autre processus automatique, à part de /events-learner, qui ne travaille que sur le côté lecture : les outils dont Claude se sert pour lire les données, améliorés lot après lot, sur plusieurs jeux de données et sur plusieurs itérations, et repris quand de nouveaux champs de données arriveront. Le but : aiguiser la vision de Claude, et rendre l'analyste et l'agent de diagnostic plus performants en leur donnant des outils plus robustes (l'utilisateur).

2. Buts, non-buts, ce qui serait un échec

Buts.

  • Une commande lance une séance sur un dossier de station ; elle tourne seule jusqu'au bout ; tout est commité, étape par étape, directement sur master, comme /events-learner (D-070 ; d'abord sur une branche à part, accepté le 2026-10-24, remplacée par D-077).
  • À la fin, un skill de lecture meilleur (§4) : ses outils et son mode d'emploi. Il sert à l'analyste et à l'agent de diagnostic, donc chaque gain profite aux deux (accepté).
  • Elle tourne sur n'importe quelles données, sans vérité connue : pas seulement sur les cinq events validés (l'utilisateur).

Non-buts.

  • Les détecteurs du journal : c'est /events-learner.
  • La base d'events : la séance n'ajoute aucun event ; ce que le correcteur trouve de nouveau va au bilan, pour /events-learner ou /new-event (choix de Claude).
  • Le raisonnement de diagnostic : classer, comparer aux events, faire des hypothèses, conclure. Seule la lecture change.
  • Récupérer les données (un dossier de station au format de data/<STATION>/, comme /events-learner) ; les autres domaines.
  • L'exhaustivité : pas de rejeu des lots déjà vus, comme /events-learner.

Ce qui serait un échec.

  • Des outils qui jugent : un seuil, une catégorie, « anomalie ici » dans ce que rend un outil. Ils deviendraient des détecteurs de plus, et l'analyste finirait par valider ce qu'il lit (accepté).
  • Des outils taillés pour les events : un outil qui « sait » où chercher la buée de E-001, une règle propre à une station, à un capteur ou à une date (accepté).
  • La complexité : des outils qui se multiplient et un mode d'emploi qui s'allonge pour un petit gain (même crainte que pour /events-learner, accepté).
  • Casser une commande citée par une fiche d'events : les fiches E-001 à E-005 citent des commandes de resume.py, inventaire.py et vignettes.py avec leurs options, et les events existants ne se modifient jamais (constaté dans les fiches).
  • Un lecteur qui voit le corrigé, ou un correcteur qui lit avec les outils qu'on améliore : la mesure ne vaudrait plus rien.

3. Ce qui existe

  • Les outils de lecture, agent-tools/ (419 lignes) : donnees.py (lecture commune des exports), inventaire.py, resume.py, graphique.py (PNG des séries), vignettes.py (gros plans des capteurs sur les images). Bibliothèque standard, matplotlib par .venv pour les figures. Ils rendent des valeurs, jamais des verdicts.
  • Leur mode d'emploi est recopié à deux endroits : le tableau « Tes outils » et l'étape 1 de .claude/skills/analyser-lot/SKILL.md (l'analyste ; critiquer-lot avant D-090), le §3 et une partie du §4 (étapes 1, 2 et 4) de agent-diagnostic/instructions.md (l'agent de diagnostic).
  • Les cinq events validés, events/E-001/ à E-005/ : données (displacement/, images/), fiche event.md (signature en critères, avec leurs commandes) et figures, dans le même dossier.
  • Le modèle de /events-learner (D-057, vues-deplacements/contexte/events-learner.md, skill .claude/skills/events-learner/SKILL.md) : un skill orchestrateur dans la conversation principale, des sous-agents qui ne se parlent pas et écrivent chacun un rendu, une ligne **Verdict** : lue par grep, des commits par chemin, une branche par séance, un bilan.md. Un passage de l'analyste coûte environ 250 000 jetons et 8 min 30 (essai du 2026-10-24).

4. Ce qu'on optimise : le skill lire-les-donnees

Un skill, .claude/skills/lire-les-donnees/SKILL.md, devient la seule source du mode d'emploi de lecture (accepté). Il contient :

  • le tableau des outils de lecture (celui du §3 des instructions, sans categories.py, qui est un détecteur) et leurs conventions (instants en UTC, --fin inclusive, règles de Bash, « regarde chaque PNG avec Read ») ;
  • ce qu'il faut lire avant : docs/domaine/colonnes-des-deplacements.md et docs/domaine/pieges-des-donnees.md ;
  • la méthode de lecture d'un lot : inventaire ; large puis zoom ; chaque capteur face à son propre niveau habituel ; vignettes espacées, plus serrées là où les courbes bougent, avec un capteur témoin ; images entières pour la scène ;
  • ce que la lecture rend : une ligne par moment (début, fin, capteurs, colonnes, ce qu'on voit, ce que montrent les images).

Il ne contient ni catégorie, ni event, ni hypothèse, ni verdict : c'est l'affaire de celui qui l'appelle.

Ceux qui l'utilisent : l'analyste (« Tes outils » et l'étape 1 d'analyser-lot renvoient au skill ; l'étape 1 garde la catégorie de la carte, ajoutée après la lecture), l'agent de diagnostic (le §3 de ses instructions renvoie au skill et garde la ligne categories.py et la remarque sur --sortie ; ses étapes de diagnostic ne changent pas) et le lecteur (§6). Les sous-agents le lisent par Read, comme l'analyste lit critiquer-lot (choix de Claude).

L'optimiseur touche à deux choses, et seulement à elles : les scripts de agent-tools/ (y compris un nouveau script) et lire-les-donnees/SKILL.md.

5. Une séance

Lancement : /aiguiser <dossier de station> [--du AAAA-MM-JJ] [--au AAAA-MM-JJ] [--ameliorer], par l'utilisateur seul, d'après son expression « aiguiser la vision » (accepté). Séparé de /events-learner (l'utilisateur : « un autre processus automatique »). La plage est le lot, sans découpe, comme pour /events-learner (D-078, D-072) : une séance, un lot, de la longueur choisie par --du / --au (l'utilisateur).

Mise en place (choix de Claude, calquée sur /events-learner) : sur master, sans changer de branche (ailleurs, l'orchestrateur le dit et s'arrête), la base de la séance notée au bilan (D-077) ; dossier de séance aiguiser/<SEANCE>_<STATION>/, hors de tout dossier de station ; un dossier lot-01/, le lot de la séance. L'agent de diagnostic ne lit pas vues-deplacements/ : il ne verra pas les rendus de la séance.

Le lot, dans l'ordre (accepté) :

  1. Lecteur : il lit le lot avec le skill, rien d'autre, et écrit lecture-1.md. Commit.
  2. Correcteur, lecture lente : il lit le lot à fond, sans les outils de lecture, et écrit corrige.md ; puis il lit lecture-1.md et écrit ecart-1.md, avec son verdict, rien à reprendre ou à reprendre. Commit.
  3. rien à reprendre : fin de séance.
  4. Optimiseur, passage K = 1, 2 ou 3 : il modifie le skill d'après le dernier écart et écrit modification-K.md. Commit des outils, du skill et du lot.
  5. Lecteur à nouveau, sans rien savoir de la modification : lecture-(K+1).md. Commit.
  6. Correcteur, écart seul : il compare lecture-(K+1).md au même corrige.md, sans refaire la lecture lente, et écrit ecart-(K+1).md avec, en plus de son verdict, une ligne **Par rapport à la lecture précédente** : mieux | pareil | moins bien. Commit.
    • mieux : la modification reste.
    • pareil ou moins bien : l'orchestrateur remet les outils et le skill tels qu'ils étaient avant le passage K, et commite ; un changement sans gain n'est que de la complexité (choix de Claude). Le passage suivant de l'optimiseur lit le dernier écart gardé et la modification annulée, pour essayer autre chose.
    • Verdict rien à reprendre, ou trois passages faits : fin de séance. Sinon, retour à l'étape 4.

La séance suivante tourne avec le skill tel qu'il est devenu.

Commandes des fiches, une fois, en fin de séance : l'orchestrateur lance les commandes que citent les fiches de la base d'events (pas d'agent) ; les échecs vont au bilan. Rien n'est annulé d'office : le bilan le dit et l'utilisateur décide. Il n'y a plus de contrôle de lecture sur les cinq events validés (D-064) : l'utilisateur a validé les diagnostics de ces events, pas les outils qui les lisent.

Bilan : bilan.md, une ligne pour le lot (verdict du premier écart ; passages gardés, annulés ; verdict du dernier écart), les commandes des fiches en échec, les manques imputés au lecteur (que le skill ne pouvait pas corriger), les nouveautés vues par le correcteur (pour /events-learner ou /new-event), les erreurs. Commit.

Difficultés : le releveur note celles de la séance (D-060) ; avec --ameliorer, l'améliorateur (.claude/agents/ameliorateur.md, le même que pour /events-learner) corrige ensuite le skill /aiguiser, ses agents, voir.py, cette spec et run.md d'après ces relevés, et marque les entrées traité ; les outils de lecture et lire-les-donnees restent à l'optimiseur (D-076). Commit Sharpen <STATION>: process fixes.

Comment les agents communiquent : comme dans /events-learner : ils ne se parlent pas ; chacun reçoit un prompt court (dossier, dates du lot, chemins à lire, chemin de son rendu), écrit son rendu et répond en quelques lignes. L'orchestrateur est seul à commiter, par chemin. Modèle et effort de la session qui lance /aiguiser (model: inherit, sans effort, D-063 ; d'abord sur Opus). Sans question à l'utilisateur pendant la séance (choix de Claude, comme /events-learner).

6. Les rôles

Chaque rôle est un sous-agent, .claude/agents/<rôle>.md, avec omitClaudeMd: true ; l'orchestrateur est un skill, comme pour /events-learner (un sous-agent ne peut pas lancer de sous-agents).

Orchestrateur : skill .claude/skills/aiguiser/SKILL.md

Lancé par l'utilisateur seulement (disable-model-invocation: true). Il déroule le §5, ne juge rien et ne lit que les lignes de verdict.

Lecteur : .claude/agents/lecteur.md

Il teste le skill : il lit lire-les-donnees/SKILL.md et le suit, rien d'autre. Outils : Read, Bash, Write. Il lit le dossier de station par les outils du skill, les images par Read, et les deux notes de docs/domaine/ que le skill cite. Il ne lit pas : les détecteurs ni leur sortie, la base d'events, la carte des événements, les rendus de la séance (ni le corrigé, ni les écarts, ni les modifications), CLAUDE.md, docs/decisions.md, vues-deplacements/ hors du dossier de station, les autres séances de aiguiser/ et events-learner/. Il n'écrit aucun script.

lecture-K.md : le tableau des moments (début, fin, capteurs, colonnes, ce que je vois, ce que montrent les images) ; ce qui m'a manqué : où il a peiné, ce qu'il aurait voulu pouvoir regarder ; les sources lues. Ses figures dans lot-NN/lecture-K/, une lecture par dossier, pour qu'une lecture n'écrase pas les figures d'une autre (même nom de PNG).

Correcteur : .claude/agents/correcteur.md

C'est le validateur des outils de lecture ; « correcteur » parce qu'il compare une copie à un corrigé (accepté). Outils : Read, Bash, Write. Deux demandes :

  • Lecture lente : il lit le lot sans limite, avec ses propres scripts (bibliothèque standard, matplotlib par .venv), rangés avec ses figures dans lot-NN/corrige/, sur les exports bruts, et autant d'images qu'il le juge utile. Il peut lire docs/domaine/ et la carte des événements. Il n'utilise pas agent-tools/, pas même donnees.py (une erreur de lecture commune passerait inaperçue) (choix de Claude), ne lit pas lire-les-donnees/SKILL.md, ni les détecteurs, ni la base d'events, et il écrit corrige.md avant d'ouvrir la lecture. corrige.md a le même tableau que la lecture, pour comparer ligne à ligne (choix de Claude). Puis il écrit l'écart (ci-dessous).
  • Écart seul : corrige.md, la nouvelle lecture et le dernier écart ; il peut revenir aux données pour trancher (le lecteur a pu voir juste là où le corrigé s'est trompé : alors il corrige le corrigé et le dit).

ecart-K.md :

# Écart K : lot NN, <STATION>, <début> → <fin> (UTC)

**Verdict** : rien à reprendre | à reprendre
**Par rapport à la lecture précédente** : mieux | pareil | moins bien   (à partir de K = 2)

## Moments
| Moment (corrigé ou lecture) | Jugement : trouvé, manqué, de travers, en trop | Faute : outil, mode d'emploi, lecteur | Pourquoi |

## Défauts à corriger
### D1 : <titre>
- **Défaut** : … (ce que le skill ne montre pas, ou montre mal)
- **Exemple** : <moment UTC, capteurs>
- **Ce qu'il faudrait** : … (en mots, pas en code ; une règle générale)

## Nouveautés
aucune | - <moment, capteurs, ce qui le montre>

## Sources lues
  • La faute : à l'outil (il ne montrait pas la chose), au mode d'emploi (l'outil la montrait, mais le skill n'a pas fait regarder là), au lecteur (le skill disait de regarder, il ne l'a pas fait). Seules les deux premières vont à l'optimiseur (choix de Claude).
  • Mieux, pareil, moins bien : son jugement sur les moments importants du corrigé (manqués et lus de travers, en trop), motivé en une ligne sous la ligne de comparaison ; pas de score (choix de Claude).
  • Au plus deux défauts, les plus importants, comme les suggestions de l'analyste, contre la complexité (choix de Claude). rien à reprendre : aucun défaut d'outil ou de mode d'emploi qui compte.
  • Ses scripts lui servent à lire, pas à juger le skill ; l'optimiseur peut s'en inspirer : un script qui a montré ce que le lecteur a manqué est un bon candidat d'outil (choix de Claude).

Optimiseur : .claude/agents/optimiseur.md

Il reprend les défauts du dernier écart (et la modification annulée, s'il y en a une) et modifie le skill. Outils : Read, Edit, Write, Bash. Il peut lire le corrigé, les scripts du correcteur, la partie « ce qui m'a manqué » des lectures et les données du lot.

  • Il ne touche qu'à agent-tools/ et à lire-les-donnees/SKILL.md (§4).
  • Le plus simple d'abord (accepté) : une phrase du mode d'emploi ou un réglage par défaut ; sinon une option d'un outil existant ; un nouvel outil en dernier recours.
  • Interdits (accepté) : aucun jugement dans ce que rend un outil (ni seuil, ni catégorie, ni « anomalie ») ; rien de propre à une station, à un capteur ou à une date ; aucun import des détecteurs (detectors/) ; bibliothèque standard, matplotlib pour les figures seulement.
  • Ne rien casser : les options et les sorties existantes restent ; une commande citée par une fiche d'events marche toujours (constaté dans les fiches). Il relance l'outil modifié sur le lot, et une commande d'une fiche qui l'emploie.
  • modification-K.md : le défaut traité, ce qui a changé et pourquoi, la commande de l'essai et ce qu'elle rend, ce qu'il n'a pas pu faire.

7. Coût

Ordre de grandeur, à mesurer au premier essai : une lecture ≈ un passage de l'analyste (250 000 jetons, 8 min 30) ; la lecture lente plus ; au pire, par lot, 4 lectures, 1 lecture lente, 3 écarts et 3 passages de l'optimiseur ; le contrôle, 5 lectures et 5 écarts. C'est la raison du contrôle en fin de séance seulement (accepté) et de la lecture lente faite une fois par lot.

8. Ce que l'utilisateur trouve à la fin

  • Sur master, un commit par étape depuis la base de la séance notée au bilan ; il annule ce qu'il ne garde pas par git revert.
  • bilan.md (§5), et dans le lot le corrigé, les lectures et les écarts, pour voir ce que la vision de Claude a gagné.
  • Dans le lot, outils/index.html : ce que les outils, tels qu'ils sont devenus, rendent sur la plage du lot (texte imprimé et figures des cinq outils), avec la version des outils en tête. Le script aiguiser/voir.py <dossier> --debut T --fin T le produit aussi à la main, sur n'importe quelle plage (page dans out/voir/<STATION>_<plage>_<version des outils>/) : lancé à deux versions des outils, il donne deux pages à comparer. Sans agent ; les vignettes montrent les 3 capteurs qui s'écartent le plus de leur niveau habituel et le plus calme (choix de Claude).

9. Essai et première séance

Essai, pendant la construction (choix de Claude) : le lecteur puis le correcteur sur un lot dont la vérité est connue, sans l'optimiseur, pour voir l'écart et le coût ; par exemple le lot 1 de NORDEND d'octobre (vues-deplacements/cas/2026-10_NORDEND/NORDEND/, 05/10 → 09/10), déjà lu par l'analyste le 2026-10-24.

Essai du 2026-10-24, rendus dans out/aiguiser-essai/lot-01/ (non versionnés) :

  • Lecteur : 8 moments, dont la nuit du 07/10 17:15 → 08/10 14:15 (quatre cibles perdues, objet flou près de l'objectif), le saut de PR17 du 08/10 02:30 et la compensation sur deux références du 08/10 07:15 ; sept manques concrets (vignettes centrées sur la position habituelle d'une cible rejetée, mesure de la tache, luminosité de l'image dans le temps, niveau habituel sur une fenêtre au choix, colonne inlier, graphique « chaque capteur moins sa médiane », rejets partiels par pas) ; 209 000 jetons, 63 appels, 7 min.
  • Correcteur : 14 scripts à lui, aucun appel aux outils de lecture ; la même nuit (07/10 17:15 → 08/10 13:30) ; verdict à reprendre : un moment manqué (une petite marche de PR08, faute de l'outil), deux lus de travers (le mouvement commun de la caméra chaque matin, faute du mode d'emploi) ; deux défauts : regarder les positions brutes de tous les capteurs devant une vague commune des courbes corrigées ; montrer chaque capteur face à lui-même (son axe, un niveau pris avant le moment) ; 136 000 jetons, 46 appels, 8 min.
  • Biais relevé par les deux : docs/domaine/colonnes-des-deplacements.md et la carte des événements citent le saut de PR17 du 08/10 ; sur NORDEND d'octobre, ce moment ne mesure pas le skill. Sur de nouvelles données, rien de tel.
  • Deux consignes du skill corrigées d'après les difficultés du lecteur (Read ne prend pas de motif ; cd vers la racine), et une du correcteur (corriger son corrigé dès la lecture lente).

Première séance : par l'utilisateur seul, sur les lots qu'il choisit. Claude ne la lance pas.

10. Laissé au constructeur

Le texte des consignes de chaque agent ; le format exact des messages de commit ; le lot (la plage donnée, sans découpe, D-078) ; comment le lecteur lit un event sans voir sa fiche ni ses figures au contrôle (proposition : un dossier de liens vers displacement/ et images/, hors du dépôt) ; ce qui reste du §3 et du §4 des instructions de l'agent de diagnostic une fois le mode d'emploi passé dans le skill, sans changer son raisonnement ; le mode de permission qui laisse une séance tourner sans demander d'accord (le correcteur écrit et lance des scripts).

À faire avec la construction : une entrée D-059 dans docs/decisions.md (le skill de lecture, seule source du mode d'emploi ; /aiguiser ; ce qui reste de « ses outils propres » de D-058) ; une ligne dans CLAUDE.md et dans vues-deplacements/CLAUDE.md ; dans boucle-automatique.md (§3), les outils ne sont plus « utilisés tels quels » mais évoluent par /aiguiser ; la spec de l'agent de diagnostic, docs/agents/agent-diagnostic.md, pour le renvoi au skill.

Annexe : pistes à revoir

  • Deux lectures par passage, pour séparer le gain du hasard : deux lectures du même lot diffèrent d'elles-mêmes.
  • Le coût de la lecture (appels d'outils, jetons) comme second critère, à qualité égale.
  • De nouveaux champs de données (à terme, la base de la plateforme) : la même séance, sur ces champs (l'utilisateur).
  • /aiguiser et /events-learner sur les mêmes lots, l'un après l'autre.
  • Plusieurs correcteurs, ou un correcteur sur un autre modèle, contre les angles morts communs au lecteur et au correcteur.