Files
Support-Agent/docs/superpowers/plans/2026-10-28-support-agent.md

11 KiB
Raw Permalink Blame History

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_name de data/ (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 master seulement quand Marc dit que c'est bon (statut prê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.py sort 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), puis GIF : <chemin> et sa taille en Mo. Fichier écrit : <sortie>/images_<AAAAMMJJTHHMMZ>_<AAAAMMJJTHHMMZ>.gif ; --sortie par défaut out/diagnostic/ (comme vignettes.py).

  • Step 1 : écrire gif.py dans le style de vignettes.py (docstring d'usage en tête, argparse avec description=__doc__, RACINE, import de donnees). Images de trouver(dossier)["images"] dont heure_image est entre --debut et --fin inclus (les autres ignorées) ; au-delà de --max, garder --max images à intervalle régulier (indices round(i * (n - 1) / (max - 1))) et imprimer « N images sur M gardées » ; chaque image réduite à --largeur px (proportions gardées, Image.LANCZOS), convertie en RGB ; texte AAAA-MM-JJ HH:MM UTC en bas à droite, blanc sur un rectangle noir, police ImageFont.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 de lire-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-cas et revue-cas, renvois plutôt que recopies. Sections et ce que chacune fixe :

    1. 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, et git add/git commit du seul dossier du cas, à la fin.
    2. 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.
    3. 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.
    4. Le dossier : support/<date -u +%F>_<STATION>_<sujet>/ ; demande.md (mail tel quel, capture.png copiée par cp depuis le chemin [Image: source: …] du message, sinon description ; station et comment établie ; plage ; question ; Statut : brouillon).
    5. Enquêter : lire lire-les-donnees puis suivre agents/diagnostic/instructions.md §4 étapes 2, 4, 5 et 7 (repérage avec categories.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.
    6. É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 par sensor_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 par gif.py --sortie <dossier du cas> seulement s'il prouve mieux qu'une phrase, quelques images vérifiées par Read avant.
    7. Montrer : le mail en entier dans la réponse, le GIF par SendUserFile (sinon son chemin), et 2-3 lignes « hors question ».
    8. Peaufiner : chaque retour de Marc → modifier reponse.md (et analyse.md ou le GIF si le fond change), remontrer le mail ; quand Marc dit que c'est bon : Statut : prêt à envoyer, puis git add support/<dossier> && git commit -m "Support : <STATION>, <sujet>".
  • 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 ligne gif.py)

  • Step 1 : lancer /support sur 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 contient demande.md, capture.png, analyse.md, reponse.md et, si utile, un GIF de la nuit du 26 au 27.10 ; le mail répond à « activité sur les voies ? », cite les cibles par sensor_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 de CLAUDE.md ci-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).