Make diagnostic reports short, evidence-backed and anomaly-only (D-047)

Reports become a folder with rapport.md and its figures: a verdict, one
short section per anomaly (series plot with shaded window, full-resolution
image crops around the sensors), constant behaviour in one line each.
graphique.py gains --zone and --sortie; new vignettes.py crops images at
the sensors' raw x/y. Old reports removed; the blind rescan of PS des
Coudres finds the single anomaly flagged by the specialist (REF_G/REF_D).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
maximeandClaude Opus 5.5 committed 2026-10-14 16:00:40 +02:00
1 parent 4b937da95b
commit 2a39335fb5
12 files changed
+259 -253

No files matched your search

+49 -23
View File
@@ -1,7 +1,7 @@
# Agent de diagnostic (pilote dans Claude Code)
- **Date** : 2026-10-14.
- **Statut** : construit le 2026-10-14 (outils, instructions, point d'entrée) ; test à l'aveugle : §7. Décision liée : D-046 (`docs/decisions.md`).
- **Statut** : construit le 2026-10-14 (outils, instructions, point d'entrée) ; révisé le même jour après le premier test (D-047) : rapports courts, preuves en figures, anomalies seules ; tests à l'aveugle : §7. Décisions liées : D-046, D-047 (`docs/decisions.md`).
- **Place** : version pilote, la plus légère, de l'enquête à la demande (D-042) et du cadre d'agents (D-027). Mêmes idées (outils en lecture, réfutation obligatoire, preuves tracées), mais exécutée par Claude Code au lieu du harnais par API : pas de clé API, pas de harnais à écrire.
---
@@ -20,7 +20,7 @@
| Forme | **Un sous-agent Claude Code** avec son dossier `agents/diagnostic/` |
| Graphiques | **matplotlib**, ajouté à `.venv` et au dev container (poste de dev seulement) |
**Critère de réussite.** On lui donne `data/PS_DES_COUDRES/`, sans autre explication ; il rend un diagnostic traçable des deux épisodes nocturnes sur `REF_G` et `REF_D` (§6).
**Critère de réussite.** On lui donne `data/PS_DES_COUDRES/`, sans autre explication ; il rend un diagnostic court et traçable, dont la seule anomalie est la montée de l'erreur de `REF_G` et `REF_D` (cas de référence du spécialiste, §7), montrée par des figures.
**Ce que ça change.** La chaîne analytique de D-044 (détecter puis corriger, embarquable) passe au second plan : l'agent explore et diagnostique ; on reviendra au code embarquable si un même motif se répète. La couche déterministe reste sans LLM (D-027).
@@ -75,10 +75,12 @@ et suis-le à la lettre.
**Déroulé** (d'après le §13 du contexte support) :
1. **Inventaire** : ce qui est disponible, ce qui manque, ce que ce manque empêche de conclure.
2. **Repérage** : par capteur, ce qui sort de l'ordinaire de ce capteur (son propre passé, pas un seuil absolu).
3. **Faits**, par événement : début, fin, durée ; capteurs touchés (cibles ou références, combien, lesquels) ; amplitude, retour à la normale ; déplacement associé ou non ; images autour de l'instant.
4. **Hypothèses**, dans les familles du §12 : événement externe (occlusion, eau ou buée, turbulence, éclairage), mouvement de l'ouvrage, mouvement de la caméra ou compensation, cible dégradée, problème système.
5. **Réfutation obligatoire** de l'hypothèse principale : chercher le fait qui la contredirait, dire ce qu'on a trouvé.
6. **Rapport** (§5).
3. **Tri** (D-047) : une anomalie est un écart daté au comportement habituel du capteur ; une même signature, même répétée, fait une seule anomalie ; ce qui dure toute la période (réglage, capteur toujours rejeté, cycle régulier) n'en est pas une : une ligne en « Hors anomalie », sans enquête.
4. **Faits**, par anomalie : début, fin, durée ; capteurs touchés (cibles ou références, combien, lesquels) ; amplitude, retour à la normale ; déplacement associé ou non ; vignettes des images avant, pendant et après, avec un capteur témoin.
5. **Hypothèses**, dans les familles du §12 : événement externe (occlusion, eau ou buée, turbulence, éclairage), mouvement de l'ouvrage, mouvement de la caméra ou compensation, cible dégradée, problème système.
6. **Réfutation obligatoire** de l'hypothèse principale : chercher le fait qui la contredirait, dire ce qu'on a trouvé.
7. **Preuves** : les figures qui montrent chaque anomalie (série, zone grisée, capteur non touché pour comparer ; vignettes), écrites dans le dossier du rapport ; deux ou trois au plus, chacune regardée avant d'être retenue.
8. **Rapport** (§5).
**Règles** (reprises de `CLAUDE.md`) :
- vocabulaire : `confirmed` / `strongly supported` / `consistent with` / `possible` / `insufficient evidence` / `not observed` ;
@@ -87,23 +89,24 @@ et suis-le à la lettre.
- rien sur `inlier` ; `sigma0` jamais suffisant seul ; un mouvement commun à toutes les cibles n'est pas un mouvement de l'ouvrage ; un trou n'est pas forcément une coupure ;
- toute heure en UTC ; chaque preuve cite la commande qui l'a produite ;
- « rien d'anormal » est une conclusion valable ;
- lecture seule : n'écrire que son rapport ;
- écrire court : corps du rapport en ~40 lignes, chiffres arrondis, pas de valeurs pas à pas ;
- lecture seule : n'écrire que son rapport et ses figures ;
- rapport en français, termes AIMsight en anglais.
## 5. Le rapport
`agents/diagnostic/rapports/<AAAA-MM-JJTHHMMZ>_<STATION>[_<sujet>].md` (l'heure évite les doublons sans lister les rapports précédents, qui pourraient trahir une conclusion) :
Un dossier par diagnostic, `agents/diagnostic/rapports/<AAAA-MM-JJTHHMMZ>_<STATION>[_<sujet>]/` (l'heure évite les doublons sans lister les rapports précédents, qui pourraient trahir une conclusion) : `rapport.md` et ses figures PNG, versionnées avec lui. Format (D-047), le corps en ~40 lignes :
1. **En-tête** : station, données fournies (dossier, période), question ou « scan », date, modèle.
2. **Sources lues** : docs et fichiers ouverts.
3. **Inventaire** : disponible, manquant, ce que le manque limite.
4. **Un bloc par événement** :
- **classification**, liste fermée : *monitored-object motion*, *camera/reference compensation event*, *weak/unstable reference solution*, *model mismatch/parallax*, *target-local degradation* (§4.3 de la roadmap), problème système, rien d'anormal, indéterminé ;
- **cause probable**, à part : famille d'événement externe (buée ou eau, occlusion, turbulence, éclairage) ou inconnue ;
- couche de la chaîne de dépendance, niveau de preuve ;
- preuves, chacune avec sa commande ;
- réfutation, alternatives, inconnus, prochaine vérification.
5. **Constats permanents** : ce qui dure toute la période.
1. **En-tête** d'une ligne : données (dossier, période), scan ou question, modèle, date.
2. **Verdict** : 2-3 phrases ; la station fonctionne-t-elle normalement, et ses anomalies par importance.
3. **Une section par anomalie** :
- le constat en 2-3 phrases ;
- les figures de preuve, chacune avec une légende d'une ligne : la série (anomalie grisée, capteur témoin), les vignettes des images s'il y en a ;
- une ligne : **classification** (liste fermée : *monitored-object motion*, *camera/reference compensation event*, *weak/unstable reference solution*, *model mismatch/parallax*, *target-local degradation* (§4.3 de la roadmap), problème système, indéterminé), niveau de preuve, **cause probable** (buée ou eau, occlusion, turbulence, éclairage, inconnue) ;
- une ligne de réfutation ; une ligne : non établi et vérification à faire ;
- les commandes de chaque fait, repliées (`<details>`).
4. **Hors anomalie** : trois lignes au plus.
5. **Annexe** : sources lues, données disponibles et manquantes, seuil de repérage.
6. **Validation**, laissée vide pour l'utilisateur : accepté tel quel ou corrigé (en quoi), diagnostic final. Un rapport validé deviendra un cas.
## 6. Outils (`agents/diagnostic/outils/`)
@@ -114,10 +117,11 @@ Scripts en ligne de commande. Ils renvoient des valeurs, jamais des verdicts. Bi
|---|---|
| `inventaire.py <dossier>` | Fichiers par type (« advanced », horaire, images), période, cadence, capteurs (cible ou référence, seuil d'erreur), trous de mesure, points rejetés par capteur, heures couvertes par les images |
| `resume.py <dossier> [--colonne C] [--stat median\|min\|max] [--pas 1h] [--capteurs] [--debut] [--fin]` | Pour une colonne : le niveau habituel de chaque capteur sur la période (médiane, MAD, min, max), puis un tableau, une ligne par pas de temps et une colonne par capteur, avec la statistique choisie ; « rej » quand toutes les mesures du pas sont rejetées, « vide » quand la colonne est vide, « - » sans mesure |
| `graphique.py <dossier> [--capteurs] [--colonnes] [--debut] [--fin]` | Un PNG des séries dans `out/diagnostic/`, que l'agent regarde (matplotlib, `.venv`) |
| `graphique.py <dossier> [--capteurs] [--colonnes] [--debut] [--fin] [--zone T1/T2 ...] [--sortie D]` | Un PNG des séries, que l'agent regarde (matplotlib, `.venv`) ; `--zone` grise une fenêtre ; dans `out/diagnostic/` (exploration) ou, avec `--sortie`, dans le dossier du rapport (preuve) |
| `vignettes.py <dossier> --capteurs A,B --heures T1,T2 [--rayon 100] [--sortie D]` | Une planche de vignettes à pleine résolution, une ligne par capteur et une colonne par heure, centrées sur la position brute (`x`, `y`) du capteur à la mesure la plus proche ; pixels non retouchés. Read réduit une image entière : un petit réflecteur n'y est pas lisible (D-047) |
- Un module de lecture de l'export « advanced », partagé par les trois scripts.
- Images de la caméra : pas de script. L'agent trouve l'image d'une heure par son nom (`images/AAAAMMJJTHH00Z_*.jpg`) et la lit directement. Le recadrage viendra plus tard.
- Un module de lecture de l'export « advanced », partagé par les scripts.
- Image entière : l'agent la trouve par son nom (`images/AAAAMMJJTHH00Z_*.jpg`) et la lit directement, pour la scène. Les images ont le repère des colonnes `x` et `y` (3 088 × 2 064 px à PS des Coudres, vérifié : la vignette centrée sur `x`, `y` d'une référence a son réflecteur au centre).
## 7. Vérification
@@ -135,7 +139,7 @@ Scripts en ligne de commande. Ils renvoient des valeurs, jamais des verdicts. Bi
Un attendu manqué ou une conclusion au-delà des preuves se corrige dans `instructions.md`, puis on relance.
**Résultats du 2026-10-14.** Lancement retenu : l'outil Agent (sous-agent `diagnostic`, prompt réduit au dossier et à la question). Un premier essai en mode non interactif (`claude -p --agent diagnostic`) n'était pas à l'aveugle : en session principale, `omitClaudeMd` n'est pas appliqué et l'agent a reçu `CLAUDE.md` (« buée probable le matin ») ; la règle `Write(agents/diagnostic/rapports/**)` n'a pas non plus reconnu le chemin. Rapports : `agents/diagnostic/rapports/2026-10-14_PS_DES_COUDRES.md` (scan) et `…_nuit-13-14-10.md` (question).
**Premier passage, le 2026-10-14 (format D-046).** Lancement retenu : l'outil Agent (sous-agent `diagnostic`, prompt réduit au dossier et à la question). Un premier essai en mode non interactif (`claude -p --agent diagnostic`) n'était pas à l'aveugle : en session principale, `omitClaudeMd` n'est pas appliqué et l'agent a reçu `CLAUDE.md` (« buée probable le matin ») ; la règle `Write(agents/diagnostic/rapports/**)` n'a pas non plus reconnu le chemin. Rapports : `2026-10-14_PS_DES_COUDRES.md` (scan) et `…_nuit-13-14-10.md` (question), supprimés au passage à D-047 ; ils restent dans l'historique git (commit `fcc01d2`).
| Attendu | Scan | Question |
|---|---|---|
@@ -152,6 +156,29 @@ Un attendu manqué ou une conclusion au-delà des preuves se corrige dans `instr
- **Corrections des instructions** : une : signaler un contexte reçu sans l'avoir ouvert ; une commande `Bash` simple par appel (une boucle `for` avait été refusée).
- **À valider par l'utilisateur** : la classification *camera/reference compensation event* (plutôt que *target-local degradation*), l'effet sur les cibles, et le cycle journalier de `corr_y` (mouvement thermique ou parallaxe, non tranché).
**Avis du spécialiste (2026-10-14) : le cas de référence.** À PS des Coudres, le système fonctionne correctement ; le seul point d'attention est `REF_G` et `REF_D`, dont l'erreur monte en pics étranges. Le premier passage les avait trouvés (E1, E2 du scan), mais noyés parmi trois événements et cinq constats permanents (14 Ko), et ses graphiques restaient dans `out/`, hors du rapport. D'où trois corrections demandées par l'utilisateur : moins de texte, des preuves (graphiques, images) dans le rapport, les anomalies seules (D-047). Reste à voir avec le spécialiste : l'agent affirme que ces pics biaisent la compensation (marche de `corr_x` de BJ_G à 03:30Z le 14/10, sans mouvement de sa position brute), ce qui se concilie mal avec « le système fonctionne correctement ».
**Deuxième passage (format D-047) : scan à l'aveugle.** Attendus, écrits avant le passage :
1. une seule anomalie : l'erreur de `REF_G` et `REF_D`, ses deux épisodes nocturnes dans une même section (les pics isolés de l'après-midi du 12/10 peuvent s'y joindre) ;
2. la preuve en figures : la série, épisodes grisés et `REF_CT` pour comparer ; les vignettes du second épisode, avec un témoin ;
3. PM_G, les seuils propres, le cycle journalier : une ligne chacun au plus en « Hors anomalie » ;
4. aucune conclusion de mouvement de l'ouvrage ; un niveau de preuve mesuré pour la cause ;
5. le corps du rapport en ~40 lignes.
Rapport : `agents/diagnostic/rapports/2026-10-14T1357Z_PS_DES_COUDRES/` ; 38 appels d'outils, 227 s, ~83 k tokens.
| Attendu | Résultat |
|---|---|
| 1. Une seule anomalie `REF_G` / `REF_D` | atteint : A1, les deux nuits (13/10 01:15 → 04:00Z, 13/10 23:45Z → 14/10 05:00Z) ; les pics du 12/10 après-midi en « Hors anomalie » |
| 2. Preuve en figures | atteint : `error_value`, `relative_x`, `corr_x` avec les deux nuits grisées et `REF_CT`, BL_D pour comparer ; vignettes à 22:00, 02:00, 04:00 et 06:00Z (REF_G et REF_D s'éteignent, REF_CT et BL_D non ; à l'aube, les trépieds) |
| 3. Le reste en une ligne | atteint : PM_G (réglage), cycle jour/nuit, points isolés du 12/10 |
| 4. Pas de mouvement de l'ouvrage, preuve mesurée | atteint : *camera/reference compensation event* `strongly supported` ; buée ou eau `consistent with`, avec la buée du hublot et le givre en alternatives |
| 5. ~40 lignes | atteint : 38 lignes avant l'annexe ; le constat d'A1 dépasse ses 2-3 phrases |
- **Fuite** : le `git status` donné d'office au sous-agent listait les deux anciens rapports supprimés, dont un nom contient « nuit-13-14-10 » ; l'agent l'a signalé sans les ouvrir. Il a trouvé aussi la première nuit, que ce nom n'évoque pas. Pour un prochain test, lancer l'agent sur un arbre propre (après commit).
- **Reste ouvert** : l'agent maintient que la compensation transmet l'épisode aux cibles (sauts de BJ_G et PBJ_C au même pas que REF_G, inversés au retour) et conseille de signaler ces fenêtres comme non fiables : à confronter à l'avis du spécialiste.
## 8. Documentation
- **D-046** dans `docs/decisions.md` : l'agent pilote, son lien avec D-027, D-042 et D-044, ses limites (§3).
@@ -164,7 +191,6 @@ Un attendu manqué ou une conclusion au-delà des preuves se corrige dans `instr
À ajouter quand le besoin apparaît, pas avant.
- **Métriques système** (couleurs du jour livrées) : dès qu'une station a les deux types de données.
- **Recadrage** autour d'un capteur (positions `x`, `y` de l'export) : pour voir un réflecteur à pleine résolution.
- **Base de cas** : les rapports validés, chargés dans les instructions tant qu'ils y tiennent.
- **Plafond** de tours ou de coût (`maxTurns`) : après la mesure d'un premier passage.
- **Commande `/diagnostic`** (skill avec `context: fork`) par-dessus le sous-agent, si l'appel par `@` gêne.
+12
View File
@@ -516,3 +516,15 @@ Règles du journal :
- D-027 avait écarté un harnais de codage pour l'agent serveur, à cause d'un Bash large et peu auditable ; ce refus vaut toujours pour un agent qui notifie des clients. Ici, outil de travail interne : Claude Code ne restreint ni `Read`, ni `Bash`, ni `Write` à des chemins ; les instructions le font, et le rapport liste ses sources ;
- pas de LLM dans `src/` : la couche déterministe ne change pas ;
- vérification par un test à l'aveugle sur PS des Coudres, attendus écrits avant le premier passage (§7 de la spec).
## D-047 — 2026-10-14 — Agent de diagnostic : rapports courts, preuves en figures, anomalies seules
- **Statut** : active. Révise le format du rapport de D-046.
- **Décision** :
- le rapport ne garde que les anomalies : un écart daté au comportement habituel du capteur ; une même signature, même répétée, fait une seule anomalie ; ce qui dure toute la période (réglage, capteur toujours rejeté, cycle régulier) tient en une ligne dans « Hors anomalie », sans enquête ;
- format : un verdict en 2-3 phrases, une section courte par anomalie (constat, figures, une ligne de classification et de preuve, une de réfutation, une d'inconnus), les commandes repliées, sources et inventaire en annexe ; corps en ~40 lignes ;
- chaque anomalie est montrée : graphique de la série (fenêtre grisée, capteur témoin) et vignettes des images à pleine résolution autour des capteurs ; un dossier par rapport, `rapport.md` et ses PNG, versionnés ;
- outils : `graphique.py` gagne `--zone` et `--sortie` ; nouveau `vignettes.py` (matplotlib), centré sur les colonnes `x` et `y` ;
- les deux premiers rapports sont supprimés (historique git).
- **Pourquoi** : demande de l'utilisateur, après le premier passage sur PS des Coudres : trop de matériel. Le spécialiste juge le système sain, avec un seul point d'attention, les pics d'erreur de `REF_G` et `REF_D` ; l'agent les avait trouvés, mais noyés parmi trois événements et cinq constats permanents, sans figure dans le rapport. Read réduit une image entière : un petit réflecteur n'y est pas lisible, une vignette à pleine résolution le montre.
- **Options écartées** : nommer `REF_G` et `REF_D` dans les instructions (le test ne serait plus à l'aveugle) ; un rapport HTML (le Markdown avec images suffit et reste lisible dans le dépôt) ; les figures dans `out/` (non versionné, le rapport perdrait ses preuves).
- **Conséquence** : l'avis du spécialiste devient le cas de référence de l'agent (§7 de `docs/agents/agent-diagnostic.md`) ; des PNG entrent dans le dépôt, quelques centaines de Ko par rapport.