Files
Support-Agent/CLAUDE.md
T
2026-10-16 15:00:00 +02:00

30 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-16)

L'état courant seulement ; l'historique est dans git log et docs/decisions.md.

  • 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.
  • Energy, 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), gardé en l'état (D-052) : 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/<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, agents/diagnostic/cas/), lue après les faits : cinq cas, C-001 à C-005 (l'index agents/diagnostic/cas/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 sur demande explicite de l'utilisateur (skill /nouveau-cas). 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 : déplacements (D-052, D-053) : maquette de la page Explore avec l'onglet Diagnosis (vues-deplacements/maquette/, cas NORDEND : image à l'instant T et grille capteurs × temps reliées, détail minimal ; version 0 vérifiée par captures, clics pas encore essayés, état dans vues-deplacements/maquette/spec.md) ; recueillir le retour de l'utilisateur (l'expert), puis la remplir pas à pas, d'abord le détail d'un capteur, puis l'agent dans la page ; 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) ; 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 + onglet Diagnosis (D-053) : out/vues_deplacements_<STATION>.html (défaut : cas NORDEND)
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), out/ (sorties générées), .venv/.

Fichiers

  • README.md (40 l) : point d'entrée pour un humain.
  • docs/decisions.md (585 l, D-001 à D-052) : 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).
  • 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, outils/, rapports/, un dossier par rapport avec ses figures, cas/, la base de cas). Appel : @agent-diagnostic data/<STATION>/ [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/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/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 (D-029).
    • VERMONT/ : jeu de travail = VERMONT seule (D-009), le plus long historique : 7 CSV, un par métrique système (~5 000 l chacun). Les analyses Energy tournent uniquement sur ce jeu (défaut des scripts).
    • WEISSHORN/ : tous les champs de la caméra (export du 2026-10-13, du 09/08 au 13/10, 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 ; le dépôt doit rester privé (D-014).
    • NORDEND/ : tous les champs d'une version plus ancienne du collecteur (export du 2026-10-13, 109 jours, 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/displacement/ : déplacements optiques de PS des Coudres (Suisse), du 08/10 au 14/10 : export « advanced » (15 min, UTC), source des analyses, et export horaire ; images/ : 24 images horaires de la caméra (13/10 12:00 → 14/10 11:00 UTC), vérité de référence (D-045). Jeu de travail de displacement. Même rangement pour NORDEND/, WILDSTRUBEL/ et CLARIDEN/ (export et images à 10 min) et NIEDERHORN/ (horaires), 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/nouveau-cas/ (ajouter un cas à la base de l'agent de diagnostic, lancé par l'utilisateur seul), skills/anonymiser-cas/ (données d'un cas copiées dans son dossier, noms en codes, registre des codes, D-049, D-050), settings.json (lecture de .env interdite).
  • 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 l'onglet Diagnosis dans vues-deplacements/maquette/ (D-053).
  • .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/, .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 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.