Files
Support-Agent/vues-deplacements/contexte/boucle-automatique.md
T

136 lines
16 KiB
Markdown

# 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) :
1. **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) ;
2. **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 » dans `displacement/`, images dans `images/`), 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, pas de revalidation générale après chaque modification ; on explore des données et on améliore peu à peu (l'utilisateur).
- 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.py` saute, 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`, contrat `detect(mesures)`, classés en événements par `categories.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), utilisés tels quels ; leur mode d'emploi est au §3 de `agents/diagnostic/instructions.md`. 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'index `INDEX.md`, le modèle de fiche (§11.3 de `docs/agents/agent-diagnostic.md`), le skill `anonymiser-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) :
1. **Analyste** : il écrit `critique.md`. Commit.
2. Verdict « d'accord » : on passe à l'étape 5.
3. **Upgrader** : il modifie les détecteurs et écrit `modification-K.md` (K : numéro du passage). Commit.
4. **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 par `git revert` les commits de détecteurs du lot).
5. **Builder** : s'il y a des nouveautés dans les rendus du lot, il ajoute les cas à la base, `agents/diagnostic/cas/`, et écrit `builder.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.
1. **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 ».
2. **Puis** la sortie de `categories.py` pour le lot.
3. **Comparaison**, événement par événement : juste ; catégorie fausse ; en trop ; bornes fausses (en retard, trop large) ; manquant.
4. **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.
5. **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.
6. **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.
### 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/*.py` et 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.py` sur 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 <date>, séance <dossier>, 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 »).
## 6. Ce que l'utilisateur trouve à la fin
- La branche `boucle/<AAAA-MM-JJ>_<STATION>` : un commit par étape, lisible avec `git 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 ; modification gardée, annulée ou aucune ; cas créés) ; les suggestions non traitées (nouvelle catégorie, au-delà de deux) ; les nouveautés déjà connues ; les erreurs.
## 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).