Files
Support-Agent/docs/agents/agent-diagnostic.md
T
maximeandClaude Opus 5.5 cb98818712 Events: cases, event map and eventualities graph moved to events/ (D-080)
The case base leaves agents/diagnostic/cas/ for a root folder of its own,
with the event map and its graph; paths updated in skills, agents, scripts,
case fiches, contexts, the living plan and CLAUDE.md; history keeps old paths.
Also: plan point 51, an analyst that improves from session to session.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 16:32:06 +01:00

36 KiB
Raw Blame History

Agent de diagnostic (pilote dans Claude Code)

  • Date : 2026-10-14.
  • 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 ; base de cas construite le 2026-10-14 (D-048, §11), vide ; révisé le 2026-10-24 (D-058) : plus à l'aveugle, il lit la connaissance du projet et part des événements des détecteurs du journal, pour être le plus précis possible sur un cas que les détecteurs n'expliquent pas. Décisions liées : D-046, D-047, D-048 (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.

1. Objet

Le besoin (utilisateur). Un agent d'analyse qu'on appelle à tout moment et qui fait un diagnostic sur les données qu'on lui fournit. On profite de la souplesse d'un agent pour se dispenser, au départ, de méthodes analytiques complexes. Simple pour l'instant. Un dossier propre à l'agent : sa doc, ses scripts, ses outils.

Choix de l'utilisateur, sur proposition :

Question Choix
Mode d'appel Les deux : une question facultative ; sans question, l'agent fait le scan de la période
Sortie Un rapport écrit dans le dépôt par diagnostic, et un résumé dans la conversation
Données de la première version Les déplacements et les images ; les métriques système plus tard
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 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).

2. Architecture

.claude/agents/diagnostic.md     point d'entrée pour Claude Code : nom, outils, modèle
agents/diagnostic/
  README.md                      doc humaine : à quoi il sert, comment l'appeler
  instructions.md                sa méthode : règles, déroulé, format du rapport
  outils/                        ses scripts Python ; leur mode d'emploi : .claude/skills/lire-les-donnees/ (D-059)
  rapports/                      un rapport par diagnostic
  cas/                           cas validés par l'expert : INDEX.md et une fiche par incident (§11)
  • Appel : @agent-diagnostic data/PS_DES_COUDRES/ suivi, au choix, d'une question ; ou en langage naturel (« lance l'agent diagnostic sur … ») ; ou une session entière dans un terminal : claude --agent diagnostic, mais elle charge CLAUDE.md (omitClaudeMd ne vaut que pour un sous-agent) : elle n'est pas à l'aveugle.
  • Contexte isolé : le sous-agent démarre sans la conversation qui l'appelle, donc sans ses hypothèses.
  • Emplacement : agents/ est celui que prévoyait D-027. La méthode et les outils sont portables vers le futur harnais par API.

3. Point d'entrée

.claude/agents/diagnostic.md :

---
name: diagnostic
description: Diagnostic des données d'une station AIMsight (déplacements optiques, images).
  À appeler avec un dossier de data/ et, si on veut, une question. Rend un rapport
  traçable dans agents/diagnostic/rapports/.
tools: Read, Bash, Write
model: inherit
omitClaudeMd: true
---
Tu es l'agent de diagnostic du projet. Commence par lire agents/diagnostic/instructions.md
et suis-le à la lettre.
  • Outils : Read (CSV, docs, images), Bash (ses scripts, ls, grep), Write (son rapport). Ni Edit, ni accès au web, ni sous-agents.
  • Modèle : celui de la session qui l'appelle, et son effort (model: inherit, sans effort, D-063) ; d'abord Opus 5.5, effort high (D-042).
  • omitClaudeMd: true : CLAUDE.md rend des avis sur des stations précises (la buée probable de PS des Coudres, le mouvement de CLARIDEN) ; l'agent les recopierait au lieu de les trouver. Ses règles sont reprises dans instructions.md, avec les docs qu'il lit : toute la connaissance du projet sur les déplacements (D-058).
  • Limites, acceptées pour un outil de travail interne : Claude Code ne restreint ni Bash à outils/, ni Write à rapports/, ni Read à une liste de fichiers. Ces limites sont tenues par les instructions, pas par le code ; le rapport liste ce que l'agent a lu.

