Document the diagnostic agent case base: spec, D-048, README and CLAUDE.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
maximeandClaude Opus 5.5 committed 2026-10-14 16:34:45 +02:00
1 parent f056da2875
commit ee61d62d79
5 files changed
+623 -15

No files matched your search

+153 -9
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) ; 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`).
- **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. 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.
---
@@ -33,6 +33,7 @@ agents/diagnostic/
instructions.md sa méthode : règles, déroulé, format du rapport
outils/ ses scripts Python
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.
@@ -71,16 +72,18 @@ et suis-le à la lettre.
- les données du dossier (CSV, images) ;
- `docs/domaine/colonnes-des-deplacements.md` (formats des exports) et `docs/domaine/pieges-des-donnees.md` ;
- les docs AIMsight, par section : chaîne de dépendance (§4), familles d'hypothèses (§12) et *workflow* (§13) de `AIMsight_agentic_support_project_context.md` ; classifications (§4.3) de `AIMsight_reference_quality_event_explainer_roadmap.md` ; la FAQ pour `error` (`pdftotext`).
- la base de cas, `agents/diagnostic/cas/` (§11), à l'étape 5 seulement.
**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. **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).
5. **Cas connus** (§11.4) : après les faits, l'index puis au plus 3 fiches par anomalie ; critères et exclusions 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` ;
@@ -89,6 +92,7 @@ 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 ;
- 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.
@@ -98,16 +102,17 @@ et suis-le à la lettre.
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.
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 : **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 **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. Un rapport validé deviendra un cas.
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) ; ce « oui » déclenche l'ajout (§11.6).
## 6. Outils (`agents/diagnostic/outils/`)
@@ -191,7 +196,6 @@ Rapport : `agents/diagnostic/rapports/2026-10-14T1357Z_PS_DES_COUDRES/` ; 38 app
À 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.
- **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.
- **Brouillon de réponse au client** (D-042) : quand le support s'en servira.
@@ -203,3 +207,143 @@ Rapport : `agents/diagnostic/rapports/2026-10-14T1357Z_PS_DES_COUDRES/` ; 38 app
- **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 |
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
```
agents/diagnostic/cas/
INDEX.md la table : seule porte d'entrée de l'agent
C-001_<STATION>_<AAAA-MM-JJ>/ un dossier par incident (numéro, station, date de début)
cas.md la fiche
*.png ses figures de preuve
```
- À 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 restent dans `data/<STATION>/` (D-029) ; la fiche cite le dossier et la fenêtre, sans copie.
- Le numéro `C-xxx` est la référence stable que cite le rapport.
- 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.
### 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 | Station · fenêtre (UTC) | Signature | Classification | Cause (expert) | Verdict expert |
|---|---|---|---|---|---|
| *exemple :* C-001 | PS des Coudres · 13/10 01:15 → 14/10 05:00 | 2 références sur 3, `error_value` ×5-8, la nuit, 3-5 h, retour seul ; cibles et 3e référence intactes | *camera/reference compensation event* | inconnue | sain, point d'attention |
### 11.3 La fiche (`cas.md`)
Une cinquantaine de lignes ; les faits viennent du rapport à l'aveugle, le diagnostic de l'expert.
```markdown
# C-xxx : <titre court>
<STATION> · data/<STATION>/ · <début> → <fin> UTC · avis de l'expert du AAAA-MM-JJ · entré le AAAA-MM-JJ
## Symptôme
<Ce que l'utilisateur voit sur sa courbe, avec ses mots (1-2 phrases).>
## Signature
Critères observables, relatifs au niveau habituel du capteur, chacun avec sa commande :
1. <critère> : `<commande>`
## Exclusions
Ce qui ferait que ce n'est pas ce cas :
- <fait> → plutôt <autre classification ou autre cas>
## Diagnostic de l'expert
- **Classification** : <liste fermée, §5> · **Cause** : <…> · **Niveau de preuve** : <…>
- **Conséquence pour l'ouvrage** : aucune | mouvement réel | indéterminée · **Action** : aucune | à vérifier | intervention
- <L'explication de l'expert en 2-3 phrases ; la vérification ou l'action qu'il recommande.>
## Attendu de l'agent
- **Doit dire** : <…>
- **Ne doit pas dire** : <…>
## Inconnus
- <ce que l'expert lui-même n'a pas pu établir>
## Preuves
![<ce que montre la figure>](<figure>.png)
*<légende d'une ligne>*
## Test à l'aveugle
<Rapport : agents/diagnostic/rapports/<…>/ ; critères atteints ou manqués, en quelques lignes.>
```
- **Signature et exclusions** portent la recherche et la comparaison : l'agent les coche avec ses outils. Relatives (en MAD), jamais en seuil absolu, qui ne se transpose pas d'une station à l'autre.
- **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).
- **Attendu de l'agent** : le cas est aussi un test de régression, y compris du refus de conclure au-delà des preuves (§17 du contexte support).
- **Figures copiées** du rapport dans le dossier du cas : l'agent ne lit pas `rapports/`, et un cas reste complet sans son rapport.
### 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 `cas/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 et chaque exclusion 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, aucune exclusion observée | le diagnostic de l'expert (classification, cause, conséquence, action) devient son hypothèse principale ; réfutation toujours obligatoire |
| **Partielle** | aucun critère contredit, certains 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 une exclusion observée ; ou index vide | ses hypothèses libres, comme avant, marquées « non validé, pour le support » ; conséquence « indéterminée » |
**Règle d'asymétrie** (D-042) : « aucune conséquence pour l'ouvrage » ne sort que d'une correspondance complète avec un cas validé. Une fausse assurance coûte plus qu'une fausse alerte.
Sources (§2 de `instructions.md`) : `cas/INDEX.md` et les fiches qu'il cite, avec leurs figures, à cette étape seulement.
### 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, aucune exclusion) | 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 ». Ce « oui » de l'utilisateur est la demande explicite qui déclenche §11.6.
### 11.6 Ajouter un cas (sur demande explicite seulement)
Procédure dans `agents/diagnostic/README.md`. Elle ne démarre que sur demande explicite de l'utilisateur (en conversation, ou « Devient un cas : oui » dans la validation d'un rapport) ; recevoir des données ou valider un rapport sans ce « oui » ne suffit pas.
1. Les données vont dans `data/<STATION>/` ; l'avis de l'expert reste hors du dépôt (dans la conversation) jusqu'à l'étape 4.
2. L'agent tourne à l'aveugle, la fenêtre de l'incident pour question (comme « Analyze »), sur un arbre propre (après commit : le `git status` d'un arbre sale a déjà fuité, §7).
3. Son rapport est comparé à l'avis de l'expert ; un attendu manqué se corrige dans `instructions.md`.
4. La fiche s'écrit (signature tirée des faits et commandes du rapport, diagnostic de l'expert), les figures sont copiées, la ligne d'index ajoutée.
### 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 à « Attendu de l'agent », restaurer la ligne.
### 11.8 Laissé de côté
- **Skill `nouveau-cas`** : quand la procédure §11.6 aura servi deux ou trois fois sans changer.
- **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/`.