Files
Support-Agent/CLAUDE.md
T
maximeandClaude Opus 5.5 56b93e9b82 Agent tools: reading tools moved to agent-tools/ (D-081)
The reading tools leave agents/diagnostic/outils/ for a root folder of their
own; paths updated in skills, agents, detectors, scripts, case fiches,
support/, contexts and CLAUDE.md; graphique, vignettes and gif find the repo
root one level up; history keeps old paths.

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

38 KiB
Raw Blame History

CLAUDE.md

Ce fichier est une carte du projet, chargée à chaque session : il dit ce qui existe et où, pas le détail. Il reste court (< 200 lignes, D-012). Le reste se lit à la demande, et seulement la partie utile (voir « Lire sans saturer le contexte »).

Projet

Agent de diagnostic proactif pour AIMsight, un système de surveillance optique de déplacements : une caméra suit des cibles (prismes, réflecteurs) sur un ouvrage, et le mouvement de la caméra est compensé grâce à des cibles de référence. L'agent analyse les séries temporelles avec des méthodes analytiques (pas de LLM), complétées à l'étude par une couche d'agents LLM côté serveur (D-027), détecte les anomalies et explique chacune d'elles (preuves calculées + ce qui reste non établi) avant que le client ne pose la question. Cible d'exécution idéale : le système embarqué de la station. Langage : Python.

