From ef8ad7028557b5b98fd7df3832594bc382412ffa Mon Sep 17 00:00:00 2001 From: maxime Date: Tue, 13 Oct 2026 08:58:43 +0200 Subject: [PATCH] Turn CLAUDE.md into a full map of the repository D-028: CLAUDE.md names every folder and document with its size in lines, says how to read without filling the context (outline of a long file then one section, index of the decision log, CSV by script, folders not to read), and gives the current state instead of a dated history. It and D-026 now name final.py for the delivered script. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 153 ++++++++++++++++++++++++---------------------- docs/decisions.md | 14 ++++- 2 files changed, 92 insertions(+), 75 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 68c2386..b960c37 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,87 +1,100 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -Ce fichier est une **carte**, chargée à chaque session : il doit rester court (< 200 lignes). Le détail est dans `docs/` et se lit quand on en a besoin. +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 +## État et prochaine étape (au 2026-10-12) -- **2026-10-09** : `MOVING_AVERAGE_7_DAYS_DROP` est en place sur VERMONT et produit un graphique HTML. C'est un prototype expérimental, sans tests automatisés. -- **Point ouvert de `MOVING_AVERAGE_7_DAYS_DROP`** : l'accoutumance. Après plus de 30 jours de déficit, l'anomalie peut disparaître (voir sa fiche). -- **2026-10-12** : `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` (suggestion d'un collègue) en place, en panneau sous la précédente pour comparer. Elle est bien moins bruitée (pire cas sain −0,04 V contre −0,16 V), mais plus tardive sur VERMONT : 1 h avant la première coupure, contre ~2,7 jours. -- **2026-10-12, changement d'échelle (D-018)** : les analyses suivantes donnent l'état de la batterie jour par jour, avec des seuils physiques du matériel, pour être utilisables dès l'installation. Phase C (état seul), puis phase B (niveaux gradués). -- **2026-10-12** : `DAILY_BATTERY_STATE` en place (phase C, état seul). -- **2026-10-12** : `DAILY_BATTERY_TREND` en place (tendance markovienne : chaque jour face à la veille, mieux / stable / pire). -- **2026-10-12, recentrage (D-020)** : le diagnostic énergétique livré ne retient que `DAILY_BATTERY_STATE` et `DAILY_BATTERY_TREND`, combinées par la matrice état × tendance de `docs/energy/matrice-etat-tendance.drawio` en une couleur par jour (vert / orange / rouge). Le manuel `docs/energy/guide/diagnostic-energetique.md` (brouillon) l'explique au client et au support. -- **2026-10-12 (D-021)** : graphique pour le site de monitoring (Plotly) : une seule figure, l'état en haut et la tendance dessous, écrite en page de démo et en JSON. La matrice est codée (`src/energy/day_color.py`, jours inconnus en gris), mais pas tracée (la bande de couleurs a été écartée). -- **2026-10-12 (D-022, D-023)** : maquettes du site en HTML sur données réelles (`maquettes/user/` pour le client, `maquettes/support/` pour le support ; Figma seulement sur demande). Maquette client « Energy » en place : section Diagnostic de la page System Summary. Tout ce qui va au site est en anglais, figure état × tendance comprise. -- **2026-10-12 (D-024)** : focus sur un jour, J et la veille seulement : `src/energy/focus_jour.py` (résumé des faits + graphique de 48 h), sélection des données dans `day_color.focus()`. -- **2026-10-12 (D-025)** : maquette support « Home » en place : page d'accueil (toutes les stations) avec une section Status, une notification par station Orange ou Red, et un lien vers la vue client. -- **2026-10-12 (D-026)** : projet rangé par domaine (`src/energy/`, `docs/energy/`, code commun dans `src/common/`, documentation AIMsight dans `docs/aimsight/`). Les analyses ne sont plus numérotées : chacune est désignée par sa règle. Deux scripts Energy : `daily.py` (analyses livrées) et `all_analyses.py` (comparaison). -- **2026-10-12 (D-027)** : piste exploratoire d'une couche d'agents LLM côté serveur, en complément des règles (anomalies inconnues, cas limites des règles) : `docs/agents/rapport-exploratoire.md`. Rien n'est construit. +L'état courant seulement ; l'historique est dans `git log` et `docs/decisions.md`. + +- **Energy, livré (prototype, D-020)** : `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). 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)** : client « Energy » (section Diagnostic de la page System Summary) ; support « Home » (section Status, une notification par station Orange ou Red, lien vers la vue client, D-025). +- **Agents LLM côté serveur (D-027)** : rapport exploratoire seulement, rien n'est construit. - **Prochaine étape** : é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 « Energy » côté client pas à pas, puis le côté support pas à pas (points ouverts dans D-022). ## Analyses (domaine Energy) -| Règle | Question | Statut | Fiche | -|---|---|---|---| -| `DAILY_BATTERY_STATE` | Chaque jour : pleine charge, charge partielle (incertain), sous le plateau ou aucune charge ? | livrée (prototype, D-020) | `docs/energy/analyses/daily_battery_state.md` | -| `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) | `docs/energy/analyses/daily_battery_trend.md` | -| `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 seulement | `docs/energy/analyses/moving_average_7_days_drop.md` | -| `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP` | Même question, sur la seule mesure de 00:00 UTC de chaque jour | comparaison seulement | `docs/energy/analyses/moving_average_7_days_midnight_utc_drop.md` | +Code dans `src/energy/`, fiche dans `docs/energy/analyses/.md`. -Pour créer une analyse : skill `nouvelle-analyse` (`.claude/skills/nouvelle-analyse/`). +| 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` | + +- **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`. ## Commandes -- `python3 src/energy/daily.py [données]` : analyses livrées (`DAILY_BATTERY_STATE`, `DAILY_BATTERY_TREND`). Il écrit `out/_daily.html` + `.json` (figure pour le site, D-021) et les ouvre dans le navigateur (via `explorer.exe` sous WSL). Défaut : `data/`. Il bascule seul sur `.venv` si plotly manque, comme tous les scripts plotly. -- `python3 src/energy/all_analyses.py [données]` : les quatre analyses ensemble pour comparer (D-016), un panneau chacune, puis un graphique par série. Il écrit `out/_energy.html` et l'ouvre. -- `python3 src/energy/focus_jour.py 27.09` : focus sur un jour et sa veille (D-024). Il affiche les faits de la couleur et écrit `out/_focus_.html` + `.json`, puis l'ouvre. -- `python3 maquettes/user/energy.py [début] [fin]` : maquette client « Energy » (page System Summary, section Diagnostic, D-022), écrite dans `out/maquette_user_energy.html` et ouverte. -- `python3 maquettes/support/home.py [début] [fin]` : maquette support « Home » (toutes les stations, section Status, D-025), écrite dans `out/maquette_support_home.html` et ouverte. +```bash +python3 src/energy/final.py [données] # livré : out/_daily.html + .json (figure du site, D-021) +python3 src/energy/all_analyses.py [données] # les 4 analyses comparées (D-016) : out/_energy.html +python3 src/energy/focus_jour.py JJ.MM[.AAAA] [données] # un jour et sa veille (D-024) : faits + out/_focus_.html + .json +python3 maquettes/user/energy.py [début] [fin] # maquette client : out/maquette_user_energy.html +python3 maquettes/support/home.py [début] [fin] # maquette support : out/maquette_support_home.html +pdftotext -layout "docs/aimsight/.pdf" - # lire un PDF AIMsight +python3 -m venv .venv && .venv/bin/pip install plotly # recréer .venv +``` -## Documentation (à lire à la demande) +- `[données]` : CSV ou dossiers, défaut `data/`. Dates des maquettes en `AAAA-MM-JJ`, défaut 2026-09-18 à 2026-09-28 ; la maquette support mène à la maquette client : les lancer avec les mêmes dates. +- 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 VERMONT. -- `docs/decisions.md` : journal des décisions **projet**, au format ADR allégé (statut, décision, pourquoi, options écartées, conséquence). Le lire avant de changer d'orientation ou de reproposer une option : elle a peut-être déjà été écartée. -- `docs//analyses/.md` : fiche vivante de chaque analyse (principe, constantes et sources, résultats, limites, options écartées, historique). Modèle : `.claude/skills/nouvelle-analyse/modele-fiche.md`. -- `docs/domaine/` : le savoir métier commun, une note par question. +## Carte du dépôt + +### Lire sans saturer le contexte + +- Fichier long (tailles en lignes ci-dessous) : lire son plan (`grep -n '^#' `), 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` (300 l, D-001 à D-027) : 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 (cas d'usage suivant). -- `docs/energy/domaine/` : le savoir métier Energy. - - `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 (VERMONT, collecteur, chimie). - - `cas-annotes-par-l-expert.md` : diagnostics experts des 5 stations. -- `docs/agents/rapport-exploratoire.md` : cadre d'agents de diagnostic LLM (D-027). Choix retenus, architecture, démarrage par étapes ; annexe A : pistes détaillées à revoir étape par étape. -- `docs/energy/guide/diagnostic-energetique.md` : manuel du diagnostic énergétique, pour le client (partie 1) et le support (partie 2). À tenir à jour avec la matrice (`docs/energy/matrice-etat-tendance.drawio`) et les fiches `DAILY_BATTERY_STATE` et `DAILY_BATTERY_TREND`. -- **Règle 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/` ; - - un changement de cap met à jour « État et prochaine étape » ci-dessus. -- `.claude/rules/analyses.md` se charge seul quand Claude touche `src/` ou `docs/*/analyses/`. -- `docs/superpowers/` : documents de travail superpowers (specs, plans). C'est un historique, non maintenu après coup, et ce n'est pas une référence. La spec d'une nouvelle analyse s'écrit directement dans sa fiche `docs//analyses/.md` ; le plan peut rester dans `docs/superpowers/plans/`. - -## Fichiers - -- `README.md` : point d'entrée pour un humain (lancer l'analyse, où trouver quoi). Tout le projet est versionné, sauf `out/`, `.venv/` et `__pycache__/` (D-014). -- `docs/aimsight/` : documentation AIMsight d'origine, à lire avant de concevoir. Ne pas re-demander à l'utilisateur ce qui y figure. Contenus non modifiés. - - `AIMsight_reference_quality_event_explainer_roadmap.md` : **référence qui fait autorité**. Elle couvre la couche diagnostique commune, l'explainer d'événements, les classifications (§4.3) et l'API indépendante de l'estimateur (§10). - - `AIMsight_agentic_support_project_context.md` : extension support. Contenu : chaîne de dépendance (§4), domaines dont la santé système (§5.1), 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). +- `docs/energy/` : le domaine Energy. + - `analyses/.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/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 vivra à part (`agents/`, proposé, pas créé). +- `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). + - `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` et `AIMsight Test Manual.pdf` (ce dernier est en réalité le manuel de la station) : définitions des signaux et des colonnes CSV, alimentation, schedules. Pour les lire : `pdftotext -layout "docs/aimsight/.pdf" -`. + - `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. - `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. -- `data/` : **jeu de travail = VERMONT seule**, le seul dataset complet (les 7 métriques système, telles qu'extraites de la plateforme) + diagnostics experts (`metadata.md`, `d.md`). Les analyses tournent uniquement sur ce jeu. -- `data/archive/` : `BusVoltage` seule des autres stations (incomplètes), mises de côté le 2026-10-09. Non analysées ; ne pas les réintroduire sans demande. +- `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/` : **jeu de travail = VERMONT seule** (D-009), le seul dataset complet : 7 CSV, un par métrique système (~5 000 l chacun). Les analyses tournent uniquement sur ce jeu. + - `metadata.md` (220 l) et `d.md` : notes brutes de l'expert, résumées dans `cas-annotes-par-l-expert.md`. `metadata.md` contient aussi des identifiants techniques de station (SIM, IP) : le dépôt doit rester privé (D-014). + - `archive/` : `BusVoltage` seule de 4 autres stations (incomplètes), mises de côté le 2026-10-09. Non analysées ; ne pas les réintroduire sans demande. - `src/` : un sous-dossier par domaine, plus le code commun (D-026). - - `src/common/` : `stations.py` (chargement des CSV, trous de mesure ; bibliothèque standard) et `page.py` (poste de dev : bascule `.venv`, ouverture dans le navigateur, `AUTOSCALE_Y_JS`). - - `src/energy/` : calcul embarquable, en bibliothèque standard et sans import de `common/` : `moving_average.py`, `battery_state.py`, `battery_trend.py` et `day_color.py` (matrice, couleur du jour, focus J−1 / J). Scripts plotly du poste de dev : `daily.py`, `all_analyses.py` et `focus_jour.py`. + - `common/` : `stations.py` (chargement des CSV, 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`, `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`. +- `maquettes/` : maquettes du site en HTML sur données réelles (D-022), Figma seulement sur demande. Un script remplit son gabarit HTML : `user/energy.py` + `energy_template.html` (client), `support/home.py` + `home_template.html` (support). +- `.claude/` : `rules/analyses.md` (se charge seule, voir « Analyses »), `skills/nouvelle-analyse/` (procédure et modèle de fiche), `settings.json` (lecture de `.env` interdite). - `architecture.drawio` : schéma d'architecture tenu par l'utilisateur. Ne pas le modifier sans demande. -- `maquettes/` : maquettes de page en HTML, sur données réelles (D-022), en deux blocs : `user/` (client) et `support/`. Un script par design, ou directement le HTML. Figma seulement sur 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/`. +- 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`) @@ -89,11 +102,9 @@ Pour créer une analyse : skill `nouvelle-analyse` (`.claude/skills/nouvelle-ana - **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. Préférer des fenêtres larges (plusieurs jours, multiples de 24 h). - - Contrat commun : `run(series) -> {analysis, rule, points: [{t, value, anomaly, facts}]}`. Calcul causal (le point t n'utilise que les données ≤ t). `anomaly = None` signifie UNKNOWN (exception : `DAILY_BATTERY_STATE` en phase C et `DAILY_BATTERY_TREND`, où `None` = pas de verdict ; l'UNKNOWN est dans `facts.state` ou `facts.trend`). - - Une analyse seule conclut au plus `consistent with`. -- **Livrable** : un graphique HTML par station. En haut, les analyses, un panneau chacune (courbes superposées, D-016) ; dessous, un graphique par série temporelle. Zoom dans le temps seulement, avec l'ordonnée recalée sur la plage visible (D-011, D-013). -- **Destinataire du diagnostic** : le client final et l'ingénieur support, en couches (D-020). +- **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/`) @@ -111,20 +122,16 @@ Pour créer une analyse : skill `nouvelle-analyse` (`.claude/skills/nouvelle-ana - **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. -- 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. - 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, pour le poste de dev. Le code d'analyse reste en bibliothèque standard. -- Prototype expérimental : **pas de tests automatisés** (D-008). Vérifier les changements à la main en lançant `python3 src/energy/all_analyses.py` (et `daily.py` pour le livré) sur VERMONT. - -## Conventions - -- Échanges et documents projet en français ; la documentation AIMsight est en anglais (garder ses termes techniques). diff --git a/docs/decisions.md b/docs/decisions.md index b482f73..8da9adc 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -260,7 +260,7 @@ Règles du journal : - **Décision** : - **Chaque domaine a son sous-dossier dans chaque couche** : `src/energy/` et `docs/energy/` (analyses, domaine, guide, matrice). Le code commun est dans `src/common/` (`stations.py` : chargement des CSV ; `page.py` : bascule `.venv`, ouverture, `AUTOSCALE_Y_JS`). `maquettes/` reste découpé par public (D-022). Les notes communes restent dans `docs/domaine/`. - **Les analyses ne sont plus numérotées** : chacune est désignée par sa règle et sa fiche porte son nom (`docs/energy/analyses/daily_battery_state.md`). Correspondance : 01 = `MOVING_AVERAGE_7_DAYS_DROP`, 02 = `MOVING_AVERAGE_7_DAYS_MIDNIGHT_UTC_DROP`, 03 = `DAILY_BATTERY_STATE`, 04 = `DAILY_BATTERY_TREND`. Les entrées du journal antérieures à celle-ci gardent les numéros. - - **Deux scripts d'analyse pour Energy** : `src/energy/daily.py`, les analyses livrées (état et tendance, D-020 et D-021), qui écrit `out/_daily.html` et `.json` ; `src/energy/all_analyses.py`, les quatre analyses ensemble pour comparer (D-016), qui écrit `out/_energy.html`. `src/energy/focus_jour.py` reste l'outil de focus (D-024). Le résumé texte d'`energy_check.py` (`out/_energy.json`) est supprimé. + - **Deux scripts d'analyse pour Energy** : `src/energy/final.py` (`daily.py` jusqu'au 2026-10-13), les analyses livrées (état et tendance, D-020 et D-021), qui écrit `out/_daily.html` et `.json` ; `src/energy/all_analyses.py`, les quatre analyses ensemble pour comparer (D-016), qui écrit `out/_energy.html`. `src/energy/focus_jour.py` reste l'outil de focus (D-024). Le résumé texte d'`energy_check.py` (`out/_energy.json`) est supprimé. - **La documentation AIMsight d'origine passe de `doc/` à `docs/aimsight/`**, avec la copie du collecteur (`collecteur_system_info.py`, ex-`src/__main__ (3).py`). La roadmap perd le suffixe « (2) ». `cas-d-usage-03-04.drawio` devient `docs/energy/matrice-etat-tendance.drawio`. Les contenus ne changent pas. - Le modèle de fiche passe dans le skill `nouvelle-analyse` (`modele-fiche.md`). - **Pourquoi** : demande de l'utilisateur. Encapsuler Energy pour que le domaine suivant (D-002) se range à côté. Ranger les fichiers dispersés (racine, `doc/` à côté de `docs/`, code commun mêlé aux analyses). Energy a convergé vers les analyses livrées : un numéro d'ordre de création n'aide plus, le nom de la règle suffit. @@ -271,7 +271,7 @@ Règles du journal : - une numérotation par domaine : elle ne dit pas plus que le nom de la règle. - **Conséquence** : - les anciens chemins restent dans `docs/superpowers/` et dans le texte des entrées antérieures du journal (historique non réécrit) ; - - le code de calcul s'embarque en copiant `src/energy/` sans `daily.py`, `all_analyses.py` ni `focus_jour.py`, qui demandent plotly. + - le code de calcul s'embarque en copiant `src/energy/` sans `final.py`, `all_analyses.py` ni `focus_jour.py`, qui demandent plotly. ## D-027 — 2026-10-12 — Couche d'agents de diagnostic côté serveur (exploratoire) - **Statut** : active, exploratoire (rapport `docs/agents/rapport-exploratoire.md`, rien n'est construit). Remplace en partie D-003 : le refus du LLM ne vaut plus que pour la couche déterministe. @@ -294,3 +294,13 @@ Règles du journal : - les règles non négociables (traçabilité, vocabulaire, lecture seule, pas de seuil inventé) s'appliquent aux agents ; - les règles détaillées proposées (journal, contrôles de `notify`, politique de destinataire, affichage) sont des **pistes à revoir étape par étape**, pas des décisions (annexe A du rapport) ; - prérequis de l'étape 1 : un compte et une clé API Anthropic. + +## D-028 — 2026-10-12 — CLAUDE.md : carte complète du dépôt, état courant, lecture ciblée +- **Statut** : active. Précise D-012. +- **Décision** : + - `CLAUDE.md` nomme chaque dossier et chaque document du dépôt, avec sa taille en lignes, pour que l'agent sache ce qui existe sans l'ouvrir ; + - il dit comment lire sans saturer le contexte : plan d'un fichier long puis la seule section utile, index de ce journal, CSV par script, dossiers à ne pas lire ; + - « État et prochaine étape » donne l'état courant, pas un historique daté ; + - ce qui est déjà dans `.claude/rules/analyses.md` (contrat `run(series)`, disposition des graphiques) n'y est plus répété. +- **Pourquoi** : demande de l'utilisateur. Le CLAUDE.md doit révéler tout le projet sans forcer l'agent à le lire. L'historique daté grossissait à chaque étape alors qu'il est déjà dans `git log` et ce journal ; la doc AIMsight (~3 300 lignes) était à « lire avant de concevoir » sans dire comment la lire par section. +- **Options écartées** : un index des sections de chaque gros document dans `CLAUDE.md` : `grep -n '^#'` le donne à la demande, sans coût permanent.