11 KiB
Support-agent Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal : un skill /support qui, dans la conversation, prend le mail d'un client, lit les données locales de la station, répond à sa question seulement, et produit un dossier de cas support/…/ avec un mail prêt à envoyer et, si utile, un GIF des images.
Architecture : un skill (.claude/skills/support/SKILL.md), qui orchestre les outils de lecture existants (agents/diagnostic/outils/, skill lire-les-donnees, categories.py) et renvoie au déroulé de l'agent de diagnostic au lieu de le recopier ; un seul outil nouveau, gif.py, à côté des autres outils de lecture.
Tech Stack : Claude Code skill (markdown), Python 3.14, Pillow (déjà dans .venv, vient avec matplotlib).
Spec : docs/superpowers/specs/2026-10-28-support-agent-design.md
Global Constraints
- Le mail répond à la question du client et à elle seule ; tout le reste va dans
analyse.md, section « Hors question (pour Marc) ». - Station incertaine, ou données de la plage absentes de
data/: l'agent demande à Marc et s'arrête ; il ne pompe jamais. - Cibles nommées dans le mail par leur
sensor_namededata/(ex.101B) ; le nom de la plateforme du client en plus seulement si la correspondance est établie. - Heures en UTC, dites ; heure locale entre parenthèses si la capture du client est visiblement en heure locale.
- Pas de fuite interne dans le mail : codes C-xxx, noms des détecteurs, autres stations,
SIM_CCID,ip, vocabulaire de preuve anglais. - Dossier
support/<AAAA-MM-JJ>_<STATION>_<sujet>/:demande.md,capture.png,analyse.md,reponse.md,*.gif,*.png; versionné dans git. - Commit du dossier sur
masterseulement quand Marc dit que c'est bon (statutprêt à envoyer). - Lecture seule ailleurs : l'agent n'écrit que dans son dossier
support/…/. - Pas de tests automatisés (D-008) : vérification par lancement sur le cas réel (LENZSPITZE, nuit du 26 au 27.10).
- Le code (gif.py, skill, docs) n'est commité qu'après validation de Marc (règle « commiter sur validation »).
Review Focus
- Plage de plus de 150 images (ex. toute la période LENZSPITZE, ~290 images horaires) : le GIF en garde 150 au plus, à intervalle régulier, et le dit → Task 1, step 3.
- Plage sans aucune image (ex. LENZSPITZE les 24 et 25.10 n'ont pas de déplacements ; une plage hors des données) :
gif.pysort avec un message clair, sans GIF vide → Task 1, step 4. - Images à 3088×2064 : GIF réduit à
--largeur(900 px par défaut), sinon des dizaines de Mo dans git → Task 1, step 2 (taille imprimée). - Mail sans indice de station (cas de l'exemple) : le skill demande la station avant toute lecture → Task 2, step 2 (règle) et Task 3 (vérifiée sur le cas).
- Capture du client en heure locale : le mail dit UTC et l'heure locale entre parenthèses → Task 2 (règle) et Task 3 (relu sur le cas).
Task 1 : l'outil GIF
Files :
- Create :
agents/diagnostic/outils/gif.py
Interfaces :
-
Consumes :
donnees.trouver(dossier) -> dict(clé"images": chemins triés),donnees.heure_image(chemin) -> datetime | None,donnees.instant(texte) -> datetime,donnees.iso(t) -> str(agents/diagnostic/outils/donnees.py). -
Produces : la commande
.venv/bin/python agents/diagnostic/outils/gif.py <dossier> --debut T --fin T [--largeur 900] [--duree 700] [--max 150] [--sortie D]; imprime une ligne par image retenue (heure ISO UTC), puisGIF : <chemin>et sa taille en Mo. Fichier écrit :<sortie>/images_<AAAAMMJJTHHMMZ>_<AAAAMMJJTHHMMZ>.gif;--sortiepar défautout/diagnostic/(commevignettes.py). -
Step 1 : écrire
gif.pydans le style devignettes.py(docstring d'usage en tête,argparseavecdescription=__doc__,RACINE, import dedonnees). Images detrouver(dossier)["images"]dontheure_imageest entre--debutet--fininclus (les autres ignorées) ; au-delà de--max, garder--maximages à intervalle régulier (indicesround(i * (n - 1) / (max - 1))) et imprimer « N images sur M gardées » ; chaque image réduite à--largeurpx (proportions gardées,Image.LANCZOS), convertie en RGB ; texteAAAA-MM-JJ HH:MM UTCen bas à droite, blanc sur un rectangle noir, policeImageFont.load_default(size=…)proportionnelle à la largeur ;save(..., save_all=True, append_images=…, duration=--duree, loop=0). -
Step 2 : lancer sur la nuit du cas réel
Run : .venv/bin/python agents/diagnostic/outils/gif.py data/LENZSPITZE/ --debut 2026-10-26T18:00Z --fin 2026-10-27T08:00Z
Expected : une quinzaine d'heures imprimées de 2026-10-26T18:00Z à 2026-10-27T08:00Z, GIF : …/out/diagnostic/images_20261026T1800Z_20261027T0800Z.gif, taille de quelques Mo au plus. Regarder 2 ou 3 images sources avec Read pour vérifier que l'heure incrustée correspond au nom de fichier.
- Step 3 : vérifier la limite de 150
Run : .venv/bin/python agents/diagnostic/outils/gif.py data/LENZSPITZE/ --debut 2026-10-16T00:00Z --fin 2026-10-27T23:59Z
Expected : « 150 images sur gardées » avec M > 150, première heure 2026-10-16…, dernière 2026-10-27T23:00Z.
- Step 4 : vérifier la plage vide
Run : .venv/bin/python agents/diagnostic/outils/gif.py data/LENZSPITZE/ --debut 2026-11-10T00:00Z --fin 2026-11-11T00:00Z
Expected : sortie non nulle, message « Aucune image entre 2026-11-10T00:00Z et 2026-11-11T00:00Z dans data/LENZSPITZE/. » (avec la première et la dernière heure disponibles), aucun fichier écrit.
Task 2 : le skill /support
Files :
- Create :
.claude/skills/support/SKILL.md
Interfaces :
-
Consumes :
gif.py(Task 1) ; les outils delire-les-donnees;python3 vues-deplacements/detectors/categories.py <dossier>;agents/diagnostic/instructions.md§4 (étapes 4, 5, 7) et §5 (règles). -
Produces : la commande
/support <mail>(capture collée dans le même message). -
Step 1 : frontmatter
---
name: support
description: Répondre à la question d'un client sur un système AIMsight — lit le mail (et sa capture), les données locales de data/, répond à la question seule, et rédige un mail prêt à envoyer, avec un GIF des images si utile, dans un dossier de cas support/. Lancé par l'utilisateur, avec /support <mail>.
disable-model-invocation: true
argument-hint: "<mail du client> (capture collée dans le même message)"
---
-
Step 2 : corps du skill, en français, court (≈ 100 lignes), dans le style de
nouveau-casetrevue-cas, renvois plutôt que recopies. Sections et ce que chacune fixe :- Ton rôle : répondre à la question du client et à elle seule ; d'autres systèmes détectent les anomalies ; tu restes dans la conversation pour le peaufinage ; lecture seule sauf ton dossier. Commandes en plus de celles de
lire-les-donnees:categories.py,gif.py,mkdir,cp(la capture),date, etgit add/git commitdu seul dossier du cas, à la fin. - Comprendre la demande : station, plage, question reformulée, séries concernées (spec §3.2 étape 1). Station non certaine → demander à Marc, en un seul message avec tout ce qui manque (station, plage si ambiguë), et s'arrêter. La plateforme du client peut nommer et traiter autrement les mêmes données ; son axe peut être en heure locale.
- Vérifier les données :
inventaire.py data/<STATION>/ --debut T --fin T; déplacements ou images absents de la plage → le dire à Marc et s'arrêter, sans pomper. - Le dossier :
support/<date -u +%F>_<STATION>_<sujet>/;demande.md(mail tel quel,capture.pngcopiée parcpdepuis le chemin[Image: source: …]du message, sinon description ; station et comment établie ; plage ; question ;Statut : brouillon). - Enquêter : lire
lire-les-donneespuis suivreagents/diagnostic/instructions.md§4 étapes 2, 4, 5 et 7 (repérage aveccategories.py, faits, cas connus après les faits, réfutation) et §5 (règles, vocabulaire, asymétrie), limitées à la plage et à la question ; figures avec--sortie <dossier du cas>; images entières par Read aux moments des perturbations, plus une avant et une après ; dire ce que la cadence des images ne permet pas d'établir. - Écrire :
analyse.md(faits traçables avec leurs commandes, cas connu, réfutation, non établi, puis## Hors question (pour Marc), quelques lignes au plus) ;reponse.md(objet, corps, pièces jointes) selon la spec §3.3 : réponse d'abord en 1-2 phrases, puis les éléments repris par le client, honnête sur le non établi, cibles parsensor_name, UTC dit, langue et ton du client, signé du prénom par lequel il s'adresse au support, vocabulaire de preuve traduit en mots simples, aucune fuite interne (liste des Global Constraints) ; GIF pargif.py --sortie <dossier du cas>seulement s'il prouve mieux qu'une phrase, quelques images vérifiées par Read avant. - Montrer : le mail en entier dans la réponse, le GIF par
SendUserFile(sinon son chemin), et 2-3 lignes « hors question ». - Peaufiner : chaque retour de Marc → modifier
reponse.md(etanalyse.mdou le GIF si le fond change), remontrer le mail ; quand Marc dit que c'est bon :Statut : prêt à envoyer, puisgit add support/<dossier> && git commit -m "Support : <STATION>, <sujet>".
- Ton rôle : répondre à la question du client et à elle seule ; d'autres systèmes détectent les anomalies ; tu restes dans la conversation pour le peaufinage ; lecture seule sauf ton dossier. Commandes en plus de celles de
-
Step 3 : relire le skill face aux Global Constraints : chaque ligne des Global Constraints se retrouve dans une section ; corriger sinon.
Task 3 : le cas réel, puis la doc
Files :
-
Create :
support/2026-10-28_LENZSPITZE_<sujet>/(par le skill) -
Modify :
docs/decisions.md(entrée D-079 à la fin),CLAUDE.md(« État et prochaine étape » : une puce Support-agent ; « Carte du dépôt » :support/et.claude/skills/support/; « Commandes » : la lignegif.py) -
Step 1 : lancer
/supportsur le mail de l'exemple (spec §1), capture/tmp/claude-1000/-home-maxime-Support-Agent/f5dc4984-b923-4955-9c4e-a3a49ed7f862/images/1.png, en suivant le skill à la lettre. Expected : l'agent demande la station avant toute lecture ; après « LENZSPITZE », le dossier contientdemande.md,capture.png,analyse.md,reponse.mdet, si utile, un GIF de la nuit du 26 au 27.10 ; le mail répond à « activité sur les voies ? », cite les cibles parsensor_name, dit UTC, dit ce que des images horaires ne permettent pas d'établir, et ne contient rien hors question. -
Step 2 : peaufinage : au moins un retour de Marc appliqué par l'agent ; noter dans le skill toute consigne que ce retour révèle comme manquante.
-
Step 3 : doc : entrée D-079 (format ADR allégé du fichier : statut, décision, pourquoi, options écartées — sous-agent comme
diagnostic, adaptation de l'agent de diagnostic —, conséquence) ; mises à jour deCLAUDE.mdci-dessus, sans dépasser 200 lignes. -
Step 4 : commit, sur validation de Marc
git add agents/diagnostic/outils/gif.py .claude/skills/support/ docs/superpowers/specs/2026-10-28-support-agent-design.md docs/superpowers/plans/2026-10-28-support-agent.md docs/decisions.md CLAUDE.md
git commit -m "Support-agent: /support skill answers a client's question, with a GIF tool"
Le dossier support/… est commité par le skill lui-même quand Marc dit que c'est bon (Task 2, section 8).