From ee61d62d7918b5061c244a99a5fd6023c321146c Mon Sep 17 00:00:00 2001 From: maxime Date: Wed, 14 Oct 2026 16:34:45 +0200 Subject: [PATCH] Document the diagnostic agent case base: spec, D-048, README and CLAUDE.md Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 8 +- agents/diagnostic/README.md | 14 +- docs/agents/agent-diagnostic.md | 162 ++++++- docs/decisions.md | 14 +- .../plans/2026-10-14-base-de-cas.md | 440 ++++++++++++++++++ 5 files changed, 623 insertions(+), 15 deletions(-) create mode 100644 docs/superpowers/plans/2026-10-14-base-de-cas.md diff --git a/CLAUDE.md b/CLAUDE.md index 44d0546..88b7c89 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,12 +15,12 @@ L'état courant seulement ; l'historique est dans `git log` et `docs/decisions.m - **Maquettes du site (D-022, D-039)** : client « System Summary », une page par station de `data/`, un bloc par domaine mesuré dans la section Diagnostic (Energy, Storage, Cellular, Temperature) ; support « Home » (section Status, une notification par station et par domaine Orange ou Red, lien vers la vue client de la station, D-025). - **Agents LLM côté serveur (D-027)** : rapport exploratoire seulement, rien n'est construit. - **Séries optiques (D-044)** : détecter les événements externes (occlusion, pluie, turbulence) dans les déplacements et produire une courbe corrigée, la brute gardée ; cadrage (`docs/displacement/cadrage.md`) ; données reçues pour une station (D-045) : PS des Coudres, export 15 min en UTC sur 5,5 jours, sans événement annoté (buée probable le matin), et 24 images horaires de la caméra ; exploration confiée d'abord à l'agent de diagnostic (D-046), chaîne analytique au second plan. -- **Agent de diagnostic (D-046)** : pilote de l'enquête à la demande (D-042) dans Claude Code : sous-agent `diagnostic` (`.claude/agents/diagnostic.md`, dossier `agents/diagnostic/`, spec `docs/agents/agent-diagnostic.md`) ; un dossier de `data/` et une question facultative donnent un rapport court dans `agents/diagnostic/rapports/_/` : verdict, anomalies seules, chacune montrée par un graphique et des vignettes des images (D-047) ; déplacements et images seulement ; cas de référence du spécialiste : PS des Coudres est sain, seule anomalie les pics d'erreur de `REF_G` et `REF_D`. L'enquête par API (D-042) reste un document. +- **Agent de diagnostic (D-046)** : pilote de l'enquête à la demande (D-042) dans Claude Code : sous-agent `diagnostic` (`.claude/agents/diagnostic.md`, dossier `agents/diagnostic/`, spec `docs/agents/agent-diagnostic.md`) ; un dossier de `data/` et une question facultative donnent un rapport court dans `agents/diagnostic/rapports/_/` : verdict, anomalies seules, chacune montrée par un graphique et des vignettes des images (D-047) ; déplacements et images seulement ; cas de référence du spécialiste : PS des Coudres est sain, seule anomalie les pics d'erreur de `REF_G` et `REF_D` ; base de cas validés (D-048, `agents/diagnostic/cas/`), lue après les faits, vide : un cas n'y entre que sur demande explicite de l'utilisateur. L'enquête par API (D-042) reste un document. - **Storage (D-030, D-034, D-035)** : jeu de travail WEISSHORN seul (NORDEND n'a pas les mesures de `/data`) ; `DAILY_STORAGE_STATE` et `DAYS_UNTIL_STORAGE_FULL` en prototype, sans cas de l'expert ; couleur du jour codée (`src/storage/day_color.py`, matrice état × horizon `docs/storage/matrice-etat-horizon.drawio`, la pire des deux) ; seuils arbitraires (20 % / 10 % libres, 60 / 14 jours) ; questions en suspens dans `docs/storage/domaine/questions-pour-l-expert.md` ; livré en prototype (D-039) : figure du site `src/storage/final.py`, bloc de la vue client, notification support, guide `docs/storage/guide/`. - **Cellular (D-030 à D-032, D-037), en pause en attendant le spécialiste** : WEISSHORN (mise en service le 19/08, puis quelques incidents isolés) et NORDEND (109 jours, 11 coupures de la liaison) explorés ; `DAILY_LINK_STATE` et `DAILY_SIGNAL_STATE` en prototype, sans cas de l'expert ; deux corrections de `DAILY_LINK_STATE` retenues sur le principe mais non codées ; couleur du jour codée (`src/cellular/day_color.py`, matrice lien × signal `docs/cellular/matrice-lien-signal.drawio` : Red si des envois manquent et que le signal n'est pas mesuré 20 h sur 24) ; livré en prototype avant les réponses du spécialiste (D-039) : figure du site `src/cellular/final.py`, bloc de la vue client, notification support, guide `docs/cellular/guide/`. Reprise : `docs/cellular/domaine/questions-pour-l-expert.md`. - **Temperature (D-040)** : jeux de travail WEISSHORN et NORDEND (VERMONT n'a pas le GPU) ; `DAILY_GPU_TEMPERATURE_LIMIT` en prototype, sans cas de l'expert : une moyenne horaire du GPU ≥ 97,5 °C (limite du Jetson Nano, carte supposée) dans les 24 dernières heures ; couleur du jour codée (`src/temperature/day_color.py` : Red si atteinte, sinon Green, pas d'orange) ; tous les jours Green (maximum 57,2 °C) ; livré en prototype (D-041) : figure du site `src/temperature/final.py`, bloc de la vue client, notification support, guide `docs/temperature/guide/`. Constats, pistes et questions dans `docs/temperature/domaine/point-de-depart.md`. - **Dev container (D-038)** : Docker Engine dans WSL, `.devcontainer/` (Python 3.14, plotly, matplotlib, réseau de l'hôte) ; prépare la communication avec la caméra, en attente de la doc de l'API REST. -- **Prochaine étape** : `cellular` : l'utilisateur voit avec le spécialiste les questions de `docs/cellular/domaine/questions-pour-l-expert.md` (cadence des envois, articulation des deux corrections de `DAILY_LINK_STATE`, retenues mais non codées, cas annotés) ; ensuite les corrections, à reporter dans le guide ; `storage` : les réponses de l'expert (seuils, disque plein, purge, cas), puis les seuils et le guide ; `temperature` : confirmer la carte et ses seuils sur une station (question 1 de `docs/temperature/domaine/point-de-depart.md`), puis le guide si la limite change ; repérer d'autres champs à notifier ; étape 1 du rapport d'agents (pilote manuel Energy sur l'historique de VERMONT, il faut une clé API Anthropic) ; mise en forme du manuel avec le plugin Interactive Docs (dans une autre conversation) ; choisir avec l'équipe du site le format d'intégration du graphique ; maquettes : poursuivre côté client pas à pas, puis côté support (points ouverts dans D-022 et D-039) ; agent de diagnostic : l'utilisateur valide le rapport du second passage sur PS des Coudres (§7 de sa spec) et voit avec le spécialiste si les pics de `REF_G` et `REF_D` biaisent la compensation (marche de `corr_x` de BJ_G). +- **Prochaine étape** : `cellular` : l'utilisateur voit avec le spécialiste les questions de `docs/cellular/domaine/questions-pour-l-expert.md` (cadence des envois, articulation des deux corrections de `DAILY_LINK_STATE`, retenues mais non codées, cas annotés) ; ensuite les corrections, à reporter dans le guide ; `storage` : les réponses de l'expert (seuils, disque plein, purge, cas), puis les seuils et le guide ; `temperature` : confirmer la carte et ses seuils sur une station (question 1 de `docs/temperature/domaine/point-de-depart.md`), puis le guide si la limite change ; repérer d'autres champs à notifier ; étape 1 du rapport d'agents (pilote manuel Energy sur l'historique de VERMONT, il faut une clé API Anthropic) ; mise en forme du manuel avec le plugin Interactive Docs (dans une autre conversation) ; choisir avec l'équipe du site le format d'intégration du graphique ; maquettes : poursuivre côté client pas à pas, puis côté support (points ouverts dans D-022 et D-039) ; agent de diagnostic : l'utilisateur valide le rapport du second passage sur PS des Coudres (§7 de sa spec) et voit avec le spécialiste si les pics de `REF_G` et `REF_D` biaisent la compensation (marche de `corr_x` de BJ_G) ; premiers cas de la base, quand l'utilisateur les apporte et le demande. ## Analyses (domaine Energy) @@ -108,7 +108,7 @@ python3 -m venv .venv && .venv/bin/pip install plotly matplotlib # recréer . ### Fichiers - `README.md` (40 l) : point d'entrée pour un humain. -- `docs/decisions.md` (530 l, D-001 à D-047) : décisions **projet**, au format ADR allégé (statut, décision, pourquoi, options écartées, conséquence). À consulter avant de changer d'orientation ou de reproposer une option : elle a peut-être déjà été écartée. +- `docs/decisions.md` (542 l, D-001 à D-048) : décisions **projet**, au format ADR allégé (statut, décision, pourquoi, options écartées, conséquence). À consulter avant de changer d'orientation ou de reproposer une option : elle a peut-être déjà été écartée. - `docs/domaine/` : savoir métier commun, une note courte (< 50 l) par question. - `ce-que-mesure-la-station.md` : format CSV, métriques et unités, consommation mesurée mais pas l'apport. - `pieges-des-donnees.md` : trou ≠ coupure, signatures d'une coupure, seuils absolus, cycle jour/nuit. @@ -122,7 +122,7 @@ python3 -m venv .venv && .venv/bin/pip install plotly matplotlib # recréer . - `docs/temperature/` : domaine Temperature (D-040), sans matrice ; guide dans `guide/` (D-041). `domaine/point-de-depart.md` : zones thermiques, carte supposée (Jetson Nano) et ses limites, constats sur trois stations, pistes, questions au spécialiste ; fiche dans `analyses/`. - `docs/agents/rapport-exploratoire.md` (290 l) : cadre d'agents LLM (D-027) : choix retenus, architecture, démarrage par étapes (§6) ; annexe A : pistes à revoir étape par étape. Le code d'agent vit à part, dans `agents/`. - `docs/agents/enquete-a-la-demande.md` (233 l) : enquête à la demande sur un événement de mesure (D-042), même cadre ; harnais (§3), déroulé (§4), sortie et règle d'asymétrie (§5), étapes (§6), questions ouvertes (§9). -- `docs/agents/agent-diagnostic.md` : spec de l'agent de diagnostic (D-046, D-047) ; code dans `agents/diagnostic/` (`instructions.md`, `outils/`, `rapports/`, un dossier par rapport avec ses figures). Appel : `@agent-diagnostic data// [question]`, (en terminal, `claude --agent diagnostic` charge `CLAUDE.md` : pas à l'aveugle). +- `docs/agents/agent-diagnostic.md` : spec de l'agent de diagnostic (D-046 à D-048), base de cas au §11 ; code dans `agents/diagnostic/` (`instructions.md`, `outils/`, `rapports/`, un dossier par rapport avec ses figures, `cas/`, la base de cas). Appel : `@agent-diagnostic data// [question]`, (en terminal, `claude --agent diagnostic` charge `CLAUDE.md` : pas à l'aveugle). - `docs/displacement/cadrage.md` (156 l) : séries optiques (D-044) : événements externes et correction des courbes ; règles de correction (§3), chaîne en trois étapes (§4), données nécessaires (§5), étapes (§6), questions ouvertes (§7). - `docs/aimsight/` : documentation AIMsight d'origine, en anglais, non modifiée. À lire avant de concevoir, **par section** ; ne pas re-demander à l'utilisateur ce qui y figure. - `AIMsight_reference_quality_event_explainer_roadmap.md` (1 180 l) : **référence qui fait autorité** : couche diagnostique commune, explainer d'événements, classifications (§4.3), API indépendante de l'estimateur (§10). diff --git a/agents/diagnostic/README.md b/agents/diagnostic/README.md index 9b319cd..7eede77 100644 --- a/agents/diagnostic/README.md +++ b/agents/diagnostic/README.md @@ -11,13 +11,25 @@ Un sous-agent Claude Code qui diagnostique les données d'une station : il repè ## Ce qu'il rend -Un dossier par diagnostic dans `rapports/` : `rapport.md` (verdict, une section courte par anomalie avec ses figures, « Hors anomalie », annexe) et ses figures PNG ; un résumé dans la conversation. La section « Validation » du rapport est à remplir : un rapport validé deviendra un cas. +Un dossier par diagnostic dans `rapports/` : `rapport.md` (verdict, une section courte par anomalie avec ses figures, « Hors anomalie », annexe) et ses figures PNG ; un résumé dans la conversation. La section « Validation » du rapport est à remplir ; « Devient un cas : oui » y demande d'en faire un cas (ci-dessous). ## Contenu du dossier - `instructions.md` : sa méthode, ses règles et le format du rapport. C'est ici qu'on corrige son comportement. - `outils/` : `inventaire.py`, `resume.py`, `graphique.py`, `vignettes.py` (recadrage des images autour des capteurs), et `donnees.py`, la lecture commune. Ils rendent des valeurs, pas des verdicts. Le graphique et les vignettes demandent matplotlib (`.venv`). - `rapports/` : ses rapports, un dossier chacun. +- `cas/` : la base de cas validés par l'expert (D-048) : `INDEX.md`, une ligne par incident, et un dossier par incident (`cas.md` et ses figures). L'agent la lit après avoir établi ses faits. Spec : §11 de `docs/agents/agent-diagnostic.md`. + +## Ajouter un cas + +Seulement 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//` (D-029) ; l'avis de l'expert reste hors du dépôt jusqu'à l'étape 4. +2. Commiter (arbre propre : un `git status` sale a déjà fuité), puis lancer l'agent à l'aveugle sur la fenêtre de l'incident : `@agent-diagnostic data// que s'est-il passé du au (UTC) ?`. Il doit répondre « aucun cas connu » ou citer le bon cas, jamais un faux. +3. Comparer son rapport à l'avis de l'expert ; un attendu manqué se corrige dans `instructions.md`. +4. Écrire `cas/C-__/cas.md` au modèle du §11.3 de la spec (signature tirée des faits et des commandes du rapport, diagnostic de l'expert), y copier les figures du rapport, ajouter sa ligne à `cas/INDEX.md` (et retirer « Base vide pour l'instant »), commiter. + +**Rejouer un cas** : retirer sa ligne de `cas/INDEX.md` sans commiter, lancer l'agent sur sa fenêtre, comparer son rapport à « Attendu de l'agent » de la fiche, restaurer la ligne (`git checkout agents/diagnostic/cas/INDEX.md`). ## Limites diff --git a/docs/agents/agent-diagnostic.md b/docs/agents/agent-diagnostic.md index 5debbd3..5d76a0a 100644 --- a/docs/agents/agent-diagnostic.md +++ b/docs/agents/agent-diagnostic.md @@ -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/_[_]/` (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 (`
`). 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__/ 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//` (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 : + + · data// · → UTC · avis de l'expert du AAAA-MM-JJ · entré le AAAA-MM-JJ + +## Symptôme + + +## Signature +Critères observables, relatifs au niveau habituel du capteur, chacun avec sa commande : +1. : `` + +## Exclusions +Ce qui ferait que ce n'est pas ce cas : +- → plutôt + +## Diagnostic de l'expert +- **Classification** : · **Cause** : <…> · **Niveau de preuve** : <…> +- **Conséquence pour l'ouvrage** : aucune | mouvement réel | indéterminée · **Action** : aucune | à vérifier | intervention +- + +## Attendu de l'agent +- **Doit dire** : <…> +- **Ne doit pas dire** : <…> + +## Inconnus +- + +## Preuves +![](
.png) +** + +## Test à l'aveugle +/ ; 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//` ; 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/`. diff --git a/docs/decisions.md b/docs/decisions.md index 6efde6d..5af6385 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -446,7 +446,7 @@ Règles du journal : - **Conséquence** : sur les données reçues, Temperature est Green tous les jours mesurés : aucune notification support. Le panneau place les jours inconnus à 0 °C (marqueur gris), repris tel quel de la page de comparaison. ## D-042 — 2026-10-13 — Enquête à la demande : un agent qui explique un événement de mesure (exploratoire) -- **Statut** : active, exploratoire (`docs/agents/enquete-a-la-demande.md`, rien n'est construit). Complète D-027 sans la remplacer : une approche auxiliaire, plus simple, sur le même cadre. +- **Statut** : active, exploratoire (`docs/agents/enquete-a-la-demande.md`, rien n'est construit). Complète D-027 sans la remplacer : une approche auxiliaire, plus simple, sur le même cadre ; remplacée en partie par D-048 (la base de cas n'est plus chargée dans le prompt). - **Décision** : - pour les données de mesure (déplacements, compensation, références), un agent **enquête à la demande** : une session par question sur un événement, pas une surveillance quotidienne. Il suit le *support query workflow* des docs AIMsight (inventaire, bas de la chaîne d'abord, faits, hypothèses, **réfutation obligatoire de l'hypothèse principale**, conclusion) ; - **enquêteur avec des outils typés**, en lecture seule, définis par famille de preuves et non par format (sources encore inconnues) : `inventory`, `get_series`, `compare_before_after`, `common_mode`, `get_system_health` (couleurs du jour déjà livrées), `get_image` (si une source existe), et `submit_diagnosis` au format structuré des §14-15 du contexte support. Les outils de calcul renvoient des valeurs, pas des verdicts ; @@ -528,3 +528,15 @@ Règles du journal : - **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. + +## D-048 — 2026-10-14 — Agent de diagnostic : une base de cas validés, consultée après les faits +- **Statut** : active, construite le 2026-10-14 (spec : §11 de `docs/agents/agent-diagnostic.md`) ; base vide. Remplace en partie D-042 (base de cas chargée dans le prompt). +- **Décision** : + - une base de cas validés par l'expert, `agents/diagnostic/cas/` : `INDEX.md`, une ligne par incident (signature observable, classification, cause, verdict), et un dossier par incident avec sa fiche `cas.md` (symptôme, signature, exclusions, diagnostic de l'expert avec conséquence pour l'ouvrage et action en listes fermées, attendu de l'agent, inconnus, figures, test à l'aveugle) ; les données restent dans `data/` ; + - l'agent lit l'index **après** avoir établi ses faits, ouvre au plus 3 fiches par anomalie et coche critères et exclusions avec ses outils : correspondance complète, partielle ou aucune ; + - sans correspondance, il rend les faits et ses hypothèses marquées « non validé », pour le support ; + - règle d'asymétrie : « aucune conséquence pour l'ouvrage » ne sort que d'une correspondance complète ; + - un cas n'entre dans la base que sur demande explicite de l'utilisateur, après un passage de l'agent à l'aveugle comparé à l'avis de l'expert ; la base démarre vide. +- **Pourquoi** : demande de l'utilisateur : le diagnostic marche mais manque de déterminisme ; l'agent reçoit tout et peut conclure hors sujet. Usage visé : un bouton « Analyze » sur une plage sélectionnée, dont il faut contrôler la sortie. Ancrer le verdict sur des cas validés suit le §17 du contexte support (*historical cases used like software tests*). Choix de l'utilisateur sur proposition : index lu par l'agent, une fiche par incident, cas reçus avec l'avis de l'expert, hypothèses « non validé » hors cas. +- **Options écartées** : RAG vectorielle (inutile à quelques dizaines de cas ; deux cas se ressemblent par leur signature, pas par leur texte ; service d'embeddings tiers) ; fiches dans les instructions (ancrage avant les données) ; une fiche par type ; toujours le cas le plus proche (ancrage) ; faits seuls hors cas (le support repart de zéro). +- **Conséquence** : un cas est aussi un test de régression (retirer sa ligne de l'index pour le rejouer) ; filtre structuré ou RAG quand l'index ne tiendra plus en une lecture ou que la question arrivera en texte libre. diff --git a/docs/superpowers/plans/2026-10-14-base-de-cas.md b/docs/superpowers/plans/2026-10-14-base-de-cas.md new file mode 100644 index 0000000..f2e493a --- /dev/null +++ b/docs/superpowers/plans/2026-10-14-base-de-cas.md @@ -0,0 +1,440 @@ +# Base de cas de l'agent de diagnostic — plan de mise en œuvre + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Donner à l'agent de diagnostic une base de cas validés par l'expert, vide au départ, qu'il consulte après avoir établi ses faits, et vérifier qu'il fonctionne toujours avec l'index vide. + +**Architecture:** Rien que du Markdown. Un index `agents/diagnostic/cas/INDEX.md` (en-tête seulement), une nouvelle étape « Cas connus » dans `agents/diagnostic/instructions.md`, de nouveaux champs dans le format du rapport (cas connu, conséquence pour l'ouvrage, action, devient un cas), la procédure d'ajout dans le README. La vérification est un passage à l'aveugle du sous-agent `diagnostic` sur PS des Coudres. + +**Tech Stack:** Markdown ; sous-agent Claude Code `diagnostic` (outil Agent) ; git. + +**Spec:** `docs/agents/agent-diagnostic.md` §11 ; décision D-048 dans `docs/decisions.md`. + +## Global Constraints + +- Aucun script, aucun code : la base est du Markdown (§11.8 : pas de `cas.py`, pas de RAG). +- La base démarre vide. **Aucun cas n'est créé** (pas de C-001, même pour PS des Coudres) : un cas n'entre que sur demande explicite de l'utilisateur (§11.6). +- Ne pas modifier `.claude/agents/diagnostic.md` : un changement exigerait une nouvelle session pour que le sous-agent le charge. +- Documents en français ; termes AIMsight en anglais ; toute heure en UTC. +- Pas de tests automatisés (D-008) : la vérification est le passage de l'agent (Task 3) et des `grep`. +- Corps du rapport ~40 lignes (D-047) : les ajouts au format ne prennent qu'une ligne par anomalie. +- `CLAUDE.md` reste sous 200 lignes ; il en a 199 : modifier des lignes existantes, n'en ajouter aucune. +- Messages de commit en anglais, terminés par `Co-Authored-By: Claude Opus 5.5 `. + +## Review Focus + +Aucun cas n'existe : la correspondance ne peut pas être exercée avant le premier cas (son passage à l'aveugle, §11.6 étape 2, en sera le premier test). Le relecteur vérifie donc dans le texte des instructions : + +1. **Ordre** : l'index n'est lu qu'à l'étape 5, après les faits ; les sources (§2) le disent aussi. Une lecture plus tôt ancrerait l'agent. +2. **Index vide** : il donne « aucun cas connu (index vide) », conséquence « indéterminée », hypothèses « Non validé (support) », et non une erreur ou un abandon (exercé par Task 3). +3. **Asymétrie** : « aucune » conséquence pour l'ouvrage seulement avec une correspondance complète ; en partielle, « aucune » devient « indéterminée » mais « mouvement réel » reste. +4. **Deux cas complets pour une anomalie** : garder celui qui a le plus de critères vérifiés, citer l'autre. +5. **Fiche hors index** : l'agent n'ouvre une fiche que si l'index la cite (le rejeu d'un cas retire sa ligne). + +--- + +### Task 1: Base vide et instructions de l'agent + +**Files:** +- Create: `agents/diagnostic/cas/INDEX.md` +- Modify: `agents/diagnostic/instructions.md` (§2 sources, §4 déroulé, §5 règles, §6 format du rapport, §7 réponse) + +**Interfaces:** +- Produces : le chemin `agents/diagnostic/cas/INDEX.md` ; les colonnes de l'index `Cas | Station · fenêtre (UTC) | Signature | Classification | Cause (expert) | Verdict expert` ; les champs du rapport `**Cas connu**`, `**Conséquence pour l'ouvrage**`, `**Action**`, `**Devient un cas**` ; le préfixe `**Non validé (support)** :`. Task 2 et Task 3 les citent à l'identique. + +- [ ] **Step 1: Créer `agents/diagnostic/cas/INDEX.md`** + +```markdown +# Cas connus + +Incidents validés par l'expert, un par ligne. La **Signature** résume ce qu'on observe : type de capteurs, combien, colonne, forme, moment, durée, retour à la normale. Ouvre la fiche d'un cas proche par son lien ; ses critères et ses exclusions se vérifient avec tes outils, sur tes données. + +| Cas | Station · fenêtre (UTC) | Signature | Classification | Cause (expert) | Verdict expert | +|---|---|---|---|---|---| + +*Base vide pour l'instant.* +``` + +- [ ] **Step 2: §2 des instructions, les sources** + +Dans `agents/diagnostic/instructions.md`, après la ligne qui commence par `` - `docs/aimsight/AIMsight FAQ.pdf`, pour `error` `` (dernière puce de la liste « Seulement : »), ajouter la puce : + +```markdown +- à l'étape 5 du déroulé (§4) seulement, jamais avant : `agents/diagnostic/cas/INDEX.md`, puis les fiches `cas.md` qu'il cite et leurs figures. Ce sont des incidents validés par l'expert. +``` + +Dans le paragraphe **Ne lis rien d'autre**, remplacer : + +```markdown +ni les rapports de `agents/diagnostic/rapports/`. +``` + +par : + +```markdown +ni les rapports de `agents/diagnostic/rapports/`, ni une fiche de `agents/diagnostic/cas/` que l'index ne cite pas. +``` + +- [ ] **Step 3: §4 des instructions, l'étape « Cas connus »** + +Remplacer : + +```markdown +5. **Hypothèses** : prends-les dans les familles de la section 12 du contexte support, plus le mouvement réel de l'ouvrage. Pour chacune, ce qui la soutient et ce qui la contredit. +6. **Réfutation obligatoire** +``` + +par : + +```markdown +5. **Cas connus**, après les faits, jamais avant : sinon tu chercherais ce que dit le cas au lieu de ce que montrent les données. + - Lis `agents/diagnostic/cas/INDEX.md`. Pour chaque anomalie, choisis au plus 3 cas dont la signature est proche de tes faits et ouvre leurs fiches. + - Vérifie chaque critère de la signature et chaque exclusion de la fiche sur **tes** données, avec tes outils : vérifié, contredit ou non vérifiable (donnée absente). + - Conclus, par anomalie : + + | Correspondance | Quand | Suite | + |---|---|---| + | **complète** | tous les critères vérifiés, aucune exclusion observée | le diagnostic de l'expert (classification, cause, conséquence, action) est ton hypothèse principale | + | **partielle** | aucun critère contredit, certains non vérifiables | même hypothèse principale ; niveau de preuve au plus `consistent with` ; conséquence « aucune » ramenée à « indéterminée » (« mouvement réel » reste) ; les critères non vérifiables vont en « à vérifier » | + | **aucune** | pour chaque cas ouvert, un critère contredit ou une exclusion observée ; ou index vide | tes propres hypothèses (étape 6), marquées « Non validé (support) » ; conséquence « indéterminée » | + + - Si deux cas correspondent, garde celui qui a le plus de critères vérifiés et cite l'autre. +6. **Hypothèses** : avec un cas (correspondance complète ou partielle), l'hypothèse principale est son diagnostic ; ajoute les alternatives que tes faits n'écartent pas. Sans cas, prends-les dans les familles de la section 12 du contexte support, plus le mouvement réel de l'ouvrage. Pour chacune, ce qui la soutient et ce qui la contredit. +7. **Réfutation obligatoire** +``` + +Puis renuméroter les deux étapes suivantes : `7. **Preuves**` devient `8. **Preuves**`, `8. **Rapport** (§6), puis ta réponse (§7).` devient `9. **Rapport** (§6), puis ta réponse (§7).` + +- [ ] **Step 4: §5 des instructions, la règle d'asymétrie** + +Après la ligne `- « Rien d'anormal » est une conclusion valable.`, ajouter : + +```markdown +- **Asymétrie** : « Conséquence pour l'ouvrage : aucune » seulement avec une correspondance complète à un cas (étape 5). Sinon « indéterminée », ou « mouvement réel » si tes preuves l'établissent. Une fausse assurance coûte plus qu'une fausse alerte. +``` + +- [ ] **Step 5: §6 des instructions, le format du rapport** + +Dans le gabarit, remplacer : + +```markdown +<2-3 phrases : la station fonctionne-t-elle normalement ? Les anomalies, par importance, une ligne chacune. Ou : aucune anomalie.> +``` + +par : + +```markdown +<2-3 phrases : la station fonctionne-t-elle normalement ? Les anomalies, par importance, une ligne chacune, avec le cas connu qui leur correspond. Ou : aucune anomalie.> +``` + +Remplacer la ligne de classification : + +```markdown +- **Classification** : · **Niveau de preuve** : … · **Cause probable** : +``` + +par : + +```markdown +- **Cas connu** : ) | aucun cas connu ( ou index vide)> +- **Classification** : · **Niveau de preuve** : … · **Cause probable** : · **Conséquence pour l'ouvrage** : · **Action** : . Sans cas connu, la ligne commence par « **Non validé (support)** : ». +``` + +Dans le bloc « Validation », après `- **Diagnostic final** :`, ajouter : + +```markdown +- **Devient un cas** : oui (C-xxx) | non +``` + +- [ ] **Step 6: §7 des instructions, la réponse** + +Remplacer : + +```markdown +le verdict, les anomalies (classification, niveau de preuve), le chemin du rapport. +``` + +par : + +```markdown +le verdict, les anomalies (cas connu, classification, niveau de preuve, conséquence pour l'ouvrage), le chemin du rapport. +``` + +- [ ] **Step 7: Vérifier la cohérence** + +Run: `grep -n -E '^[0-9]\. \*\*|étape [0-9]|INDEX.md|Cas connu|Devient un cas|Non validé|Asymétrie' agents/diagnostic/instructions.md` +Expected : les étapes numérotées 1 à 9 sans doublon ; « étape 5 » dans §2, §4 et §5 désigne bien « Cas connus » ; « étape 6 » désigne « Hypothèses » ; `INDEX.md` en §2 et §4 ; `Cas connu`, `Non validé (support)` et `Devient un cas` dans le gabarit. + +Run: `grep -n '§4\|§6\|§7' agents/diagnostic/instructions.md` +Expected : les renvois internes (§6 rapport, §7 réponse) restent justes après la renumérotation des étapes (seules les étapes changent, pas les sections). + +- [ ] **Step 8: Commit** + +```bash +git add agents/diagnostic/cas/INDEX.md agents/diagnostic/instructions.md +git commit -m "$(cat <<'EOF' +Add the empty case base and the known-cases step to the diagnostic agent (D-048) + +Co-Authored-By: Claude Opus 5.5 +EOF +)" +``` + +--- + +### Task 2: Documentation (README, spec, D-048, CLAUDE.md) + +**Files:** +- Modify: `agents/diagnostic/README.md` +- Modify: `docs/agents/agent-diagnostic.md` (en-tête, §4, §5) +- Modify: `docs/decisions.md` (statut de D-048) +- Modify: `CLAUDE.md` (état, prochaine étape, carte) + +**Interfaces:** +- Consumes : les noms de Task 1 (`agents/diagnostic/cas/INDEX.md`, champs `Cas connu`, `Conséquence pour l'ouvrage`, `Action`, `Devient un cas`, `Non validé (support)`). + +- [ ] **Step 1: README, ce qu'il rend** + +Dans `agents/diagnostic/README.md`, remplacer : + +```markdown +La section « Validation » du rapport est à remplir : un rapport validé deviendra un cas. +``` + +par : + +```markdown +La section « Validation » du rapport est à remplir ; « Devient un cas : oui » y demande d'en faire un cas (ci-dessous). +``` + +- [ ] **Step 2: README, contenu du dossier** + +Après la puce `` - `rapports/` : ses rapports, un dossier chacun. ``, ajouter : + +```markdown +- `cas/` : la base de cas validés par l'expert (D-048) : `INDEX.md`, une ligne par incident, et un dossier par incident (`cas.md` et ses figures). L'agent la lit après avoir établi ses faits. Spec : §11 de `docs/agents/agent-diagnostic.md`. +``` + +- [ ] **Step 3: README, ajouter un cas** + +Avant la section `## Limites`, ajouter : + +```markdown +## Ajouter un cas + +Seulement 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//` (D-029) ; l'avis de l'expert reste hors du dépôt jusqu'à l'étape 4. +2. Commiter (arbre propre : un `git status` sale a déjà fuité), puis lancer l'agent à l'aveugle sur la fenêtre de l'incident : `@agent-diagnostic data// que s'est-il passé du au (UTC) ?`. Il doit répondre « aucun cas connu » ou citer le bon cas, jamais un faux. +3. Comparer son rapport à l'avis de l'expert ; un attendu manqué se corrige dans `instructions.md`. +4. Écrire `cas/C-__/cas.md` au modèle du §11.3 de la spec (signature tirée des faits et des commandes du rapport, diagnostic de l'expert), y copier les figures du rapport, ajouter sa ligne à `cas/INDEX.md` (et retirer « Base vide pour l'instant »), commiter. + +**Rejouer un cas** : retirer sa ligne de `cas/INDEX.md` sans commiter, lancer l'agent sur sa fenêtre, comparer son rapport à « Attendu de l'agent » de la fiche, restaurer la ligne (`git checkout agents/diagnostic/cas/INDEX.md`). +``` + +- [ ] **Step 4: Spec, en-tête** + +Dans `docs/agents/agent-diagnostic.md`, remplacer : + +```markdown +base de cas conçue le 2026-10-14 (D-048, §11), non construite. +``` + +par : + +```markdown +base de cas construite le 2026-10-14 (D-048, §11), vide. +``` + +- [ ] **Step 5: Spec §4, sources, déroulé et règles** + +Après la ligne 74 (`- les docs AIMsight, par section : …` qui finit par `la FAQ pour `error` (`pdftotext`).`), ajouter : + +```markdown +- la base de cas, `agents/diagnostic/cas/` (§11), à l'étape 5 seulement. +``` + +Remplacer : + +```markdown +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** : +``` + +par : + +```markdown +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** : +``` + +et `8. **Rapport** (§5).` par `9. **Rapport** (§5).` + +Après `- « rien d'anormal » est une conclusion valable ;`, ajouter : + +```markdown +- asymétrie : « aucune conséquence pour l'ouvrage » seulement avec une correspondance complète à un cas (§11.4) ; +``` + +- [ ] **Step 6: Spec §5, le rapport** + +Remplacer : + +```markdown +2. **Verdict** : 2-3 phrases ; la station fonctionne-t-elle normalement, et ses anomalies par importance. +``` + +par : + +```markdown +2. **Verdict** : 2-3 phrases ; la station fonctionne-t-elle normalement, et ses anomalies par importance, avec leur cas connu. +``` + +Avant la puce ` - une ligne : **classification** (liste fermée : …`, ajouter : + +```markdown + - une ligne **cas connu** : le cas et sa correspondance (complète, partielle, aucune), §11.4 ; +``` + +Dans la puce de classification, remplacer `**cause probable** (buée ou eau, occlusion, turbulence, éclairage, inconnue) ;` par `**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) » ;`. + +Remplacer : + +```markdown +6. **Validation**, laissée vide pour l'utilisateur : accepté tel quel ou corrigé (en quoi), diagnostic final. Un rapport validé deviendra un cas. +``` + +par : + +```markdown +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). +``` + +- [ ] **Step 7: D-048, statut** + +Dans `docs/decisions.md`, remplacer : + +```markdown +- **Statut** : active, conçue (spec : §11 de `docs/agents/agent-diagnostic.md`) ; rien n'est construit. Remplace en partie D-042 (base de cas chargée dans le prompt). +``` + +par : + +```markdown +- **Statut** : active, construite le 2026-10-14 (spec : §11 de `docs/agents/agent-diagnostic.md`) ; base vide. Remplace en partie D-042 (base de cas chargée dans le prompt). +``` + +- [ ] **Step 8: CLAUDE.md, sans ajouter de ligne** + +Remplacer, dans la puce « Agent de diagnostic (D-046) » de l'état : + +```markdown +cas de référence du spécialiste : PS des Coudres est sain, seule anomalie les pics d'erreur de `REF_G` et `REF_D`. L'enquête par API (D-042) reste un document. +``` + +par : + +```markdown +cas de référence du spécialiste : PS des Coudres est sain, seule anomalie les pics d'erreur de `REF_G` et `REF_D` ; base de cas validés (D-048, `agents/diagnostic/cas/`), lue après les faits, vide : un cas n'y entre que sur demande explicite de l'utilisateur. L'enquête par API (D-042) reste un document. +``` + +Dans la prochaine étape, remplacer : + +```markdown +(marche de `corr_x` de BJ_G). +``` + +par : + +```markdown +(marche de `corr_x` de BJ_G) ; premiers cas de la base, quand l'utilisateur les apporte et le demande. +``` + +Remplacer `` - `docs/decisions.md` (530 l, D-001 à D-047) `` par `` - `docs/decisions.md` (542 l, D-001 à D-048) ``. + +Remplacer : + +```markdown +spec de l'agent de diagnostic (D-046, D-047) ; code dans `agents/diagnostic/` (`instructions.md`, `outils/`, `rapports/`, un dossier par rapport avec ses figures). +``` + +par : + +```markdown +spec de l'agent de diagnostic (D-046 à D-048), base de cas au §11 ; code dans `agents/diagnostic/` (`instructions.md`, `outils/`, `rapports/`, un dossier par rapport avec ses figures, `cas/`, la base de cas). +``` + +- [ ] **Step 9: Vérifier** + +Run: `wc -l CLAUDE.md docs/decisions.md && grep -n -E '^[0-9]\. \*\*' docs/agents/agent-diagnostic.md | sed -n '1,12p' && grep -c 'Ajouter un cas' agents/diagnostic/README.md` +Expected : `CLAUDE.md` à 199 lignes ; le compte de `docs/decisions.md` cité dans `CLAUDE.md` (542) corrigé à la valeur réelle si elle diffère ; étapes du §4 de la spec numérotées 1 à 9 ; `1` pour le README. + +- [ ] **Step 10: Commit** + +```bash +git add agents/diagnostic/README.md docs/agents/agent-diagnostic.md docs/decisions.md CLAUDE.md docs/superpowers/plans/2026-10-14-base-de-cas.md +git commit -m "$(cat <<'EOF' +Document the diagnostic agent case base: spec, D-048, README and CLAUDE.md + +Co-Authored-By: Claude Opus 5.5 +EOF +)" +``` + +--- + +### Task 3: Vérification à l'aveugle, index vide (§11.7) + +**Files:** +- Create: `agents/diagnostic/rapports/_PS_DES_COUDRES/` (écrit par l'agent) +- Modify: `docs/agents/agent-diagnostic.md` (§11.7 : résultat) + +**Interfaces:** +- Consumes : Task 1 (instructions, index vide) et Task 2 commités : l'arbre doit être propre. + +- [ ] **Step 1: Arbre propre** + +Run: `git status --short` +Expected : aucune ligne. Sinon, commiter d'abord : le sous-agent reçoit le `git status` et un nom de fichier peut trahir une conclusion (§7). + +- [ ] **Step 2: Lancer l'agent** + +Outil Agent, `subagent_type: diagnostic`, premier plan (`run_in_background: false`), prompt réduit au dossier, sans question ni contexte : + +``` +data/PS_DES_COUDRES/ +``` + +- [ ] **Step 3: Vérifier les attendus de §11.7** + +Lire le `rapport.md` produit et cocher : + +1. le même diagnostic que le deuxième passage (§7) : une seule anomalie, `REF_G` et `REF_D` les deux nuits, figures dans le dossier du rapport ; +2. la ligne `**Cas connu** : aucun cas connu (index vide)` ; +3. la ligne de classification commence par « **Non validé (support)** : » et donne `**Conséquence pour l'ouvrage** : indéterminée` et une `**Action**` ; +4. « Sources lues » cite `agents/diagnostic/cas/INDEX.md` et aucune fiche ni aucun rapport ; +5. la validation contient `**Devient un cas** : oui (C-xxx) | non`, laissée vide ; +6. le corps (jusqu'à « Hors anomalie » compris) en ~40 lignes : `sed -n '/^## Verdict/,/^## Annexe/p' | wc -l`. + +Ordre de lecture (attendu : `INDEX.md` après les premiers `resume.py`) : chercher la transcription du sous-agent, `ls -t ~/.claude/projects/-home-maxime-Support-Agent/*/subagents/*.jsonl | head -1`, puis `grep -n -o -E 'resume.py|cas/INDEX.md' | head`. Si elle est introuvable, le noter comme non vérifié. + +Un attendu manqué : corriger `agents/diagnostic/instructions.md`, commiter, relancer (Step 1). + +- [ ] **Step 4: Consigner le résultat** + +À la fin du §11.7 de `docs/agents/agent-diagnostic.md`, ajouter un paragraphe `**Mise en place, le 2026-10-14 (index vide).**` : chemin du rapport, appels d'outils, durée et tokens (rendus par l'outil Agent), puis un tableau `| Attendu | Résultat |` avec les six attendus du Step 3 et l'ordre de lecture, chacun « atteint » ou « manqué » avec le fait qui le montre, et les corrections faites aux instructions s'il y en a. + +- [ ] **Step 5: Commit** + +```bash +git add agents/diagnostic/rapports/ docs/agents/agent-diagnostic.md agents/diagnostic/instructions.md +git commit -m "$(cat <<'EOF' +Run the diagnostic agent blind with an empty case base and record the results + +Co-Authored-By: Claude Opus 5.5 +EOF +)" +```