Files
Support-Agent/docs/superpowers/specs/2026-10-13-nouveaux-domaines-design.md

19 KiB
Raw Permalink Blame History

Nouveaux domaines de notification : Storage, Cellular, et une procédure pour les suivants

  • Date : 2026-10-13
  • Statut : design validé en conversation, spec à relire.
  • Décision projet qui en découle : D-030 (texte en fin de document).

Objectif

  • Faire pour d'autres points d'attention le même travail qu'Energy : des analyses sans LLM, un verdict du jour, une notification au client et au support (D-020, D-022, D-025).
  • Deux premiers domaines : l'espace disque restant et la qualité du signal 4G. D'autres suivront peut-être.
  • Les données sont arrivées pendant la conception : data/WEISSHORN/ contient tous les champs de la caméra (voir « Jeu de travail »). On les explorera ensuite, pour voir ce qui mérite une notification. Aujourd'hui, on prépare :
    • une procédure réutilisable, pour ajouter vite un nouveau domaine, donc une nouvelle notification ;
    • pour chacun des deux domaines, une note de départ : ce qu'on sait déjà, et ce qu'il faudra demander aux données.
  • Critère de réussite : quand les CSV arrivent, on sait quoi faire, dans quel ordre, et où ranger chaque chose.

Ce qui ne change pas

  • Le code et les pages d'Energy, les maquettes et les données (data/).
  • Aucune analyse ni aucun seuil n'est écrit avant l'exploration des données : pas de données synthétiques (D-003), aucun seuil sans source.

Les domaines

Les noms sont en anglais, en un mot, comme energy :

  • storage, l'espace disque. C'est le mot du collecteur (data_storage_*).
  • cellular, le signal 4G : niveau radio, enregistrement au réseau et lien, c'est-à-dire tout ce que rapporte le modem. Le VPN (ip_nebula1) et les envois de données n'en font pas partie : la doc AIMsight les range sous « Communication » (§ « Likely high-value future signals »), qui pourra devenir un domaine plus tard.

Ce qui est créé maintenant

Fichier Contenu
src/storage/__init__.py, src/cellular/__init__.py vides, comme src/energy/__init__.py : la place du code, qui viendra avec la première analyse
docs/storage/domaine/point-de-depart.md note de départ du domaine (≈ 50 l), voir plus bas
docs/cellular/domaine/point-de-depart.md idem
.claude/skills/nouveau-domaine/SKILL.md la procédure (≈ 80 l), voir plus bas
  • Les autres dossiers du domaine (analyses/, guide/, matrice) ne sont pas créés : git ne suit pas les dossiers vides. Le skill les crée quand ils ont un contenu.
  • Les CSV des nouvelles métriques vont dans data/<STATION>/ (D-029), à côté des CSV Energy de la même station.

Jeu de travail des nouveaux domaines : WEISSHORN

  • VERMONT (D-009) n'a ni métrique de disque ni métrique de modem. Pour storage et cellular, le jeu de travail est WEISSHORN : tout ce que contient data/WEISSHORN/, sans restriction de dates. Un export plus long le remplace ou le complète, et c'est souhaitable : la vitesse de remplissage du disque et la comparaison du signal à son propre passé demandent des fenêtres larges.

  • L'export reçu le 2026-10-13 contient tous les champs de la caméra. Il couvre ce que l'extraction a fourni, du 2026-10-03 07:00 au 2026-10-13 07:00 UTC, soit 241 heures, sans trou.

  • Ce que montre un premier profil, fait par script :

    • les métriques numériques sont des moyennes horaires, comme pour VERMONT ;
    • les métriques texte (link, registration, network_technology, network_operator, BatteryState) sont la liste des échantillons de l'heure, par exemple ['up', 'up', 'up', 'up'], soit un toutes les 15 minutes. Ce ne sont pas des moyennes ;
    • last_sync est la liste des heures de synchronisation de l'heure (toutes les 15 minutes). C'est une piste pour un futur domaine « Communication », hors du périmètre ici ;
    • 10 copies … (1).csv, (2).csv, (3).csv (ShuntVoltage, rsrq_dB, rssi_dbm, sensor_thermal_deg_c) sont identiques à l'octet près à leur original. Avec elles, load_stations s'arrête sur une erreur « doublon » ;
    • 38 fichiers …:Zone.Identifier ont été laissés par le téléchargement sous Windows ;
    • SIM_CCID et ip sont des identifiants de station. Ils restent dans data/ (dépôt privé, D-014) et ne sont jamais recopiés dans les notes ;
    • Battery Voltage couvre la même plage que BusVoltage, mais les deux séries ne sont pas identiques. Point à éclaircir pour Energy, hors du périmètre ici.
  • Réception (étape 2 du skill, appliquée à WEISSHORN) :

    • supprimer les 10 copies identiques et les 38 Zone.Identifier ;
    • ajouter *:Zone.Identifier à .gitignore ;
    • versionner data/WEISSHORN/, comme data/VERMONT/.

    Les métriques texte restent ignorées par le chargeur tant que l'exploration n'a pas montré qu'on en a besoin.