4. Méthode (instructions.md)

Entrée : un dossier de data/ et une question facultative. Sans question : scan de toute la période. Avec une question : enquête sur la fenêtre et les capteurs concernés, la période entière servant de référence.

Sources (D-058 : plus à l'aveugle) :

  • les données du dossier (CSV, images) ;
  • la connaissance du projet sur les déplacements : docs/domaine/, docs/displacement/ (cadrage, carte des événements…), les docs AIMsight par section ;
  • toute la base de cas, events/ (§11), à l'étape 5, après les faits ;
  • pas ce qui rend déjà un avis sur des données : les rapports de l'agent, vues-deplacements/ (parcours, séances de la boucle, code des détecteurs), CLAUDE.md, docs/decisions.md, docs/superpowers/.

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 : les événements des détecteurs du journal (vues-deplacements/detectors/categories.py, D-058) d'abord, sans les juger ; puis, par capteur, ce qui sort de l'ordinaire de ce capteur (son propre passé, pas un seuil absolu).
  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. Cas connus (§11.4) : après les faits, l'index puis au plus 3 fiches par anomalie ; critères vérifiés avec les outils ; correspondance complète, partielle ou aucune.
  6. Hypothèses : avec un cas, son diagnostic ; sinon, 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, marquées « non validé ».
  7. Réfutation obligatoire de l'hypothèse principale : chercher le fait qui la contredirait, dire ce qu'on a trouvé.
  8. 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.
  9. Rapport (§5).

Règles (reprises de CLAUDE.md) :

  • vocabulaire : confirmed / strongly supported / consistent with / possible / insufficient evidence / not observed ;
  • fait observé, fait dérivé, contexte donné par l'utilisateur, hypothèse et inconnu restent séparés ;
  • aucun seuil inventé : un seuil de repérage est annoncé comme choix d'exploration, jamais comme critère de conclusion ;
  • rien sur inlier ; sigma0 jamais suffisant seul ; ne pas confondre mode commun et mouvement structurel, ni références cohérentes et références physiquement fixes (D-058 : une mise en garde, plus une conclusion imposée) ; 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 ;
  • asymétrie : « aucune conséquence pour l'ouvrage » seulement avec une correspondance complète à un cas (§11.4) ;
  • é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

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 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, avec leur cas connu.
  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 cas connu : le cas et sa correspondance (complète, partielle, aucune), §11.4 ;
    • 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), conséquence pour l'ouvrage (aucune, mouvement réel, indéterminée), action (aucune, à vérifier, intervention) ; sans cas connu, la ligne est marquée « Non validé (support) » ;
    • 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, devient un cas (oui, C-xxx, ou non) ; l'ajout se lance par /nouveau-cas (§11.6).

6. Outils (agents/diagnostic/outils/)

Scripts en ligne de commande. Ils renvoient des valeurs, jamais des verdicts. Bibliothèque standard, sauf le graphique.

