18 KiB
La boucle automatique : conception
Point 31 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 ; plan de construction : docs/superpowers/plans/2026-10-24-boucle-automatique.md. Ce qui vient de l'utilisateur est dit « l'utilisateur » ; le reste est un choix de Claude, marqué (choix de Claude).
1. Pourquoi
L'utilisateur veut que Claude apprenne sur des lots entiers de données de stations, sans lui : passer les détecteurs du journal du matin sur un lot, juger leurs résultats comme le ferait un expert, en regardant lui-même les courbes et les images, corriger les détecteurs, et garder sous forme de cas tout ce qui est nouveau. Puis passer au lot suivant.
À la fin d'une séance, il reste deux choses durables (l'utilisateur) :
- de la connaissance : de nouveaux cas, appris sur des événements réels, de la même forme que C-001 à C-005, ajoutés à la même base de cas,
agents/diagnostic/cas/: tous les cas sont au même endroit (l'utilisateur) ; - des détections optimisées : des détecteurs mieux réglés.
L'analyste et le validateur ne laissent rien de durable eux-mêmes : ce sont les juges qui y mènent.
2. Buts, non-buts, ce qui serait un échec
Buts. Une commande lance une séance sur une station ; elle tourne seule jusqu'au bout ; tout ce qu'elle fait est commité, étape par étape, pour s'y retrouver et revenir en arrière (l'utilisateur).
Non-buts.
- Récupérer les données : la boucle prend un dossier de station tel quel, au format de
data/<STATION>/(export « advanced » dansdisplacement/, images dansimages/), qu'il vienne du pompage (extraction/pomper.py, point 27) ou de CSV et d'images téléchargés à la main. - Les autres domaines (Energy, Storage, Cellular, Temperature) : les déplacements seulement.
- L'agent de diagnostic (
diagnostic, D-046) : il n'entre pas en jeu ici, à aucun moment il n'a de travail dans la boucle (l'utilisateur, 2026-10-24). Il sert au diagnostic pour l'utilisateur ; on le traitera dans une autre conversation, y compris ce que les cas appris changent pour lui. La boucle ne touche pas à ses consignes ; elle ne fait que compléter la base de cas. - L'exhaustivité : pas de rejeu des lots déjà vus par l'analyste, pas de revalidation générale après chaque modification ; on explore des données et on améliore peu à peu (l'utilisateur). Le score (D-062, §5) rejoue les lots d'avant sans regard de Claude, sur leurs étiquettes.
- Revalider les cas appris : peut-être plus tard, à la main, pas maintenant (l'utilisateur).
- Plusieurs analystes en parallèle : plus tard (annexe).
Ce qui serait un échec.
- La complexité : des détecteurs qui gonflent de règles et de cas particuliers pour un petit gain (la crainte de l'utilisateur).
- Toucher aux cas validés C-001 à C-005, ou aux catégories du journal, validées au point 5 du plan (choix de Claude).
- Un détecteur cassé qui disparaît sans bruit : le chargeur de
categories.pysaute, avec un simple message, un fichier qui ne se charge pas (constaté dans le code).
3. Ce qui existe et que la boucle réutilise
- Les détecteurs du journal :
vues-deplacements/journal/*.py, contratdetect(mesures), classés en événements parcategories.py. Le tri en lot existe (point 30, validé) :python3 vues-deplacements/journal/categories.py <dossier> --du AAAA-MM-JJ --au AAAA-MM-JJ --tranche 4 --historique 3. Chaque lot est classé avec les 3 jours d'avant : c'est la règle pour la boucle (D-056). - Les outils de lecture des données,
agents/diagnostic/outils/:inventaire.py,resume.py,graphique.py(PNG des séries),vignettes.py(gros plans des cibles sur les images) ; leur mode d'emploi est le skill.claude/skills/lire-les-donnees/, que suit l'analyste ; ils évoluent par/aiguiser(D-059,aiguiser-la-lecture.md), pas par la boucle. Seuls les outils servent : l'agent de diagnostic, lui, n'est pas appelé. - La carte des événements,
docs/displacement/domaine/carte-des-evenements.md: ce qui peut arriver, en familles, et les catégories du journal (section 4). - La base de cas,
agents/diagnostic/cas/: l'indexINDEX.md, le modèle de fiche (§11.3 dedocs/agents/agent-diagnostic.md), le skillanonymiser-cas(données copiées dans le dossier du cas, noms codés, D-049, D-050). Les cas existants ne se modifient jamais ; la boucle en ajoute. - Le registre des seuils,
vues-deplacements/contexte/seuils-du-journal.md: une constante changée le met à jour dans le même changement.
4. Une séance
Lancement : /boucle <dossier de station> [--du AAAA-MM-JJ] [--au AAAA-MM-JJ] [--lot 4], par l'utilisateur seul. Sans dates, toute la période du dossier. L'utilisateur pilote les lots (2026-10-24) : avec les données en masse, on ne traitera pas tout ; les lots se traitent indépendamment, il choisit lesquels (--du / --au sur la plage d'un lot pour un seul) ; la manière de les choisir reste à voir. Lots de 4 jours par défaut (l'utilisateur : « 4-5 jours, c'est égal »).
Mise en place (choix de Claude). L'orchestrateur crée la branche boucle/<AAAA-MM-JJ>_<STATION> depuis la branche courante et le dossier de la séance vues-deplacements/boucle/<AAAA-MM-JJTHHMMZ>_<STATION>/, hors de tout dossier de station (règle de vues-deplacements/CLAUDE.md). Il découpe la plage en lots, les mêmes que les tranches de categories.py.
Pour chaque lot, dans l'ordre (dossier lot-NN/ dans celui de la séance) :
- Analyste : il écrit
critique.md. Commit. - Verdict « d'accord » : on passe à l'étape 5.
- Upgrader : il modifie les détecteurs et écrit
modification-K.md(K : numéro du passage). Commit. - Validateur : il écrit
validation-K.md, « accepté » ou « à reprendre ». Commit. « À reprendre » : retour à l'étape 3, l'upgrader lit cette validation. Au plus trois passages de l'upgrader (choix de Claude) : à la troisième validation, le validateur n'a plus que deux réponses, « garder » (ça va dans le bon sens) ou « annuler » (l'orchestrateur annule pargit revertles commits de détecteurs du lot). - Builder : s'il y a des nouveautés dans les rendus du lot, il ajoute les cas à la base,
agents/diagnostic/cas/, et écritbuilder.md. Un commit pour les cas du lot (ils partagent la ligne d'index).
Le lot suivant tourne avec les détecteurs tels qu'ils sont devenus. À la fin, l'orchestrateur écrit bilan.md (§6) et le commite.
Comment les agents communiquent (choix de Claude, accepté le 2026-10-24). Ils ne se parlent pas. Chacun reçoit de l'orchestrateur un prompt court : le dossier de station, les dates du lot, les chemins des fichiers à lire. Il écrit son rendu dans le dossier du lot et répond en quelques lignes (verdict, chemins). L'orchestrateur est le seul à commiter et à changer de branche ; il commite par chemin, pour ne rien emporter d'autre (message Loop <STATION> lot NN: <rôle> …). Les agents tournent sur Opus (l'utilisateur).
Sans question : la séance tourne seule jusqu'au bout. Si un agent ne rend pas son fichier, l'orchestrateur le note dans le bilan et passe au lot suivant (choix de Claude).
5. Les rôles
Chaque rôle est un sous-agent de Claude Code, défini dans .claude/agents/<rôle>.md (ses consignes y sont), comme l'agent diagnostic. L'orchestrateur est un skill, lancé dans la conversation principale : un sous-agent ne peut pas lancer d'autres sous-agents.
Orchestrateur : skill .claude/skills/boucle/SKILL.md
Lancé par l'utilisateur seulement (comme /nouveau-cas). Il déroule le §4 et ne juge rien lui-même.
Analyste : .claude/agents/analyste.md, avec le skill critiquer-lot
La critique est un skill à part, à la demande de l'utilisateur ; on peut aussi la lancer à la main sur un lot, hors de la boucle. Outils : Read, Bash, Write. Il ne modifie rien.
- Sa propre lecture d'abord, sans la sortie des détecteurs (choix de Claude) : sinon il ne trouverait jamais ce que les détecteurs ratent. Inventaire, courbes du lot avec
graphique.py, vignettes espacées (une toutes les 2 à 3 h) et plus serrées là où les courbes bougent, images entières pour la scène. Il note chaque moment : début, fin, capteurs, ce qu'il voit, la catégorie de la carte qui conviendrait, ou « aucune catégorie ». - Puis la sortie de
categories.pypour le lot. - Comparaison, événement par événement : juste ; catégorie fausse ; en trop ; bornes fausses (en retard, trop large) ; manquant.
- Puis les cas, après les faits (sinon il chercherait ce que dit un cas au lieu de ce que montrent les données) : l'index
agents/diagnostic/cas/INDEX.md, avec les cas appris aux lots et aux séances d'avant. - Verdict : « d'accord » (rien d'important à corriger), ou des suggestions, au plus deux, les plus importantes (choix de Claude, contre la complexité) : le défaut, l'exemple (moment, capteurs), le détecteur en cause, ce qu'il faudrait, en mots et non en code.
- Nouveautés pour le builder : ce que ni la carte ni l'index ne décrivent, avec le moment, les capteurs et la figure qui le montre.
critique.md reprend ces six parties ; ses figures sont dans le dossier du lot.
Étiquettes (D-061, ajoutées le 2026-10-25) : juste après sa lecture, avant la sortie des détecteurs, l'analyste écrit aussi etiquettes.json, une entrée par moment de sa lecture (début, fin, capteurs, catégorie du journal, événement de la carte s'il est établi, preuve vue ou déduite), contrôlée par .claude/skills/critiquer-lot/etiquettes.py ; le format est dans critiquer-lot. Elles ne dépendent pas des détecteurs : ce sont les labels d'un futur modèle appris (point 44 du plan), à garder même si une modification est annulée. Toutes les étiquettes : vues-deplacements/boucle/*/lot-*/etiquettes.json.
Score (D-062, point 45 du plan, ajouté le 2026-10-25) : le but de la boucle est la précision de la détection sur tout le lot (l'utilisateur). python3 .claude/skills/boucle/score.py <dossier> compare, mesure par mesure et capteur par capteur, les événements des détecteurs aux étiquettes de tous les lots de la station : par catégorie et pour deux niveaux de validité (« à ignorer » : les zones grisées ; « prudence » : visibilité réduite et turbulence), « trouvées » (part des mesures étiquetées que les détecteurs signalent) et « justes » (part des mesures signalées que l'analyste a étiquetées). L'orchestrateur l'écrit au début de chaque lot (score-avant.txt) et en fin de séance (score-fin.txt) ; l'upgrader et le validateur le relancent après une modification : la catégorie en cause monte sur ce lot, sans baisse nette sur les lots d'avant. Le score est un fait, pas un verdict : l'analyste peut se tromper aussi. Choix de Claude, laissé par l'utilisateur, à revoir après la première séance : trois niveaux plutôt que deux, un compte par mesure plutôt que par événement, par capteur plutôt que pour toute la station. Le script est hors de journal/ : l'upgrader ne peut pas le modifier.
Upgrader : .claude/agents/upgrader.md
Il reprend les suggestions de l'analyste (et la dernière validation, s'il y en a une) et modifie les détecteurs. Outils : Read, Edit, Write, Bash.
- Il ne touche qu'à
vues-deplacements/journal/*.pyet au registre des seuils. - Le plus simple d'abord (choix de Claude, contre la complexité) : changer une constante ; sinon ajuster une règle existante ; sinon une règle nouvelle et courte ; un nouveau détecteur (contrat
detect(mesures)) en dernier recours. - Interdits : pas de nouvelle catégorie (une suggestion qui en demande une va au bilan) ; pas de règle propre à une station, à un capteur ou à une date ; contrat et clés des épisodes inchangés ; bibliothèque standard seulement.
- Il met à jour le registre des seuils et la docstring du détecteur dans le même changement.
- Il relance
categories.pysur le lot, avant et après. modification-K.md: ce qui a changé et pourquoi, les événements du lot avant et après, ce qu'il n'a pas pu corriger.
Validateur : .claude/agents/validateur.md
Il sait que l'upgrader est passé : il lit la critique, la modification et le diff des détecteurs depuis le début du lot. Il relance categories.py sur le lot et vérifie qu'aucun détecteur n'a été sauté au chargement. Il ne refait pas l'analyse des images (l'utilisateur). Outils : Read, Bash, Write ; il ne modifie pas le code.
- Ses questions : la modification répond-elle au défaut relevé par l'analyste ? Va-t-elle dans le bon sens sur ce lot ? Est-elle simple, à la mesure du gain ? Respecte-t-elle les interdits de l'upgrader ?
- Pas trop strict (consigne forte de l'utilisateur) : aucune modification n'est parfaite, et il y a toujours des imprévus. Il accepte ce qui va dans le bon sens, même imparfait. Il ne renvoie que pour un défaut net : le problème n'est pas réglé, un autre événement du lot est cassé, la complexité est hors de proportion, un interdit n'est pas respecté. Jamais pour demander ce que l'upgrader ne peut pas faire. Au plus trois remarques, concrètes.
validation-K.md: « accepté » ou « à reprendre » avec ses remarques ; à la troisième, « garder » ou « annuler ».
Builder : .claude/agents/builder.md
Il construit la base de connaissances (l'utilisateur). Outils : Read, Bash, Write, Edit. Il lit les nouveautés des rendus du lot ; c'est l'analyste qui en signale le plus, mais l'upgrader et le validateur peuvent en noter aussi (l'utilisateur : « pendant toutes ces phases »).
- Une seule base (l'utilisateur) :
agents/diagnostic/cas/, à côté de C-001 à C-005 ; numéro suivant de l'index (C-006…), comme/nouveau-cas. - Un cas par genre d'événement, pas par occurrence (choix de Claude) : si l'index a déjà un cas de même signature, rien.
- Sinon, un cas de la même forme que C-001 à C-005 : données de la fenêtre de l'événement, avec une marge, copiées et codées par
anonymiser-cas; fiche du §11.3 (résumé, symptôme, verdict, signature avec ses commandes, diagnostic, preuves avec leurs figures) ; ligne d'index. - Marqué « appris » (choix de Claude), pour la revalidation à la main, plus tard : en tête de fiche, « Appris par la boucle le , séance , non revalidé par l'expert » ; dans l'index, le Verdict commence par « (appris) ».
- Il ne touche jamais aux cas existants. Il ne passe pas par
/nouveau-cas(ni passage à l'aveugle, ni validation) : les cas appris s'ajoutent sans attendre (l'utilisateur : « ça ne peut pas vraiment faire de mal »).
Releveur : .claude/agents/releveur.md (D-060)
Ajouté le 2026-10-24, commun à tous les processus automatiques. Chaque rendu finit par ## Difficultés (consigne floue, contradictoire ou absente, chemin, format, commande ; « aucune » sinon). En fin de séance, l'orchestrateur l'appelle une fois, avec ses propres difficultés ; il retrouve la consigne ou le fichier en cause, regroupe les occurrences d'une même cause et note tout dans docs/ameliorations-processus.md. Il ne corrige rien : l'utilisateur s'en sert ensuite, dans une autre conversation.
6. Ce que l'utilisateur trouve à la fin
- La branche
boucle/<AAAA-MM-JJ>_<STATION>: un commit par étape, lisible avecgit log; il la fusionne, n'en garde qu'une partie, ou revient en arrière. bilan.md: une ligne par lot (verdict de l'analyste ; étiquettes ; modification gardée, annulée ou aucune ; cas créés), et le score de fin de séance (score-fin.txt) sur toutes les étiquettes de la station ; les suggestions non traitées (nouvelle catégorie, au-delà de deux) ; les nouveautés déjà connues ; les erreurs.docs/ameliorations-processus.md: les difficultés du processus relevées pendant la séance.
7. Essai et première séance
Essai du 2026-10-24 (tâche 1 du plan) : l'analyste seul sur le lot 1 de NORDEND d'octobre (05/10 → 09/10) : verdict « suggestions » (deux : une référence rejetée qui fausse la compensation de toutes les cibles, fondue dans un épisode au lieu d'être grisée ; un nombre de capteurs faux dans la phrase de la buée), une nouveauté (halo sur la vitre sous PR17 au saut du 08/10 02:30, cause non établie), la buée du 07/10 au 08/10 retrouvée ; 53 appels d'outils, ~250 000 jetons, 8 min 30 (Opus, effort élevé ; les images pèsent le plus). Fonctionnement validé par l'utilisateur le 2026-10-24.
Première séance : par l'utilisateur seul, plus tard, sur de nouvelles données, lot par lot, quand les autres développements seront faits. Claude ne la lance pas. Pour un essai sur des données déjà là, NORDEND d'octobre (vues-deplacements/cas/2026-10_NORDEND/NORDEND/, 11 jours, 3 lots de 4 jours) a une vérité connue.
8. Laissé au constructeur
Le texte des consignes de chaque agent ; le format exact des messages de commit ; la découpe des lots (en lisant l'en-tête de categories.py ou en la calculant) ; les colonnes des courbes de l'analyste ; la marge autour d'un événement pour les données d'un cas (proposition : 6 h ; seulement la fenêtre, pas tout le lot, pour ne pas commiter des centaines d'images par cas) ; une option de fenêtre dans anonymiser.py si elle manque (vérifiée par son --test) ; le mode de permission qui laisse une séance tourner sans demander d'accord.
À faire avec la construction : une entrée D-057 dans docs/decisions.md (la boucle ; la base de cas s'enrichit aussi par le builder, sans /nouveau-cas, ce qui complète D-048 ; l'agent de diagnostic hors de la boucle), une ligne dans CLAUDE.md et dans vues-deplacements/CLAUDE.md.
Annexe : pistes à revoir
- Plusieurs analystes en parallèle : les lots sont indépendants ; l'upgrader reste seul, pour que deux agents ne modifient jamais le même détecteur.
- La revalidation des cas appris par l'utilisateur.
- Le rejeu sur les lots déjà vus (écarté le 2026-10-24 : trop lourd, pas exhaustif voulu).
- Un plafond de lots ou de coût par séance.
- Plusieurs stations par séance.
- La durée : ~8 min 30 par lot pour l'analyste seul. Leviers : son effort (
high→medium, il réfléchit moins à chaque appel, change peu ce qu'il voit) ; moins de vignettes (toutes les 4 à 6 h, plus serrées là où ça bouge ; risque de rater un événement court). - Le choix des lots parmi beaucoup de données (l'utilisateur : « on verra comment on fait »).
- Le pompage en masse (points 27 à 29).