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

115 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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).