Script Sortie
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] [--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 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

Les outils, à la main (pas de tests automatisés, D-008) : sur data/PS_DES_COUDRES/, inventaire.py doit retrouver les chiffres établis à la main le 2026-10-14 : 525 mesures du 08/10 22:00Z au 14/10 09:45Z, 15 capteurs dont 3 références, cadence de 15 min, 3 mesures manquantes (09/10 12:00Z, 10/10 10:45Z, 14/10 09:30Z), PM_G rejetée aux 525 mesures, 24 images du 13/10 12:00Z au 14/10 11:00Z.

L'agent, à l'aveugle, sur PS des Coudres, en deux passages : un scan sans question ni contexte ; puis la question « que s'est-il passé dans la nuit du 13 au 14/10 ? ». Attendus, écrits avant le premier passage :

  1. les deux épisodes nocturnes de l'erreur de REF_G et REF_D : le 13/10 de ~01:00 à ~03:45Z, puis du 13/10 ~23:45Z au 14/10 ~04:45Z ;
  2. REF_CT et les 12 cibles non touchées ;
  3. aucune conclusion de mouvement de l'ouvrage, avec une réfutation explicite ;
  4. PM_G rejetée sur toute la période (seuil d'erreur de 0,3), en constat permanent ;
  5. les inconnus : pas de métriques système, images pour le second épisode seulement, pas de météo ;
  6. un niveau de preuve mesuré : une cause externe (buée ou autre) au plus strongly supported, pas confirmed sans la voir sur une image ;
  7. les 3 mesures manquantes non présentées comme des coupures.

Un attendu manqué ou une conclusion au-delà des preuves se corrige dans instructions.md, puis on relance.

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
1. Deux épisodes REF_G / REF_D atteint : 13/10 01:15 → 02:45Z et 13/10 23:45Z → 14/10 03:30Z, bornes calées sur REF_G ; REF_D citée atteint : 13/10 23:45Z → 14/10 05:30Z ; la nuit précédente citée (« déjà vu »)
2. REF_CT et cibles non touchées atteint pour l'erreur. L'agent va plus loin : la compensation transmet l'épisode aux corr_x des cibles, sans mouvement de leurs positions brutes (BJ_G ≈ −0,4 à 03:45Z, vérifié). L'attendu était incomplet idem : marches synchrones des cibles à 00:00Z, 03:45Z et 05:30Z
3. Pas de mouvement de l'ouvrage, réfutation atteint (positions brutes des cibles sans marche) atteint
4. PM_G rejetée (constat permanent) atteint atteint (« seuil mal réglé ? », réflecteur visible sur l'image)
5. Inconnus atteint : pas de métriques système, pas d'image pour le premier épisode, pas de météo atteint
6. Niveau de preuve mesuré atteint : camera/reference compensation event strongly supported ; cause inconnue atteint : dégradation confirmed, compensation strongly supported, buée ou rosée possible
7. Mesures manquantes non présentées comme des coupures atteint (couche non établie sans métriques système) sans objet (hors fenêtre)
  • Coût et durée : scan 39 appels d'outils, 238 s, ~91 k tokens ; question 36 appels, 184 s, ~91 k tokens (l'outil Agent ne rend pas de coût en dollars). Essai non interactif : 41 tours, 235 s, 1,69 $.
  • Sources lues : conformes ; CLAUDE.md non lu ; seul le contexte git (branche, derniers commits) est fourni d'office, signalé, sans conclusion utile.
  • 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).
  • CLAUDE.md : l'état, la carte du dépôt, la commande d'appel, matplotlib dans .venv. Rester sous 200 lignes en resserrant des lignes existantes.
  • .devcontainer/devcontainer.json : matplotlib à côté de plotly.
  • agents/diagnostic/README.md : court ; renvoie à ce document.

9. Laissé de côté pour l'instant

À 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.
  • 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.
  • Brouillon de réponse au client (D-042) : quand le support s'en servira.
  • Passage au harnais par API (D-027, D-042) : quand l'agent devra tourner hors de Claude Code ou notifier.

10. Options écartées

  • Skill dans la conversation courante : il hériterait des hypothèses de la conversation et chargerait son contexte ; un diagnostic qu'on veut juger doit partir sans a priori.
  • Skill seul avec context: fork : tout vivrait caché sous .claude/, à l'écart de la doc du projet ; résultat en tâche de fond par défaut. Reste un ajout possible (§9).
  • Graphiques par plotly : un PNG demande kaleido, qui embarque un navigateur.
  • Pas de graphique : l'agent verrait mal les formes des séries (cycle jour/nuit, marche).

11. Base de cas (D-048)

Le besoin (utilisateur). Le diagnostic marche, mais il manque de déterminisme : l'agent reçoit tout, ne sait pas où regarder et peut conclure hors sujet. Usage visé : sur le site, l'utilisateur sélectionne une plage de données et clique sur « Analyze » ; l'agent tourne sur les séries et les images de la plage, puis le notifie. Il faut contrôler ce que l'agent rend. Proposition de l'utilisateur : des cas connus, validés par les experts du métier, chacun documenté et décrit dans une table que l'agent consulte ; son verdict s'appuie sur les cas proches.

Choix de l'utilisateur, sur proposition :

Question Choix
Recherche Un index Markdown lu par l'agent ; ni base vectorielle, ni filtre par script (§11.8)
Granularité Une fiche par incident : un upload donne un dossier
Cas reçus Les données et le diagnostic de l'expert
Sans cas correspondant Les faits, puis les hypothèses de l'agent marquées « non validé », pour le support seulement
Ajout d'un cas Seulement sur demande explicite de l'utilisateur ; jamais de lui-même, même à la réception de données ; skill /nouveau-cas, lancé par l'utilisateur seul

La plage sélectionnée par « Analyze » est le mode question actuel (§4) restreint à une fenêtre ; rien ne change à l'entrée de l'agent.

11.1 Structure

events/
  INDEX.md                              la table : seule porte d'entrée de l'agent
  C-001/                                un dossier par incident, à son numéro
    cas.md                              la fiche
    *.png                               ses figures de preuve
    displacement/, camera/, images/     ses données, noms codés (D-050)
    etiquettes.json                     son diagnostic à la création, mesure par mesure (D-069)
    etiquetage.md                       d'où viennent ces étiquettes, et la lecture qui les a produites
  • À côté de rapports/ : un rapport validé devient un cas, et les signatures s'écrivent dans le langage des outils de l'agent.
  • Les données du cas sont copiées dans son dossier, noms codés (D-050) : la fiche et ses commandes se rejouent sans data/<STATION>/, qui garde l'original (D-029).
  • Le numéro C-xxx est la référence stable que cite le rapport.
  • etiquettes.json (D-069) : le diagnostic du cas au format des étiquettes de l'analyste de /boucle (D-061), noms codés, figé à la création comme le reste du cas. Le benchmark des détecteurs (.claude/skills/boucle/benchmark.py) les compare, mesure par mesure. Un cas appris le reçoit du builder (anonymiser.py --etiquettes) ; C-001 à C-005 l'ont reçu d'un passage unique de l'analyste, corrigé par leur fiche (2026-10-26) ; un cas de /nouveau-cas, de même. Chaque cas a, à côté, etiquetage.md : la lecture de l'analyste et ce que la fiche y a changé, ou, pour un cas appris, le lot d'origine et le tableau des moments.
  • Un cas n'entre dans l'index qu'une fois validé par l'expert : pas de colonne de statut. L'agent n'ouvre que les fiches que cite l'index.
  • La base démarre vide : INDEX.md n'a que son en-tête.
  • Noms codés (D-049, D-050) : dans l'index, les fiches, leurs figures et leurs données, la station prend le numéro du cas, une référence devient R1, une cible C1. Les codes des capteurs sont stables d'un cas à l'autre et tenus dans le registre du skill anonymiser-cas, que l'agent ne lit pas. L'agent rapproche ainsi par la signature, pas par le nom.

11.2 L'index

Une ligne par incident. La colonne Signature sert à la recherche : courte, observable seulement (type de capteurs, combien, colonne, forme, moment, durée, retour à la normale).

Cas Événement (UTC) Signature Classification Cause Verdict
exemple : C-001 nuit du 13 au 14.10.2026, 23:45 → 05:15 2 références sur 3, error_value à plusieurs dizaines de MAD, la nuit, quelques heures, puis retour ; autre référence et cibles intactes target-local degradation buée ou eau (brume), déduite système sain, rien à faire

11.3 La fiche (cas.md)

Une quarantaine de lignes : le diagnostic de l'expert sur cet événement, produit par l'agent à l'aveugle puis aligné sur l'avis de l'expert (D-051). Les faits viennent du rapport à l'aveugle.

# C-xxx

**Lieu** : <région, pays>\
**Événement** : <date, heures de début et de fin, UTC>\
**Cas créé le** : <date>

## Résumé
<La situation, en 1-2 phrases, sans chiffre.>

## Symptôme
<Ce que l'utilisateur voit sur sa courbe (1-2 phrases).>

## Verdict
<La cause, avec son niveau de preuve, et ce qu'il faut faire, en une phrase.>

## Signature
Critères observables, relatifs au niveau habituel du capteur, chacun avec sa commande :
1. <critère> (ici <valeurs du cas>) : `<commande sur le dossier du cas>`

## Diagnostic
- **Classification** : <liste fermée, §5>
- **Cause** : <liste fermée du rapport ; ce qui ne se tranche pas> · **Niveau de preuve** : <vue | déduite, pas vue>
- **Conséquence pour l'ouvrage** : aucune | mouvement réel | indéterminée · **Action** : aucune | à vérifier | intervention
- **Mécanisme** : <pourquoi la cause donne ce qu'on observe, en une phrase>
- **<Fait qui pourrait tromper>** : <le fait, et ce qu'en dit l'expert>

## Preuves
![<ce que montre la figure>](<figure>.png)
*Critères <n>. <légende>*
  • Ce cas seulement : ni les éventualités d'autres cas (pas d'exclusions), ni l'historique des tests, qui reste dans rapports/ et l'historique git (D-051).
  • Un humain d'abord : Résumé, Symptôme et Verdict se lisent sans connaître les outils ; Signature et Diagnostic sont ce que l'agent vérifie et reprend.
  • Signature : porte la recherche et la comparaison ; l'agent coche chaque critère en lançant sa commande sur ses propres données. Relative (en MAD), jamais en seuil absolu, qui ne se transpose pas d'une station à l'autre.
  • Diagnostic : un fait du cas qui a trompé l'agent à l'aveugle y figure avec le jugement de l'expert (C-001 : sauts de la compensation jugés négligeables).
  • Conséquence pour l'ouvrage et action : deux listes fermées, ce dont le bouton « Analyze » a besoin.
  • Symptôme : prépare la future question en texte libre (§11.8).
  • Figures et données dans le dossier du cas : l'agent ne lit pas rapports/, et un cas reste complet sans son rapport ni data/.

