Support-agent: /support skill answers a client's question, GIF tool, first case LENZSPITZE (draft)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
maximeandClaude Opus 5.5 committed 2026-10-28 11:12:28 +01:00
1 parent 425acbbad4
commit 02f2bf5369
12 files changed
+505 -3

No files matched your search

@@ -0,0 +1,114 @@
# 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 <M> 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**
```yaml
---
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**
```bash
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).