État et prochaine étape (au 2026-10-24)

  • Energy, livré (prototype, D-020, D-043) : DAILY_BATTERY_STATE et DAILY_BATTERY_TREND, combinées par la matrice état × tendance en une couleur par jour (vert / orange / rouge, gris si inconnu) ; sur secteur (DAILY_POWER_SOURCE), la perte du secteur décide à la place de la matrice (rouge dès une heure < 13,4 V), statut On mains / Not on mains dans la notification du support et dans l'en-tête du bloc Energy de la vue client. Une figure Plotly pour le site (D-021 ; la matrice est codée mais pas tracée), un focus sur un jour et sa veille (D-024), un manuel en brouillon. Comparaison seulement : les deux moyennes glissantes sur 7 jours ; point ouvert : l'accoutumance après ~30 jours de déficit (fiche moving_average_7_days_drop).
  • 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 (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, puis NORDEND, WILDSTRUBEL, CLARIDEN et NIEDERHORN, chacune devenue un cas de la base ; CLARIDEN est l'incident de Barcelone de la doc AIMsight, où l'expert voit un mouvement réel de l'ouvrage, la doc une instabilité des références (docs/displacement/domaine/incident-de-barcelone.md) ; deux rapports d'analyse AIMsight (murs GN-1.472 et GN-5.054), causes des déplacements apparents selon l'expert, sans leurs données ; exploration confiée d'abord à l'agent de diagnostic (D-046), chaîne analytique au second plan.
  • Agent de diagnostic (D-046, révisé par D-058) : pilote de l'enquête à la demande (D-042) dans Claude Code, appelé pour un cas précis que les détecteurs n'expliquent pas ; plus à l'aveugle : il lit la connaissance du projet et part des événements des détecteurs du journal, sans les juger, et n'ajoute aucun cas ; 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/<date>_<STATION>/ : 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, events/), lue après les faits : cinq cas, C-001 à C-005 (l'index events/INDEX.md en est le registre), chaque cas avec ses données, la station au numéro du cas et les capteurs codés (D-049, D-050, skill anonymiser-cas), une fiche courte sur ce seul cas, lisible d'abord par un humain (D-051) ; un cas n'y entre que par /nouveau-cas, lancé par l'utilisateur, ou par le builder de la boucle (D-057), puis revu par l'utilisateur avec /revue-cas (D-075, agent revue). Ses outils et leur mode d'emploi, partagés avec l'analyste de la boucle : skill lire-les-donnees, aiguisé par /aiguiser (D-059, lancé par l'utilisateur seul ; spec vues-deplacements/contexte/aiguiser-la-lecture.md). L'enquête par API (D-042) reste un document.
  • Support-agent (D-079) : skill /support <mail>, lancé par l'utilisateur, dans la conversation : répond à la question d'un client sur un système, et à elle seule (le reste en note pour l'utilisateur), à partir des données locales de data/ (station ou données absentes : il demande) ; un dossier par demande, support/<date>_<STATION>_<sujet>/ (demande.md, analyse.md, reponse.md, le mail prêt à envoyer, GIF des images par agent-tools/gif.py), peaufiné avec l'utilisateur puis commité ; versionné, base de cas de support (usage à rediscuter) ; premier cas : LENZSPITZE, nuit du 26 au 27.10 ; design docs/superpowers/specs/2026-10-28-support-agent-design.md.
  • 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.
  • Journal du matin (D-056), le cap actuel : retour au simple, côté support : une anomalie de déplacement est tout ce qui rend les courbes non plates : presque toujours sans gravité, un moment où il ne faut pas se fier aux données (pluie, buée, train, toile d'araignée, turbulence…), parfois grave, un vrai mouvement (Barcelone : la voûte du pont s'affaisse) ; onglet Journal de la maquette Explore : courbes nettoyées en mm (px au choix), la brute en gris dans les zones à ignorer, frise « What happened » dépliable par catégorie, journal en cartes aux phrases catégoriques, bouton ▶ Images ; un détecteur élémentaire par fichier dans vues-deplacements/detectors/ (visibilite, sauts, thermique, turbulence, trous, degradee, contrat detect(mesures)), réglés sur les cas C-001 à C-005, classés en onze catégories par categories.py (aussi outil de tri en lot, toujours 3 jours d'historique) ; prototypé dans Support-Agent ; contexte dans vues-deplacements/contexte/ (brainstorming journal-du-matin.md, seuils, lissage, données et boucle), carte des événements events/carte-des-evenements.md ; pompage extraction/pomper.py (métriques système, déplacements et images, un fichier par jour, relance sans re-télécharger ; lecture seule, lancé une fois par l'utilisateur le 2026-10-26, NORDEND sur 2 jours, identique aux exports reçus ; sortie dans data/, hors de git, D-065 ; application de référence : ~/monitoring-dashboard) ; boucle automatique /boucle <dossier> (D-057, construite, fonctionnement validé ; lancée par l'utilisateur seul, lot par lot, sur de nouvelles données) : analyste, upgrader, validateur et builder, lot après lot, tout commité directement sur master (D-070), chaque lot laissant les étiquettes de l'analyste, etiquettes.json, labels d'un futur modèle appris (D-061), et le score des détecteurs face à toutes les étiquettes, mesure par mesure, qui juge chaque modification (.claude/skills/boucle/score.py, D-062), et une page de fin de séance, l'analyste face aux détecteurs sur toute la plage (comparaison.py, D-066), et un benchmark des détecteurs sur la base de cas, chacun avec son diagnostic figé, versionné dans un historique (benchmark.py, D-069) (spec vues-deplacements/contexte/boucle-automatique.md) ; tout le suivi est dans le plan docs/superpowers/plans/2026-10-23-journal-du-matin.md.
  • Prochaine étape : journal du matin (D-056) : les points du plan encore en attente (pompage, première séance de la boucle par l'utilisateur, test « Claude verrait la même chose », portage), sur les consignes de l'utilisateur, dans d'autres conversations ; un point validé n'est plus repris ; ensuite, déplacements (D-052 à D-055) : détection mécanique des anomalies (D-055) : onglet Displacements de la maquette Explore, les sauts (brutaux et qui durent, retours compris) et les tendances (dérive lente et régulière), ce que regarde le client ; le survol d'une ligne les montre sur les courbes, échelle fixe (2026-10-19) ; très expérimental, seuils provisoires, sur NORDEND seuls PR17 et PR06 les passent, nettement (vues-deplacements/contexte/detection-d-anomalies.md) ; suite : la suite des retours de l'utilisateur, puis les pistes notées (accélération, cible qui se sépare de ses voisines) ; maquette de la page Explore (vues-deplacements/maquette/, cas NORDEND, D-054) : onglet View pour les images (glisseur, comparaison à ±24 h, error_value sur chaque capteur, gros plan des cibles avec les images d'avant et d'après), onglet Diagnosis pour les données (déplacements en mm et error_value des cibles choisies sur une plage, demande à l'agent composée sans être lancée) ; vérifiée par captures, clics à essayer, état dans vues-deplacements/maquette/spec.md ; cas NORDEND laissé là le 2026-10-16, PR17 sans explication claire (vues-deplacements/cas/2026-10_NORDEND/parcours.md) ; suite, à la demande de l'utilisateur : la sortie de l'agent dans la page, les annotations d'épisodes (à croiser avec l'agent), d'autres cas ; 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 : ses outils propres, pour plus de précision (dans une autre conversation), et l'utilisateur valide le rapport du second passage sur PS des Coudres (§7 de sa spec) ; d'autres cas de la base, quand l'utilisateur les apporte et le demande.

Analyses (domaine Energy)

Code dans src/energy/, fiche dans docs/energy/analyses/<règle en minuscules>.md.

Règle Question Statut Code
DAILY_BATTERY_STATE Chaque jour : pleine charge, charge partielle (incertain), sous le plateau ou aucune charge ? livrée (prototype, D-020) battery_state.py
DAILY_BATTERY_TREND Chaque jour, face à la veille : mieux, stable ou pire (changement d'état, sinon écart de fin de nuit) ? livrée (prototype, D-020) battery_trend.py
MOVING_AVERAGE_7_DAYS_DROP La tension moyenne sur 7 jours décroche-t-elle de son propre passé récent (> 0,2 V) ? comparaison : ~2,7 jours d'avance sur la première coupure de VERMONT, mais bruitée (pire cas sain −0,16 V) moving_average.py
MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP Même question, sur la seule mesure de 00:00 UTC de chaque jour comparaison : peu bruitée (−0,04 V), mais 1 h d'avance seulement moving_average.py
DAILY_POWER_SOURCE Chaque jour : sur secteur (moyenne des 3 jours avant J ≥ 14,0 V) ? Si oui, une heure de J < 13,4 V (perte du secteur) ? livrée (prototype, D-043) ; vérifiée sur WEISSHORN, NORDEND et MISSISSIPPI (historique git) power_source.py
  • Couleur du jour : src/energy/day_color.py (MATRIX, focus() pour J−1 / J), transcription de docs/energy/matrice-etat-tendance.drawio.
  • Travailler sur une analyse : .claude/rules/analyses.md (contrat run(series), calcul causal, constantes sourcées, graphiques, fiche à jour) se charge seul dès qu'on touche src/ ou docs/*/analyses/.
  • Créer une analyse : skill nouvelle-analyse.
  • Créer un domaine (une nouvelle notification) : skill nouveau-domaine (D-030).

Analyses (domaine Cellular)

Code dans src/cellular/, fiche dans docs/cellular/analyses/<règle en minuscules>.md, page de comparaison src/cellular/all_analyses.py (WEISSHORN et NORDEND, D-032).

Règle Question Statut Code
DAILY_LINK_STATE Chaque jour : tous les envois arrivés avec link = up, un lien signalé down, ou des envois ou messages manquants ? prototype (D-031) link_state.py
DAILY_SIGNAL_STATE Chaque jour : médianes du RSRP et du RSRQ sur la grille publiée (excellent, bon, moyen, limite de cellule) prototype (D-031) signal_state.py
  • Couleur du jour : src/cellular/day_color.py (MATRIX[lien][signal], HEADLINE), transcription de docs/cellular/matrice-lien-signal.drawio (D-037).
  • Livré (D-039) : figure du site src/cellular/final.py (panneaux partagés avec la page de comparaison), guide docs/cellular/guide/diagnostic-cellulaire.md.

Analyses (domaine Storage)

Code dans src/storage/, fiche dans docs/storage/analyses/<règle en minuscules>.md, page de comparaison src/storage/all_analyses.py (WEISSHORN, D-034).

Règle Question Statut Code
DAILY_STORAGE_STATE Chaque jour : espace libre de /data en % de l'utilisable, OK, LOW ou CRITICAL (planchers arbitraires 20 % / 10 %) ? prototype (D-034) storage_state.py
DAYS_UNTIL_STORAGE_FULL Chaque jour : dans combien de jours le disque sera-t-il plein, au rythme médian des 7 derniers jours ? prototype (D-034) days_until_full.py
  • Couleur du jour : src/storage/day_color.py (MATRIX[état][horizon], HEADLINE), transcription de docs/storage/matrice-etat-horizon.drawio (D-035).
  • Livré (D-039) : figure du site src/storage/final.py (panneaux partagés avec la page de comparaison), guide docs/storage/guide/diagnostic-stockage.md.

Analyses (domaine Temperature)

Code dans src/temperature/, fiche dans docs/temperature/analyses/<règle en minuscules>.md, page de comparaison src/temperature/all_analyses.py (WEISSHORN et NORDEND, D-040).

Règle Question Statut Code
DAILY_GPU_TEMPERATURE_LIMIT Chaque jour : une moyenne horaire du GPU a-t-elle atteint 97,5 °C (limite du constructeur) dans les 24 dernières heures ? prototype (D-040) gpu_temperature_limit.py
  • Couleur du jour : src/temperature/day_color.py (COLOR, HEADLINE) : Red si la limite est atteinte, Green sinon, sans matrice (D-040).
  • Livré (D-041) : figure du site src/temperature/final.py (panneau partagé avec la page de comparaison), guide docs/temperature/guide/diagnostic-temperature.md.

Commandes

python3 src/energy/final.py [données]                    # livré : out/<STATION>_daily.html + .json (figure du site, D-021)
python3 src/energy/all_analyses.py [données]             # les 5 analyses comparées (D-016) : out/<STATION>_energy.html
python3 src/energy/focus_jour.py JJ.MM[.AAAA] [données]  # un jour et sa veille (D-024) : faits + out/<STATION>_focus_<AAAA-MM-JJ>.html + .json
python3 src/cellular/final.py [données]                 # livré : out/<STATION>_cellular_daily.html + .json (défaut data/WEISSHORN/ et data/NORDEND/)
python3 src/cellular/all_analyses.py [données]          # analyses 4G comparées : out/<STATION>_cellular.html (même défaut)
python3 src/storage/final.py [données]                  # livré : out/<STATION>_storage_daily.html + .json (défaut data/WEISSHORN/)
python3 src/storage/all_analyses.py [données]           # analyses disque comparées : out/<STATION>_storage.html (même défaut)
python3 src/temperature/final.py [données]              # livré : out/<STATION>_temperature_daily.html + .json (défaut data/WEISSHORN/ et data/NORDEND/)
python3 src/temperature/all_analyses.py [données]       # limite du GPU : out/<STATION>_temperature.html (même défaut)
python3 maquettes/user/summary.py [début] [fin]          # maquette client : out/maquette_user_<STATION>.html, une page par station de data/
python3 maquettes/support/home.py [début] [fin]          # maquette support : out/maquette_support_home.html
python3 vues-deplacements/maquette/explore.py [dossier]  # maquette Explore, onglets View, Diagnosis (D-054), Displacements (D-055) et Journal (D-056, un détecteur seul : `python3 vues-deplacements/detectors/<détecteur>.py <dossier>`) : out/vues_deplacements_<STATION>.html (défaut : cas NORDEND, `vues_deplacements_2026-10_NORDEND.html`)
pdftotext -layout "docs/aimsight/<fichier>.pdf" -        # lire un PDF AIMsight
python3 -m venv .venv && .venv/bin/pip install plotly matplotlib    # recréer .venv
  • [données] : CSV ou dossiers, défaut data/VERMONT/. Dates des maquettes en AAAA-MM-JJ, défaut 2026-09-18 à 2026-09-28 ; la maquette support mène aux maquettes client : les lancer avec les mêmes dates (2026-08-12 2026-08-22 montre des notifications Cellular).
  • Chaque script bascule seul sur .venv si plotly manque, puis ouvre sa page (navigateur Windows via explorer.exe sous WSL).
  • Vérifier un changement : pas de tests automatisés (D-008). Lancer all_analyses.py, et final.py pour le livré, sur le jeu de travail du domaine.

Carte du dépôt

Lire sans saturer le contexte

  • Fichier long (tailles en lignes ci-dessous) : lire son plan (grep -n '^#' <fichier>), puis la seule section utile (Read avec offset et limit).
  • docs/decisions.md : l'index est grep -n '^## D-' docs/decisions.md ; lire ensuite l'entrée citée seulement. Son Statut dit si elle est remplacée.
  • CSV de data/ : les explorer par script (common.stations.load_stations), jamais en les affichant.
  • Ne pas lire : docs/superpowers/ (historique, sauf le plan vivant plans/2026-10-23-journal-du-matin.md), out/ (sorties générées), .venv/.

Fichiers

  • Handoff.md (~150 l) : cadrage du product owner (reçu le 2026-10-25) : sous-projet G, santé des sites et notifications au client (domaines de mesure, étiquette de responsabilité, « consistent with », traductions, sécurité de production). À lire avant de concevoir côté client ou notifications, par section ; sa dernière section liste les écarts constatés avec ce dépôt, à arbitrer par l'utilisateur.
  • README.md (40 l) : point d'entrée pour un humain. run.md : les commandes génériques, pompage (dans le dev container de l'appli), /aiguiser et /boucle.
  • docs/decisions.md (790 l, D-001 à D-073) : 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.
    • colonnes-des-deplacements.md : colonnes des déplacements, d'après la FAQ et dans les exports reçus (« advanced » 15 min, horaire) ; images-de-la-camera.md : images IRON (la scène) et DIFF (les réflecteurs, l'image mesurée).
  • docs/energy/ : le domaine Energy.
    • analyses/<règle>.md (80-120 l) : fiche vivante de chaque analyse (principe, constantes et sources, résultats, limites, options écartées, pistes, historique). Modèle : .claude/skills/nouvelle-analyse/modele-fiche.md.
    • domaine/ (< 80 l) : comment-se-comporte-la-batterie.md (LiFePO4, plateau et coude, table OCV, redémarrage à 12,6 V, capacité) ; tensions-selon-l-etat-de-la-batterie.md (tensions et pentes en charge, pleine charge et décharge) ; cas-annotes-par-l-expert.md (diagnostics experts des 5 stations, vérité de référence).
    • guide/diagnostic-energetique.md (180 l, brouillon) : manuel, partie 1 pour le client (§1-4), partie 2 pour le support (§5-9). À tenir à jour avec la matrice et les fiches des deux analyses livrées.
    • matrice-etat-tendance.drawio : matrice état × tendance, tenue par l'utilisateur.
  • docs/storage/, docs/cellular/ : domaines Storage (espace disque) et Cellular (signal 4G), D-030. Storage a sa matrice état × horizon, matrice-etat-horizon.drawio, Cellular sa matrice lien × signal, matrice-lien-signal.drawio, tenues par l'utilisateur. Chacun a une note de départ, domaine/point-de-depart.md (mesures du collecteur, données reçues, pièges, pistes), ses fiches dans analyses/, ses questions ouvertes dans domaine/questions-pour-l-expert.md et son guide (~90 l, client puis support) dans guide/, dont la partie 1 est affichée dans la vue client.
  • 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-048), base de cas au §11 ; code dans agents/diagnostic/ (instructions.md, rapports/, un dossier par rapport avec ses figures ; la base de cas est dans events/, ses outils dans agent-tools/). Appel : @agent-diagnostic data/<STATION>/ [question], (en terminal, claude --agent diagnostic charge CLAUDE.md : pas à l'aveugle).
  • events/ : les événements, connaissance métier qui grandit (D-080) : la base de cas (INDEX.md, un dossier C-xxx/ par cas : cas.md, figures, données codées, etiquettes.json), validés par l'utilisateur ou « (appris) » par /boucle en attendant /revue-cas ; la carte des événements carte-des-evenements.md (familles, catégories du journal en section 4) et son graphe des éventualités eventualites-et-categories.drawio.
  • agent-tools/ : les outils de lecture des agents (D-081) : donnees.py (lecture commune), inventaire.py, resume.py, plages.py, jours.py, ensemble.py, graphique.py, vignettes.py, gif.py ; mode d'emploi dans le skill lire-les-donnees, aiguisés par /aiguiser ; utilisés par l'analyste de /boucle, l'agent de diagnostic, /support et les détecteurs (donnees.py).
  • 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/displacement/domaine/ce-que-regarde-le-client.md : sauts et tendances, pas les erreurs (D-055) ; docs/displacement/domaine/cas-annotes-par-l-expert.md : les deux rapports d'analyse résumés, vérité de référence sans données ; incident-de-barcelone.md : le cas de régression de la doc AIMsight, ses données (C-004) et l'avis de l'expert.
  • docs/aimsight/ : documentation AIMsight d'origine, non modifiée, en anglais sauf les rapports d'analyse. À 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).
    • AIMsight_agentic_support_project_context.md (2 090 l) : extension support : chaîne de dépendance (§4), domaines dont la santé système (§5.1, le cas d'usage actuel), règles épistémiques (§10), familles d'hypothèses (§12), format de sortie (§14-15), cas de régression (§16-17), cas d'usage (§23).
    • Les deux docs prévoient un LLM/agent pour la synthèse : la couche déterministe reste 100 % analytique ; la couche d'agents côté serveur (D-027) reprend cette idée, en exploration.
    • AIMsight FAQ.pdf, AIMsight Test Manual.pdf (en réalité le manuel de la station) : définitions des signaux et des colonnes CSV, alimentation, schedules. Mur de soutènement GN-1.472.pdf, GN-5.054.pdf : rapports d'analyse remis au client (mai 2026, en français).
    • collecteur_system_info.py : copie de référence du collecteur system_info embarqué (INA219, table OCV LiFePO4, compensation IR 0,34 Ω). Source des unités. Ne pas modifier.
  • docs/ameliorations-faq.md : carnet d'idées pour la prochaine révision de la FAQ, une entrée par idée sous la rubrique de la FAQ qu'elle concerne ; la réécriture viendra ensuite. docs/ameliorations-processus.md : carnet des difficultés des processus automatiques, tenu par le releveur (D-060).
  • docs/superpowers/ : specs et plans superpowers (170-850 l chacun). Historique non maintenu, pas une référence. La spec d'une nouvelle analyse s'écrit dans sa fiche ; le plan peut aller dans docs/superpowers/plans/.
  • data/ : un dossier par station, au numéro de série du système (D-029), rempli par le pompage (run.md), hors de git (D-065) : metrics/ (métriques système, un CSV par métrique et par jour), displacement/ (« advanced », un CSV par jour), camera/, images/. Les exports reçus à la main y ont été remplacés le 2026-10-26 par leurs plages repompées, élargies ; leurs copies codées restent dans les cas (events/).
    • VERMONT/ : jeu de travail = VERMONT seule (D-009), le plus long historique (métriques dès le 22/02). Les analyses Energy tournent uniquement sur ce jeu (défaut des scripts).
    • WEISSHORN/ : tous les champs de la caméra (mesures dès le 19/08) ; jeu de travail de storage (seul, D-034) et cellular (D-030) ; sur secteur, avec NORDEND, il sert à DAILY_POWER_SOURCE (D-043). Contient des identifiants (SIM_CCID, ip) : ne pas les recopier.
    • NORDEND/ : tous les champs d'une version plus ancienne du collecteur (sans link) ; deuxième jeu de travail de cellular, station à la liaison faible (D-032). Mêmes identifiants à ne pas recopier (SIM_CCID, ip_*).
    • PS des Coudres (Suisse, sous son numéro de série, ex-PS_DES_COUDRES/) : déplacements du 08/10 au 14/10, images de la caméra, vérité de référence (D-045), jeu de travail de displacement. De même NORDEND/, WILDSTRUBEL/, CLARIDEN/ (images à 10 min) et NIEDERHORN/ : données des cas C-002 à C-005.
    • Les notes brutes de l'expert (metadata.md, d.md) et archive/ ont été retirées le 2026-10-13 (D-033) : leur résumé est dans docs/energy/domaine/cas-annotes-par-l-expert.md.
  • src/ : un sous-dossier par domaine, plus le code commun (D-026).
    • common/ : stations.py (chargement des CSV, métriques texte en listes, trous de mesure ; bibliothèque standard) et page.py (poste de dev : bascule .venv, ouverture dans le navigateur, AUTOSCALE_Y_JS).
    • energy/ : calcul embarquable, en bibliothèque standard et sans import de common/ : battery_state.py, battery_trend.py, power_source.py, moving_average.py, day_color.py. Scripts plotly du poste de dev, à laisser hors de la station : final.py, all_analyses.py, focus_jour.py.
    • cellular/ : calcul embarquable link_state.py, signal_state.py, day_color.py (D-037) ; plotly : final.py (figure du site, D-039), all_analyses.py (D-031).
    • storage/ : calcul embarquable storage_state.py, days_until_full.py, day_color.py (D-035) ; plotly : final.py (figure du site, D-039), all_analyses.py (D-034).
    • temperature/ : calcul embarquable gpu_temperature_limit.py, day_color.py ; plotly : final.py (figure du site, D-041), all_analyses.py (D-040).
  • maquettes/ : maquettes du site en HTML sur données réelles (D-022), Figma seulement sur demande. Un script remplit son gabarit HTML : user/summary.py + summary_template.html (client, une page par station, un bloc par domaine), support/home.py + home_template.html (support). Les deux parcourent une liste de domaines (DOMAINS, D-039).
  • .claude/ : rules/analyses.md (se charge seule, voir « Analyses »), agents/diagnostic.md (point d'entrée de l'agent de diagnostic, D-046), skills/nouvelle-analyse/ (procédure et modèle de fiche), skills/nouveau-domaine/ (procédure pour un nouveau domaine), skills/support/ (réponse à un client, D-079), skills/nouveau-cas/ (ajouter un cas à la base de l'agent de diagnostic, lancé par l'utilisateur seul), skills/revue-cas/ avec l'agent revue (l'utilisateur valide, corrige ou rejette les cas appris par la boucle, D-075), skills/anonymiser-cas/ (données d'un cas copiées dans son dossier, noms en codes, registre des codes, D-049, D-050), skills/boucle/ et skills/critiquer-lot/ avec les agents analyste, upgrader, validateur, builder (boucle automatique, D-057), skills/lire-les-donnees/ (outils de lecture et leur mode d'emploi) et skills/aiguiser/ avec les agents lecteur, correcteur, optimiseur (D-059), agents/releveur.md (difficultés des processus automatiques, D-060), agents/ameliorateur.md (les corrige en fin de /boucle --ameliorer ou /aiguiser --ameliorer, D-071, D-076), settings.json (lecture de .env interdite). Schémas de ces processus (agents, flux de données) : docs/agents/pipelines-ia.drawio, une page par processus.
  • vues-deplacements/ : chantier à part des vues des déplacements et de l'agent dans une maquette (D-052) : contexte, cas réels (données, pages de la plateforme, parcours de l'utilisateur), puis le code ; sa carte : vues-deplacements/CLAUDE.md ; maquette de la page Explore avec les onglets View et Diagnosis dans vues-deplacements/maquette/ (D-053, D-054) ; détecteurs du journal du matin dans vues-deplacements/detectors/ (D-056) ; extraction/ : pompage des données de la plateforme (D-056), à lancer par l'utilisateur dans le dev container de l'application (qui monte ~ : sortie directe dans data/) ; lecture seule ; mode d'emploi dans extraction/README.md.
  • .devcontainer/devcontainer.json : environnement de dev en conteneur (D-038), réseau de l'hôte pour joindre la caméra. architecture.drawio : schéma d'architecture tenu par l'utilisateur, à ne pas modifier sans demande. out/ : pages et JSON générés. Tout le projet est versionné, sauf out/, data/ (D-065), .venv/ et __pycache__/ (D-014).

Règles de travail

  • Une décision projet prise en conversation donne une entrée dans docs/decisions.md.
  • Toute modification d'une analyse met à jour sa fiche dans le même changement.
  • Un savoir métier nouveau va dans docs/domaine/ (commun) ou docs/<domaine>/domaine/.
  • Un processus automatique à plusieurs agents (aujourd'hui /boucle) fait remonter ses difficultés : chaque sous-agent finit son rendu par ## Difficultés, l'orchestrateur appelle l'agent releveur en fin de processus, qui les note dans docs/ameliorations-processus.md (D-060). Pas dans une conversation ordinaire.
  • Un changement de cap met à jour « État et prochaine étape » ci-dessus : l'état courant, pas un historique.
  • Langue : échanges et documents projet en français ; documentation AIMsight en anglais (garder ses termes techniques) ; tout ce qui va au site en anglais, figure état × tendance comprise (D-023).

Principes (raisons, statuts et options écartées : docs/decisions.md)

  • Point d'entrée du POC : scan proactif d'un export. L'agent détecte les événements, les classe et explique chacun. Le mode « question de support » viendra ensuite, sur le même socle.
  • Premier cas d'usage : santé énergétique des stations. Ici, le trou de données est l'anomalie. L'interprétation des déplacements viendra ensuite.
  • Pas de LLM dans la couche déterministe (agents LLM côté serveur en exploration, D-027), pas de données synthétiques (ni CSV simulés, ni générateur de scénarios : refus explicite de l'utilisateur). Le code d'analyse est embarquable : bibliothèque standard, calcul léger.
  • Anomalie énergétique = régime non soutenable (l'apport ne couvre pas la consommation), pas une batterie basse. Une station débranchée avec une batterie pleine est déjà en anomalie.
  • Analyses combinées : chaque analyse est une preuve imparfaite, juste « dans la majorité des cas » ; la combinaison fait le diagnostic (pour Energy, la matrice état × tendance, D-020). Une analyse seule conclut au plus consistent with. Préférer des fenêtres larges (plusieurs jours, multiples de 24 h).
  • Livrables : pour le site, une figure Plotly par station (état en haut, tendance dessous, D-021) et la couleur du jour ; pour comparer, une page HTML par station, un panneau par analyse puis un graphique par série (D-016). Zoom dans le temps seulement, ordonnée recalée sur la plage visible (D-013).
  • Destinataires du diagnostic : le client final et l'ingénieur support, en couches (D-020).
  • Ouvert : architecture (à définir plus tard, ne pas la figer ici).

L'essentiel du domaine (détail : docs/domaine/)

  • Données : un CSV par station et par métrique, <STATION>_<Metric>_<début> to <fin>.csv, colonnes ,time_utc,metric, moyennes horaires en UTC. Une valeur vide signifie qu'il n'y a pas de mesure. Toute heure est en UTC (données, noms de fichiers, documents, échanges) ; une heure locale ne figure que pour décrire une source qui l'utilise.
  • Unités : BusVoltage [V], BusCurrent [mA], Power [mW], ShuntVoltage [mV]. Ces trois dernières sont une seule mesure : la consommation. L'apport (panneau ou secteur) n'est pas mesuré.
  • Batterie LiFePO4 de 12,8 V :
    • entre 30 et 90 % de charge, la tension de nuit reste plate ; elle ne chute qu'au coude (~12,8 V, puis ~12,5 V) ;
    • sous 12 V, la station s'éteint et ne redémarre que vers ~12,6 V ;
    • ≥ 14,0 V dans la journée signale une charge complète.
  • Les seuils de tension absolus ne se transposent pas d'une station à l'autre : comparer la station à son propre passé. Exception : les seuils du matériel (fin de charge ~14,0 V, coude 12,8 V), admis pour les analyses d'état (D-018).
  • Un trou n'est pas forcément une coupure : retard de synchronisation en fin de fichier, début d'historique, cause commune si plusieurs stations ont un trou en même temps.

Règles non négociables

  • Chaque conclusion est traçable. Elle cite les faits calculés et la règle qui l'a produite. Aucun chiffre ni seuil sans source.
  • Ne pas confondre « pas de donnée visible » et « station arrêtée » : acquisition, transmission, ingestion et affichage sont des couches distinctes.
  • Séparer fait observé, fait dérivé, contexte opérateur, hypothèse et inconnu. Pas de pseudo-probabilités ; vocabulaire : confirmed / strongly supported / consistent with / possible / insufficient evidence / not observed.
  • Pas de règle spécifique à un site : les cas résolus deviennent des cas de régression.
  • Lecture seule : aucune action sur les stations, la configuration ou le retraitement.
  • Pour les déplacements (cas d'usage suivant) :
    • ne rien construire sur inlier binaire : RANSAC sera remplacé par un estimateur pondéré. Utiliser poids continus, N_eff, résidus, influence ;
    • sigma0 seul et le nombre de références ne sont jamais des critères suffisants ;
    • ne pas confondre qualité image d'une cible et qualité du réseau de références, ni petit résidu et transformation bien contrainte ;
    • ne pas confondre mouvement en mode commun et mouvement structurel, ni références cohérentes et références physiquement fixes.

Environnement

  • pandas n'est pas installé ; la bibliothèque standard suffit pour explorer les CSV (csv, datetime.fromisoformat). .venv/ (Python 3.14) ne contient que plotly et matplotlib (graphiques de l'agent de diagnostic), pour le poste de dev. Le code d'analyse reste en bibliothèque standard.
  • Dev container (D-038) : Docker Engine dans WSL (réseau mirrored), VS Code « Reopen in Container » ; dans le conteneur, les pages restent dans out/ sans s'ouvrir seules.