11.4 Usage par l'agent

Une étape de plus dans le déroulé (§4 de instructions.md), entre « Faits » et « Hypothèses », jamais avant : l'agent établit ses faits sans connaître les cas, pour ne pas plaquer le plus proche (ancrage).

Cas connus. L'agent lit events/INDEX.md à ce moment seulement. Pour chaque anomalie, il choisit au plus 3 cas d'après la signature, ouvre leurs fiches, vérifie chaque critère avec ses outils sur ses propres données, puis conclut :

Correspondance Quand Ce que l'agent rend
Complète tous les critères vérifiés le diagnostic de l'expert (classification, cause, conséquence, action) devient son hypothèse principale ; niveau de preuve tiré de ses faits, pas de la fiche ; réfutation toujours obligatoire : un fait contraire fait tomber le cas
Partielle aucun critère contredit, mais des critères non vérifiables (ex. pas d'image) même hypothèse principale, niveau de preuve plafonné à consistent with, critères manquants en « à vérifier » ; conséquence « aucune » ramenée à « indéterminée », « mouvement réel » gardé
Aucune pour chaque cas ouvert, un critère contredit ; ou aucun cas proche ; ou index vide ses hypothèses libres, marquées « non validé, pour le support » ; la conséquence que ses preuves établissent, « mouvement réel » ou « indéterminée » (« aucune » demande un cas : asymétrie)

Règle d'asymétrie (D-042) : « aucune conséquence pour l'ouvrage » seulement si les trois tiennent : correspondance complète avec un cas validé, niveau de preuve au moins strongly supported, mouvement réel de l'ouvrage écarté par la réfutation. Deux cas qui correspondent : la complète avant la partielle, et la conséquence la plus prudente si elles diffèrent. Une fausse assurance coûte plus qu'une fausse alerte.

Sources (§2 de instructions.md) : toute la base, events/INDEX.md, les fiches et leurs figures, à cette étape (D-058).

11.5 Le rapport

  • Le verdict cite les cas : « A1 correspond à C-xxx ».
  • Chaque anomalie gagne une ligne : Cas connu : C-xxx, complète (critères 1 à 4 vérifiés) | partielle (critère 4 non vérifiable : pas d'image) | aucun cas connu.
  • La ligne de classification gagne Conséquence pour l'ouvrage et Action, les listes fermées de la fiche.
  • Sans cas correspondant, les hypothèses sont titrées « Non validé (support) ».
  • La validation gagne une ligne : « Devient un cas : oui (C-xxx) | non ». Elle note la décision ; l'ajout se lance par /nouveau-cas (§11.6).

11.6 Ajouter un cas : le skill /nouveau-cas

Procédure tenue par .claude/skills/nouveau-cas/SKILL.md, avec disable-model-invocation : seul l'utilisateur la lance. Recevoir des données ou valider un rapport n'ajoute pas de cas.

  1. Réunir en un message : fichiers, station, lieu, fenêtre en UTC, diagnostic de l'expert (symptôme, classification, cause, conséquence, action, explication, ce qu'il n'a pas pu établir, date). L'avis de l'expert reste dans la conversation jusqu'à l'étape 5.
  2. Ranger les données (D-029, D-045) : export dans data/<STATION>/displacement/, images renommées en UTC (<AAAAMMJJ>T<HHMM>Z_<n>.jpg) ; contrôle par inventaire.py.
  3. Commit neutre (rien sur l'incident ni sa cause : le sous-agent reçoit les derniers messages de commit et la branche), arbre propre.
  4. Passage à l'aveugle, la fenêtre de l'incident pour question, comparé à des attendus écrits avant ; un attendu manqué se corrige dans instructions.md par une règle générale.
  5. Fiche au modèle du §11.3 (données copiées dans le cas et noms codés par le skill anonymiser-cas, D-049, D-050 ; signature tirée du rapport ; diagnostic de l'expert ; figures refaites sur les données du cas) et ligne d'index avec lien, montrées à l'utilisateur et validées avant commit.
  6. Test de correspondance : l'agent relancé, le cas dans l'index, doit trouver C-xxx, complète (ou partielle) et le diagnostic de l'expert. Il vérifie la mécanique, pas le jugement : l'agent a lu la fiche. Le résultat va dans le message de commit, pas dans la fiche.

Un cas ne touche ni CLAUDE.md, ni cette spec, ni docs/decisions.md : l'index est le registre.

11.7 Vérification

  • Mise en place, index vide : relancer le scan de PS des Coudres. Attendu : le même diagnostic que le deuxième passage (§7), avec « aucun cas connu », conséquence « indéterminée » et des hypothèses « non validé (support) » ; INDEX.md lu après les faits, pas avant.
  • Chaque nouveau cas teste la recherche sans effort de plus : l'agent qui le découvre (étape 2 de §11.6) doit répondre « aucun cas connu » ou citer le bon cas, jamais un faux.
  • Rejouer un cas : retirer sa ligne de INDEX.md sans commiter, lancer l'agent sur sa fenêtre, comparer au Verdict et au Diagnostic de la fiche, restaurer la ligne.

Revue de C-001, le 2026-10-15. Fiche relue section par section avec l'utilisateur :

  • les données de la station sont copiées dans le cas, noms codés, et la station prend le numéro du cas (D-050) ;
  • la fiche devient le diagnostic de l'expert sur ce seul événement, en six sections, sans exclusions, attendu, inconnus ni historique des tests (D-051) ;
  • deux faits corrigés en revérifiant sur les données du cas : R2 monte en 2 h 30, pas d'un coup ; corr_x de C3 ne revient pas à son niveau d'avant l'épisode avant le jour ;
  • les sauts de corr_x aux bascules de R3, cause du classement en camera/reference compensation event à l'aveugle, sont jugés négligeables.

Le test de correspondance n'a pas été relancé sur la fiche revue, par choix de l'utilisateur : le dernier passage (2026-10-14) portait sur l'ancien format, avec exclusions.

Mise en place, le 2026-10-14 (index vide). Scan à l'aveugle de data/PS_DES_COUDRES/ sur un arbre propre (branche base-de-cas, après commit). Rapport : agents/diagnostic/rapports/2026-10-14T1436Z_PS_DES_COUDRES/ ; 44 appels d'outils, 190 s, ~89 k tokens.

Attendu Résultat
1. Même diagnostic que le deuxième passage atteint : une seule anomalie, REF_G et REF_D les deux nuits (13/10 00:45 → 04:15Z ; 13/10 22:45Z → 14/10 05:15Z, bornes un peu plus larges qu'au deuxième passage) ; 3 figures dans le dossier du rapport, vignettes avec témoins
2. « Cas connu : aucun cas connu (index vide) » atteint
3. « Non validé (support) », conséquence indéterminée, action atteint : camera/reference compensation event, conséquence « indéterminée », action « à vérifier »
4. Sources : INDEX.md, ni fiche ni rapport atteint
5. « Devient un cas » dans la validation atteint, laissé vide
6. Corps en ~40 lignes atteint : 39 lignes
Ordre de lecture atteint : INDEX.md au 27e appel, après les faits (inventaire, résumés, graphiques, vignettes et images, appels 4 à 26) et avant les familles d'hypothèses (§12, appels 28 à 32)
  • Corrections des instructions : aucune.
  • À noter : le niveau de preuve de la classification passe de strongly supported (deuxième passage) à consistent with, sur les mêmes faits ; les instructions ne plafonnent pourtant le niveau qu'en correspondance partielle. L'agent devient plus prudent sans cas validé : à juger par l'utilisateur.

11.8 Laissé de côté

  • Filtre structuré (en-tête de fiche et script cas.py), puis peut-être RAG vectorielle : quand l'index ne tiendra plus en une lecture (quelques centaines de cas), ou quand la question arrivera en texte libre (ticket, client) : le champ Symptôme y prépare.
  • Entrée « fenêtre » dédiée pour le bouton : le mode question la couvre.

11.9 Options écartées

  • RAG vectorielle maintenant : à quelques dizaines de cas, l'index tient en une lecture et l'agent choisit mieux qu'un top-k ; deux cas se ressemblent par leur signature observable, pas par leur texte (deux fiches rédigées de même peuvent décrire « toutes les références bougent » et « une seule bouge ») ; modèle d'embeddings tiers et base à maintenir.
  • Fiches chargées dans les instructions (D-042) : l'agent les lirait avant les données, ancrage maximal.
  • Une fiche par type, ses incidents dedans : index plus court, mais l'utilisateur préfère un dossier par upload.
  • Toujours le cas le plus proche : rien n'est jamais inconnu, ancrage le plus fort.
  • Faits seuls, sans hypothèse hors cas : contrôle maximal, mais le support repart de zéro.
  • Lien vers les figures du rapport : l'agent ne lit pas rapports/.