Note de départ d'un domaine

Elle est rangée dans docs/<domaine>/domaine/, avec le savoir du domaine qui y restera, et elle se complète au fil des étapes. Sections :

  1. Question du domaine, en une phrase.
  2. Ce que mesure le collecteur : métriques, unités, ligne source dans docs/aimsight/collecteur_system_info.py, nom exporté (SYNC_SPEC).
  3. Ce que montrent les instantanés de data/metadata.md (WILDSTRUBEL et VERMONT), sans les identifiants (SIM, IP).
  4. Ce qu'en disent les docs AIMsight : le manuel de la station et la FAQ.
  5. Pièges déjà connus.
  6. CSV reçus et manquants, par rapport à ce que le collecteur exporte.
  7. Pistes d'analyses : ce sont des pistes, pas des décisions. Elles passent dans les fiches au moment où les analyses s'écrivent.

Storage : ce qu'on sait déjà

  • Collecteur (get_proc_info) : psutil.disk_usage('/data'), la partition des données. Il produit data_storage_percent [%], et data_storage_free_gb, _used_gb et _total_gb [GiB, ÷ 1024³]. Dans SYNC_SPEC, les trois derniers sont exportés sous une seule métrique data_storage_gb, avec un label state qui vaut free, used ou total.
  • Instantanés :
    • WILDSTRUBEL : total 5,98, libre 5,61, utilisé 0,04 GiB ;
    • VERMONT expose d'autres noms, absents de notre copie du collecteur : total_disk_1k-blk, used_disk_1k-blk, avail_disk_1k-blk (blocs de 1 kio), DB_file_size, DB_total_entries, DB_uploaded, DB_not_uploaded.
  • WEISSHORN (plages observées dans l'export du 2026-10-13) :
    • data_storage_free_gb de 3,21 à 3,48 ; data_storage_used_gb de 2,17 à 2,45 ; data_storage_total_gb à 5,98 ;
    • le label state du collecteur est aplati dans le nom de la métrique ;
    • data_storage_percent n'est pas dans l'export, ni les métriques *_disk_1k-blk et DB_* de VERMONT.
  • Manuel de la station (§ Disk) : « Monitor available capacity, especially for frequent schedules, long time series, or image-heavy acquisitions ».
  • Pièges :
    • utilisé + libre ≠ total (5,65 contre 5,98 GiB chez WILDSTRUBEL ; 3,46 contre 3,67 GiB chez VERMONT, soit 3 623 856 contre 3 849 952 blocs de 1 kio). Un écart de 5 à 6 % est cohérent avec les blocs réservés d'ext4, mais ce n'est pas vérifié. psutil.percent se calcule sur utilisé / (utilisé + libre), pas sur le total ;
    • deux familles de métriques, selon la version du logiciel ou la partition mesurée. Laquelle est exportée pour chaque station ? Question à poser ;
    • les totaux diffèrent d'une station à l'autre (3,67 et 5,98 GiB ; peut-être pas la même partition) : raisonner en espace libre et en vitesse de remplissage, pas sur un pourcentage fixe.
  • Pistes : l'espace libre du jour ; la vitesse de remplissage et les jours avant saturation (libre ÷ pente) ; les purges (sauts vers le haut).

Cellular : ce qu'on sait déjà

  • Collecteur (get_modem_info, commandes AT, une lecture du modem tous les 10 cycles, sinon la dernière réponse est réutilisée) :

    • rssi_dbm (AT+CSQ, de −113 à −51 dBm par pas de 2 ; 99 signifie inconnu) ;
    • ber_percent (AT+CSQ, une table de codes 0 à 7) ;
    • rsrq_dB (AT+CESQ, de −19,5 à −2,5 dB par pas de 0,5) ;
    • rsrp_dBm (AT+CESQ, de −140 à −43 dBm) ;
    • network_operator, network_technology (GSM, UMTS, LTE, E-UTRAN) ;
    • registration (AT+CEREG : home, roaming, searching, denied, not_registered, unknown) ;
    • link (up si le contexte PDP a une adresse IP, sinon down).

    Tout cela est exporté (SYNC_SPEC, rubrique modem), sauf ip, exporté à part en ip_address{interface="modem"}.

  • Instantanés :

    • WILDSTRUBEL : RSRP −81 dBm, RSRQ −13,5 dB, RSSI −51 dBm, BER 2,4 %, E-UTRAN, home, link up ;
    • VERMONT : RSRP −105 dBm, RSRQ −10 dB.
  • WEISSHORN (plages observées dans l'export du 2026-10-13, moyennes horaires) :

    • RSRP de −98,25 à −60,50 dBm ; RSRQ de −18,75 à −5,00 dB ; RSSI de −67,5 à −51,0 dBm (le plafond est atteint) ; BER de 0,53 à 13,00 % ;
    • les échantillons texte montrent link à up, registration à home, E-UTRAN et un seul opérateur. L'exploration dira s'ils changent jamais ;
    • toutes les métriques du modem de SYNC_SPEC sont là.
  • Manuel de la station et FAQ :

    • le « Link status » doit passer à « Up » ;
    • une connexion 4G peut mettre quelques minutes à s'établir après le démarrage ;
    • une installation en intérieur, en sous-sol, ou derrière du béton ou du métal affaiblit la réception ;
    • « Loss of remote connectivity does not necessarily mean that the measurement station itself has stopped operating ».
  • Pièges :

    • une donnée absente peut être l'anomalie elle-même, comme pour Energy : quand le lien tombe, les mesures du modem n'arrivent plus. Distinguer :
      • un trou pendant une coupure d'énergie, à croiser avec Energy ;
      • un trou avec la station alimentée, qui fait penser à un problème de lien ;
      • un trou rempli plus tard par une remontée différée ;
    • RSSI à −51 dBm veut dire « −51 dBm ou plus » : la valeur sature ;
    • si la lecture du modem échoue, le collecteur rapporte link = down avec toutes les valeurs vides : un lien down sans mesures n'est pas un signal faible ;
    • métriques texte (registration, link, network_technology) : ce sont des listes d'échantillons par heure. common.stations.load_csv ne lit que des nombres et ignore ces fichiers ;
    • moyennes de codes : ber_percent et rssi_dbm sont des codes AT (tables du collecteur) moyennés sur l'heure. Une moyenne comme 0,53 % ne correspond à aucun code ;
    • moyennes horaires de grandeurs en dB : la moyenne de valeurs en dB n'est pas la moyenne des puissances, et elle aplatit les décrochages brefs ;
    • aucun seuil de qualité (« bon » ou « faible ») n'a encore de source : il en faudra une (doc du module radio, opérateur, expert), ou bien comparer la station à son propre passé.
  • Pistes :

    • le niveau du jour (médiane du RSRP) comparé au passé de la station ;
    • la part des heures avec link = up ;
    • les heures sans mesure alors que la station est alimentée.

Le skill nouveau-domaine

Il se déclenche quand l'utilisateur apporte les données d'un nouveau point d'attention, ou veut une nouvelle notification. Il décrit sept étapes, et chacune s'arrête pour l'avis de l'utilisateur, qui décide si la suivante est utile (mémoire « simple d'abord »).

  1. Situer le domaine
    • Un nom en anglais, en un mot, et la question du domaine en une phrase.
    • Lire docs/<domaine>/domaine/point-de-depart.md. S'il n'existe pas, le créer avec les sections ci-dessus, et créer src/<domaine>/__init__.py.
  2. Recevoir les données
    • Les CSV vont dans data/<STATION>/.
    • Vérifier qu'ils se chargent avec common.stations.load_stations. Une métrique texte demande d'adapter le chargeur commun à ce moment-là.
    • Relever la couverture, le pas de temps et les trous.
  3. Explorer
    • Explorer par script, jamais en affichant les CSV.
    • Compléter la note avec les faits observés : plages, cycles, sauts.
    • Croiser avec Energy : un trou pendant une coupure d'énergie n'appartient pas à ce domaine.
  4. Recueillir les cas de référence
    • Demander à l'expert des périodes annotées, normales ou à problème, et les ranger dans docs/<domaine>/domaine/cas-annotes-par-l-expert.md.
    • Sans cas annotés, pas de verdict livré.
  5. Écrire les analyses
    • Une analyse par question, avec le skill nouvelle-analyse : fiche, code embarquable, constantes sourcées.
    • La première crée la page de comparaison du domaine, src/<domaine>/all_analyses.py (D-016).
  6. Produire le verdict du jour, c'est-à-dire le contrat de notification, ci-dessous.
    • Ce que veut dire Red pour ce domaine se décide avec l'utilisateur, et la combinaison des analyses aussi (une matrice tenue par l'utilisateur si elle est utile, comme pour Energy).
  7. Livrer et documenter
    • Écrire la figure src/<domaine>/final.py (D-021).
    • Ajouter la notification sur la maquette Home du support et un bloc dans la section Diagnostic du client. Pour les maquettes, proposer, puis attendre les consignes de l'utilisateur (mémoire « attendre les instructions »).
    • Si les maquettes ne parcourent pas encore une liste de domaines, faire ce passage d'abord, une seule fois (voir plus bas).
    • Écrire le guide docs/<domaine>/guide/, en deux couches, client et support (D-020).
    • Mettre à jour CLAUDE.md (tableau des analyses du domaine, état, commandes, carte) et ajouter une entrée dans docs/decisions.md pour le nouveau domaine.

Le skill renvoie vers nouvelle-analyse pour tout ce qui touche à une analyse, sans le répéter. En retour, nouvelle-analyse §1 renvoie vers nouveau-domaine quand le domaine est nouveau.

Le contrat de notification

Chaque domaine livré expose le même contrat que src/energy/day_color.py :

  • run(series) -> {analysis, rule, points}, avec un point par jour UTC, causal, anomaly = None, et la couleur dans facts.color : GREEN, ORANGE, RED, ou None (inconnu, gris) ;
  • HEADLINE = {"RED": "...", "ORANGE": "..."} : une phrase en anglais par couleur notifiée (D-023). Green ne notifie rien (D-025).

Energy le respecte déjà, à un détail près : sa HEADLINE est aujourd'hui dans maquettes/support/home.py.

Le passage des maquettes à plusieurs domaines (reporté)

  • Quand : au premier nouveau domaine qui atteint l'étape 7.
  • Quoi :
    • déplacer HEADLINE d'Energy dans src/energy/day_color.py ;
    • dans maquettes/support/home.py et la vue client, remplacer l'appel direct à energy.day_color par une liste DOMAINS = {"Energy": energy.day_color, "Storage": storage.day_color, …}, parcourue pour les notifications.
  • Ensuite, ajouter un domaine revient à ajouter une ligne.
  • Pourquoi pas maintenant : ce serait une liste à un seul élément, et il n'y aurait pas de second domaine pour vérifier que le contrat tient.
  • Le design s'y prête déjà : côté client, la section Diagnostic prévoit « un rectangle repliable par notification » (D-022), et côté support, chaque notification affiche son domaine (D-025).

Documentation à mettre à jour

  • docs/decisions.md : D-030, ci-dessous.
  • CLAUDE.md :
    • « État et prochaine étape » : Storage et Cellular ont leur structure et attendent les données ;
    • « Carte du dépôt » : docs/storage/, docs/cellular/, src/storage/, src/cellular/, le skill nouveau-domaine.
  • .claude/skills/nouvelle-analyse/SKILL.md §1 : une phrase qui renvoie vers nouveau-domaine.
  • CLAUDE.md, prochaine étape : explorer WEISSHORN (étape 3 du skill) pour storage et cellular, et repérer les autres champs qui mériteraient une notification.

Vérification

  • Il n'y a pas de code de calcul. On relit les deux notes de départ en les confrontant au collecteur, au manuel, à la FAQ et à metadata.md : chaque fait cite sa source, et aucun identifiant de station (SIM, IP) n'est recopié.
  • python3 src/energy/final.py et python3 src/energy/all_analyses.py tournent toujours : les nouveaux paquets ne cassent pas les imports.
  • Après la réception, load_stations(["data/WEISSHORN"]) charge le dossier sans erreur de doublon, et git status ne montre plus de Zone.Identifier.

Options écartées

  • La procédure dans un document de docs/ : Claude ne le trouve pas tout seul, et il recouvre en partie le skill nouvelle-analyse.
  • La procédure ajoutée au skill nouvelle-analyse : elle mélangerait deux échelles (une analyse, un domaine entier), et ce skill se charge à chaque nouvelle analyse.
  • Le nom network : il engloberait le VPN et les envois de données, qui relèvent de « Communication ».
  • Le passage des maquettes à plusieurs domaines dès maintenant : une liste à un seul élément, sans second domaine pour vérifier le contrat.
  • Créer tout de suite analyses/, guide/ ou des fiches vides : de l'échafaudage sans contenu, que git ne suit pas.

Texte de la décision D-030

D-030 — 2026-10-13 — Nouveaux domaines Storage et Cellular ; procédure nouveau-domaine ; contrat de notification

  • Statut : active. Complète D-026 (structure par domaine) et D-025 (notifications support) ; précise D-009 (jeu de travail par domaine).
  • Décision :
    • deux nouveaux domaines, rangés comme Energy : storage (espace disque) et cellular (signal 4G : niveau radio, enregistrement, lien). Chacun a src/<domaine>/ et une note de départ, docs/<domaine>/domaine/point-de-depart.md. Les analyses attendent l'exploration des données ;
    • leur jeu de travail est WEISSHORN : tout data/WEISSHORN/, sans restriction de dates (tous les champs de la caméra ; l'export du 2026-10-13 couvre 10 jours, un export plus long le remplacera) : VERMONT (D-009) n'a ni métrique de disque ni métrique de modem ;
    • la procédure pour ajouter un domaine, donc une notification, est le skill nouveau-domaine (sept étapes, de la réception des données à la livraison). Il renvoie vers nouvelle-analyse pour chaque analyse ;
    • contrat de notification : chaque domaine livré expose day_color.run(series), un point par jour avec facts.color (GREEN / ORANGE / RED / None), et une HEADLINE en anglais par couleur notifiée ;
    • le passage des maquettes à une liste de domaines se fait au premier nouveau domaine livré, pas avant.
  • Pourquoi : demande de l'utilisateur, qui veut le même travail qu'Energy pour d'autres points d'attention, et pouvoir ajouter vite de nouvelles notifications. Le collecteur mesure déjà l'espace disque et le signal du modem.
  • Options écartées : la procédure dans un document de docs/ (Claude ne le trouve pas seul) ou dans nouvelle-analyse (deux échelles mêlées) ; le nom network (VPN et envois relèvent de « Communication ») ; le passage multi-domaines dès maintenant (une liste à un seul élément, contrat non vérifié).
  • Conséquence :
    • HEADLINE d'Energy quittera maquettes/support/home.py pour src/energy/day_color.py lors du passage multi-domaines ;
    • le chargeur commun ne lit que des métriques numériques : il faudra l'adapter si l'on retient les métriques texte du modem (link, registration), qui sont des listes d'échantillons par heure ;
    • les copies identiques et les Zone.Identifier de WEISSHORN sont supprimés, et *:Zone.Identifier est ignoré par git.