Plan the diagnostic agent implementation
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
5d639e5ee3
commit
7892fd9126
1 file changed
+890
@@ -0,0 +1,890 @@
|
||||
# Agent de diagnostic : plan d'implémentation
|
||||
|
||||
> **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 sous-agent Claude Code `diagnostic`, appelable à tout moment, qui diagnostique un dossier de `data/` (déplacements optiques et images) et écrit un rapport traçable.
|
||||
|
||||
**Architecture :** un point d'entrée `.claude/agents/diagnostic.md` (outils, modèle, `omitClaudeMd`) qui renvoie à `agents/diagnostic/instructions.md` (méthode, règles, format du rapport). Trois scripts en ligne de commande dans `agents/diagnostic/outils/` rendent des valeurs (inventaire, résumé chiffré, graphique PNG) ; l'agent juge et écrit son rapport dans `agents/diagnostic/rapports/`.
|
||||
|
||||
**Tech Stack :** Python 3.14, bibliothèque standard ; matplotlib dans `.venv` pour le seul graphique ; Claude Code (sous-agent, Opus 5.5).
|
||||
|
||||
**Spec :** `docs/agents/agent-diagnostic.md`
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- Python 3.14 ; `donnees.py`, `inventaire.py`, `resume.py` en bibliothèque standard seulement ; `graphique.py` importe matplotlib et se lance avec `.venv/bin/python`.
|
||||
- Toute heure est en UTC ; une heure saisie sans fuseau est lue en UTC.
|
||||
- Les outils rendent des valeurs, jamais des verdicts : aucun seuil de décision dans les outils.
|
||||
- Lecture seule : les outils n'écrivent que dans `out/diagnostic/` ; l'agent n'écrit que dans `agents/diagnostic/rapports/`.
|
||||
- Pas de tests automatisés (D-008) : chaque tâche se vérifie par des commandes et leurs sorties attendues, sur `data/PS_DES_COUDRES/`.
|
||||
- Documents en français, termes AIMsight en anglais.
|
||||
- `CLAUDE.md` reste sous 200 lignes (D-012).
|
||||
- Commits : message en anglais, terminé par `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>`.
|
||||
|
||||
## Review Focus
|
||||
|
||||
1. **Dossier sans export « advanced »** (ex. `data/WEISSHORN/`, métriques système seulement) : `inventaire.py` le dit ; `resume.py` et `graphique.py` s'arrêtent avec un message clair, sans trace d'erreur Python. Vérifié aux tâches 1, 2 et 3.
|
||||
2. **Fenêtre sans mesure** (`--debut` après la fin des données) : message clair, pas de tableau vide ni de graphique vide. Tâches 2 et 3.
|
||||
3. **Capteur ou colonne inconnu** : message qui liste les noms connus. Tâches 2 et 3.
|
||||
4. **Heure sans fuseau** (`--debut "2026-10-14 02:00"`) : même résultat qu'avec `2026-10-14T02:00Z`. Tâche 2.
|
||||
5. **Capteur rejeté sur toute la période** (PM_G, `corr_x` vide) : « rej » dans le tableau et « aucune valeur » au niveau habituel, pas de plantage. Tâche 2.
|
||||
|
||||
---
|
||||
|
||||
## Structure des fichiers
|
||||
|
||||
| Fichier | Rôle |
|
||||
|---|---|
|
||||
| `agents/diagnostic/outils/donnees.py` | Lecture : trouver les fichiers d'un dossier par type, charger l'export « advanced », heures d'image, conversion des instants (UTC) |
|
||||
| `agents/diagnostic/outils/inventaire.py` | Ce qui est disponible et ce qui manque |
|
||||
| `agents/diagnostic/outils/resume.py` | Niveau habituel par capteur et tableau par pas de temps |
|
||||
| `agents/diagnostic/outils/graphique.py` | PNG des séries dans `out/diagnostic/` |
|
||||
| `agents/diagnostic/instructions.md` | Méthode, règles, format du rapport (le « cerveau » de l'agent) |
|
||||
| `agents/diagnostic/README.md` | Doc humaine courte |
|
||||
| `agents/diagnostic/rapports/` | Un rapport par diagnostic (créé par l'agent) |
|
||||
| `.claude/agents/diagnostic.md` | Point d'entrée Claude Code |
|
||||
| `.devcontainer/devcontainer.json` | Ajout de matplotlib |
|
||||
| `docs/decisions.md`, `CLAUDE.md`, `docs/agents/agent-diagnostic.md` | D-046, carte et état, statut et résultats de la spec |
|
||||
|
||||
Les scripts s'importent entre eux par `from donnees import …` : Python ajoute le dossier du script lancé à `sys.path`, il n'y a donc rien à configurer.
|
||||
|
||||
---
|
||||
|
||||
### Task 1 : lecture des données et inventaire
|
||||
|
||||
**Files :**
|
||||
- Create : `agents/diagnostic/outils/donnees.py`
|
||||
- Create : `agents/diagnostic/outils/inventaire.py`
|
||||
|
||||
**Interfaces :**
|
||||
- Produces (`donnees.py`) :
|
||||
- `trouver(dossier: str) -> dict[str, list[str]]`, clés `advanced`, `horaire`, `images`, `autres` ;
|
||||
- `charger(dossier: str) -> dict[str, list[dict]]` : capteur → mesures triées par `t` ; mesure : `t` (datetime UTC), `pattern_type` (str), et les colonnes de `NUM` (float ou None) ;
|
||||
- `NUM: tuple[str, ...]` ;
|
||||
- `est_reference(mesures: list[dict]) -> bool` ; `rejetee(m: dict) -> bool` ;
|
||||
- `filtrer(mesures, debut: datetime | None, fin: datetime | None) -> list[dict]` (bornes incluses) ;
|
||||
- `heure_image(chemin: str) -> datetime | None` ; `instant(texte: str) -> datetime` ; `iso(t: datetime) -> str` (`AAAA-MM-JJTHH:MMZ`).
|
||||
|
||||
- [ ] **Step 1 : écrire `donnees.py`**
|
||||
|
||||
```python
|
||||
"""Lecture des données d'une station pour l'agent de diagnostic (bibliothèque standard).
|
||||
|
||||
Formats : docs/domaine/colonnes-des-deplacements.md. Toute heure est en UTC.
|
||||
"""
|
||||
import csv
|
||||
import glob
|
||||
import os
|
||||
import re
|
||||
from datetime import datetime, timezone
|
||||
|
||||
# Colonnes numériques de l'export « advanced » ; une case vide devient None.
|
||||
NUM = ("x", "y", "error_value", "error_threshold", "relative_x", "relative_y",
|
||||
"corr_x", "corr_y", "reproj_err", "sigma0")
|
||||
IMAGE_RE = re.compile(r"^(\d{8}T\d{4})Z_")
|
||||
|
||||
|
||||
def _entete(chemin):
|
||||
with open(chemin, newline="") as f:
|
||||
return next(csv.reader(f), [])
|
||||
|
||||
|
||||
def trouver(dossier):
|
||||
"""Dossier de station -> {'advanced', 'horaire', 'images', 'autres'} : chemins triés, sous-dossiers compris."""
|
||||
out = {"advanced": [], "horaire": [], "images": [], "autres": []}
|
||||
for p in sorted(glob.glob(os.path.join(dossier, "**", "*"), recursive=True)):
|
||||
if os.path.isdir(p):
|
||||
continue
|
||||
entete = _entete(p) if p.endswith(".csv") else []
|
||||
if p.lower().endswith((".jpg", ".jpeg", ".png")):
|
||||
out["images"].append(p)
|
||||
elif "sensor_name" in entete:
|
||||
out["advanced"].append(p)
|
||||
elif "timestamp" in entete:
|
||||
out["horaire"].append(p)
|
||||
else:
|
||||
out["autres"].append(p)
|
||||
return out
|
||||
|
||||
|
||||
def _nombre(v):
|
||||
v = v.strip()
|
||||
return float(v) if v else None
|
||||
|
||||
|
||||
def charger(dossier):
|
||||
"""Exports « advanced » du dossier -> {capteur: [mesure]}, triées par t, un seul relevé par instant.
|
||||
|
||||
Mesure : dict avec t (datetime UTC), pattern_type, et les colonnes de NUM (float ou None).
|
||||
"""
|
||||
par = {}
|
||||
for chemin in trouver(dossier)["advanced"]:
|
||||
with open(chemin, newline="") as f:
|
||||
for r in csv.DictReader(f):
|
||||
m = {c: _nombre(r[c]) for c in NUM}
|
||||
m["t"] = datetime.fromisoformat(r["time_utc"]).astimezone(timezone.utc)
|
||||
m["pattern_type"] = r["pattern_type"]
|
||||
par.setdefault(r["sensor_name"], {})[m["t"]] = m
|
||||
return {s: [d[t] for t in sorted(d)] for s, d in par.items()}
|
||||
|
||||
|
||||
def est_reference(mesures):
|
||||
"""Référence du réseau de compensation (pattern_type global_ref), sinon cible."""
|
||||
return mesures[0]["pattern_type"] == "global_ref"
|
||||
|
||||
|
||||
def rejetee(m):
|
||||
"""Mesure rejetée par la station (error_value au-dessus du seuil du capteur) : corr_x et corr_y vides."""
|
||||
return m["corr_x"] is None
|
||||
|
||||
|
||||
def filtrer(mesures, debut, fin):
|
||||
"""Mesures entre debut et fin inclus ; None = pas de borne."""
|
||||
return [m for m in mesures if (debut is None or m["t"] >= debut) and (fin is None or m["t"] <= fin)]
|
||||
|
||||
|
||||
def heure_image(chemin):
|
||||
"""'20261013T1200Z_10167931.jpg' -> datetime UTC ; None si le nom ne suit pas ce format (D-045)."""
|
||||
m = IMAGE_RE.match(os.path.basename(chemin))
|
||||
return datetime.strptime(m.group(1), "%Y%m%dT%H%M").replace(tzinfo=timezone.utc) if m else None
|
||||
|
||||
|
||||
def instant(texte):
|
||||
"""'2026-10-13T23:00Z' ou '2026-10-13 23:00' -> datetime UTC ; une heure sans fuseau est lue en UTC."""
|
||||
t = datetime.fromisoformat(texte)
|
||||
return t.astimezone(timezone.utc) if t.tzinfo else t.replace(tzinfo=timezone.utc)
|
||||
|
||||
|
||||
def iso(t):
|
||||
return t.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%MZ")
|
||||
```
|
||||
|
||||
- [ ] **Step 2 : écrire `inventaire.py`**
|
||||
|
||||
```python
|
||||
"""Inventaire d'un dossier de station : ce qui est disponible, ce qui manque.
|
||||
|
||||
Usage : python3 agents/diagnostic/outils/inventaire.py data/PS_DES_COUDRES/
|
||||
Rend des valeurs, pas de verdict.
|
||||
"""
|
||||
import statistics
|
||||
import sys
|
||||
from datetime import timedelta
|
||||
|
||||
from donnees import charger, est_reference, heure_image, iso, rejetee, trouver
|
||||
|
||||
|
||||
def fichiers(f):
|
||||
print(f"Exports « advanced » (source des mesures) : {len(f['advanced'])}")
|
||||
for p in f["advanced"]:
|
||||
print(f" {p}")
|
||||
print(f"Exports horaires : {len(f['horaire'])} (non lus par les outils : moyennes horaires, "
|
||||
"heure locale sans fuseau ; voir docs/domaine/colonnes-des-deplacements.md)")
|
||||
for p in f["horaire"]:
|
||||
print(f" {p}")
|
||||
print(f"Autres fichiers : {len(f['autres'])}")
|
||||
for p in f["autres"]:
|
||||
print(f" {p}")
|
||||
|
||||
|
||||
def images(chemins):
|
||||
heures = sorted(h for h in map(heure_image, chemins) if h)
|
||||
print(f"Images : {len(chemins)}" + (f", du {iso(heures[0])} au {iso(heures[-1])}" if heures else ""))
|
||||
inconnues = [p for p in chemins if heure_image(p) is None]
|
||||
if inconnues:
|
||||
print(f" noms sans heure reconnue : {len(inconnues)}")
|
||||
if heures:
|
||||
manquantes = []
|
||||
for a, b in zip(heures, heures[1:]):
|
||||
h = a + timedelta(hours=1)
|
||||
while h < b:
|
||||
manquantes.append(iso(h))
|
||||
h += timedelta(hours=1)
|
||||
print(f" heures pleines sans image entre la première et la dernière : {', '.join(manquantes) or 'aucune'}")
|
||||
|
||||
|
||||
def mesures(par):
|
||||
if not par:
|
||||
print("\nAucune mesure : pas d'export « advanced » dans ce dossier.")
|
||||
return
|
||||
instants = sorted({m["t"] for ms in par.values() for m in ms})
|
||||
cadence = statistics.median(b - a for a, b in zip(instants, instants[1:]))
|
||||
print(f"\nPériode des mesures : {iso(instants[0])} → {iso(instants[-1])}, {len(instants)} instants")
|
||||
print(f"Cadence (pas médian) : {cadence.total_seconds() / 60:.0f} min")
|
||||
trous = [(a, b, round((b - a) / cadence) - 1) for a, b in zip(instants, instants[1:])]
|
||||
trous = [x for x in trous if x[2] > 0]
|
||||
print(f"Mesures manquantes (instants absents de la cadence) : {sum(n for *_, n in trous)}")
|
||||
for a, b, n in trous:
|
||||
print(f" entre {iso(a)} et {iso(b)} : {n}")
|
||||
noms = sorted(par, key=lambda s: (not est_reference(par[s]), s))
|
||||
refs = [s for s in noms if est_reference(par[s])]
|
||||
print(f"\nCapteurs : {len(par)} ({len(refs)} références, {len(par) - len(refs)} cibles)")
|
||||
print(f"{'capteur':10} {'type':10} {'motif':11} {'seuil':>5} {'mesures':>7} {'rejetées':>8}")
|
||||
for s in noms:
|
||||
ms = par[s]
|
||||
seuil = "/".join(f"{x:g}" for x in sorted({m['error_threshold'] for m in ms}))
|
||||
print(f"{s:10} {'référence' if est_reference(ms) else 'cible':10} {ms[0]['pattern_type']:11} "
|
||||
f"{seuil:>5} {len(ms):7} {sum(map(rejetee, ms)):8}")
|
||||
|
||||
|
||||
def main(dossier):
|
||||
print(f"Dossier : {dossier}")
|
||||
f = trouver(dossier)
|
||||
fichiers(f)
|
||||
images(f["images"])
|
||||
mesures(charger(dossier))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
if len(sys.argv) != 2:
|
||||
sys.exit(__doc__)
|
||||
main(sys.argv[1])
|
||||
```
|
||||
|
||||
- [ ] **Step 3 : vérifier sur PS des Coudres**
|
||||
|
||||
Run : `python3 agents/diagnostic/outils/inventaire.py data/PS_DES_COUDRES/`
|
||||
|
||||
Expected (chiffres établis à la main le 2026-10-14, spec §7) :
|
||||
```
|
||||
Exports « advanced » (source des mesures) : 1
|
||||
Exports horaires : 1 (...)
|
||||
Autres fichiers : 0
|
||||
Images : 24, du 2026-10-13T12:00Z au 2026-10-14T11:00Z
|
||||
heures pleines sans image entre la première et la dernière : aucune
|
||||
|
||||
Période des mesures : 2026-10-08T22:00Z → 2026-10-14T09:45Z, 525 instants
|
||||
Cadence (pas médian) : 15 min
|
||||
Mesures manquantes (instants absents de la cadence) : 3
|
||||
entre 2026-10-09T11:45Z et 2026-10-09T12:15Z : 1
|
||||
entre 2026-10-10T10:30Z et 2026-10-10T11:00Z : 1
|
||||
entre 2026-10-14T09:15Z et 2026-10-14T09:45Z : 1
|
||||
|
||||
Capteurs : 15 (3 références, 12 cibles)
|
||||
```
|
||||
puis `REF_CT` seuil 0.45, `REF_D` et `REF_G` 0.7, rejetées 0 ; `PM_G` seuil 0.3, mesures 525, rejetées 525 ; toutes les autres cibles seuil 0.7, rejetées 0.
|
||||
|
||||
- [ ] **Step 4 : vérifier un dossier sans export « advanced » (Review Focus 1)**
|
||||
|
||||
Run : `python3 agents/diagnostic/outils/inventaire.py data/WEISSHORN/`
|
||||
|
||||
Expected : `Exports « advanced » (source des mesures) : 0`, `Autres fichiers : 27` suivis des 27 CSV, `Images : 0`, puis `Aucune mesure : pas d'export « advanced » dans ce dossier.` Pas de trace d'erreur.
|
||||
|
||||
Run : `python3 agents/diagnostic/outils/inventaire.py` (sans argument). Expected : le docstring d'usage, code de sortie 1.
|
||||
|
||||
- [ ] **Step 5 : commit**
|
||||
|
||||
```bash
|
||||
git add agents/diagnostic/outils/donnees.py agents/diagnostic/outils/inventaire.py
|
||||
git commit -m "Add the diagnostic agent's data reader and inventory tool (D-046)" -m "Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2 : résumé chiffré
|
||||
|
||||
**Files :**
|
||||
- Create : `agents/diagnostic/outils/resume.py`
|
||||
|
||||
**Interfaces :**
|
||||
- Consumes : `charger`, `est_reference`, `filtrer`, `instant`, `iso`, `rejetee` (Task 1).
|
||||
- Produces : CLI `resume.py <dossier> [--colonne C] [--stat median|min|max] [--pas 1h] [--capteurs A,B] [--debut T] [--fin T]` ; `COLONNES` (aussi recopié dans `graphique.py`).
|
||||
|
||||
- [ ] **Step 1 : écrire `resume.py`**
|
||||
|
||||
```python
|
||||
"""Résumé chiffré compact des séries d'un export « advanced », pour l'agent de diagnostic.
|
||||
|
||||
Usage : python3 agents/diagnostic/outils/resume.py data/PS_DES_COUDRES/ [--colonne error_value]
|
||||
[--stat median|min|max] [--pas 1h] [--capteurs REF_G,REF_D] [--debut 2026-10-13T00:00Z] [--fin ...]
|
||||
|
||||
1. Niveau habituel de chaque capteur sur toute la période : médiane, MAD (écart absolu médian), min, max.
|
||||
2. Tableau : une ligne par pas de temps (début du pas, UTC), une colonne par capteur, la statistique
|
||||
choisie sur les mesures du pas. « rej » : toutes les mesures du pas sont rejetées ; « - » : aucune mesure.
|
||||
Rend des valeurs, pas de verdict.
|
||||
"""
|
||||
import argparse
|
||||
import re
|
||||
import statistics
|
||||
import sys
|
||||
from datetime import timedelta
|
||||
|
||||
from donnees import charger, est_reference, filtrer, instant, iso, rejetee
|
||||
|
||||
COLONNES = ("error_value", "corr_x", "corr_y", "relative_x", "relative_y", "x", "y", "sigma0", "reproj_err")
|
||||
STATS = {"median": statistics.median, "min": min, "max": max}
|
||||
|
||||
|
||||
def duree(texte):
|
||||
"""'15min', '1h', '6h', '1d' -> timedelta."""
|
||||
m = re.fullmatch(r"(\d+)(min|h|d)", texte)
|
||||
if not m:
|
||||
raise argparse.ArgumentTypeError(f"pas invalide : {texte!r} (ex. 15min, 1h, 1d)")
|
||||
n, unite = int(m.group(1)), m.group(2)
|
||||
return {"min": timedelta(minutes=n), "h": timedelta(hours=n), "d": timedelta(days=n)}[unite]
|
||||
|
||||
|
||||
def valeurs(ms, col):
|
||||
return [m[col] for m in ms if m[col] is not None]
|
||||
|
||||
|
||||
def main():
|
||||
a = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
a.add_argument("dossier")
|
||||
a.add_argument("--colonne", default="error_value", choices=COLONNES)
|
||||
a.add_argument("--stat", default="median", choices=STATS)
|
||||
a.add_argument("--pas", default="1h", type=duree)
|
||||
a.add_argument("--capteurs", help="liste séparée par des virgules (défaut : tous)")
|
||||
a.add_argument("--debut", type=instant)
|
||||
a.add_argument("--fin", type=instant)
|
||||
o = a.parse_args()
|
||||
|
||||
par = charger(o.dossier)
|
||||
if not par:
|
||||
sys.exit(f"Aucun export « advanced » dans {o.dossier} (voir inventaire.py).")
|
||||
noms = o.capteurs.split(",") if o.capteurs else sorted(par, key=lambda s: (not est_reference(par[s]), s))
|
||||
inconnus = [s for s in noms if s not in par]
|
||||
if inconnus:
|
||||
sys.exit(f"Capteurs absents : {', '.join(inconnus)}. Présents : {', '.join(sorted(par))}.")
|
||||
|
||||
t0 = min(m["t"] for s in noms for m in par[s]).replace(hour=0, minute=0, second=0, microsecond=0)
|
||||
cases = {}
|
||||
for s in noms:
|
||||
for m in filtrer(par[s], o.debut, o.fin):
|
||||
debut_du_pas = t0 + ((m["t"] - t0) // o.pas) * o.pas
|
||||
cases.setdefault(debut_du_pas, {}).setdefault(s, []).append(m)
|
||||
if not cases:
|
||||
sys.exit("Aucune mesure dans la fenêtre demandée.")
|
||||
|
||||
print(f"Colonne : {o.colonne}. Niveau habituel sur toute la période (mesures non vides) :")
|
||||
print(f"{'capteur':10} {'n':>5} {'médiane':>9} {'MAD':>8} {'min':>9} {'max':>9}")
|
||||
for s in noms:
|
||||
v = valeurs(par[s], o.colonne)
|
||||
if not v:
|
||||
print(f"{s:10} {0:5} (aucune valeur)")
|
||||
continue
|
||||
med = statistics.median(v)
|
||||
mad = statistics.median(abs(x - med) for x in v)
|
||||
print(f"{s:10} {len(v):5} {med:9.4f} {mad:8.4f} {min(v):9.4f} {max(v):9.4f}")
|
||||
|
||||
print(f"\n{o.stat} de {o.colonne} par pas de {o.pas} (début du pas, UTC) :")
|
||||
print(f"{'début':17} " + " ".join(f"{s:>8}" for s in noms))
|
||||
for k in sorted(cases):
|
||||
cellules = []
|
||||
for s in noms:
|
||||
ms = cases[k].get(s, [])
|
||||
v = valeurs(ms, o.colonne)
|
||||
if v:
|
||||
cellules.append(f"{STATS[o.stat](v):8.3f}")
|
||||
else:
|
||||
cellules.append(f"{'rej' if ms and all(map(rejetee, ms)) else '-':>8}")
|
||||
print(f"{iso(k):17} " + " ".join(cellules))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
```
|
||||
|
||||
- [ ] **Step 2 : vérifier le pic de la seconde nuit**
|
||||
|
||||
Run : `python3 agents/diagnostic/outils/resume.py data/PS_DES_COUDRES/ --stat max --capteurs REF_CT,REF_G,REF_D --debut 2026-10-13T22:00Z --fin 2026-10-14T06:00Z`
|
||||
|
||||
Expected :
|
||||
- niveau habituel : `REF_G` médiane ≈ 0.084, max ≈ 0.674 ; `REF_D` médiane ≈ 0.132, max ≈ 0.692 ; `REF_CT` médiane ≈ 0.151, max ≈ 0.226 ;
|
||||
- tableau de `2026-10-13T22:00Z` à `2026-10-14T05:00Z` (8 lignes) ; à la ligne `2026-10-14T02:00Z`, `REF_G` ≈ 0.670 et `REF_D` ≈ 0.690 ; `REF_CT` reste sous 0.23 sur toutes les lignes.
|
||||
|
||||
- [ ] **Step 3 : vérifier les cas limites (Review Focus 2 à 5)**
|
||||
|
||||
Run : `python3 agents/diagnostic/outils/resume.py data/PS_DES_COUDRES/ --colonne corr_x --capteurs PM_G,BJ_C --pas 1d`
|
||||
Expected : `PM_G` « 0 (aucune valeur) » au niveau habituel, « rej » sur chaque ligne ; `BJ_C` des valeurs (médiane ≈ 0.258).
|
||||
|
||||
Run : `python3 agents/diagnostic/outils/resume.py data/PS_DES_COUDRES/ --capteurs REF_G --debut "2026-10-14 02:00" --fin "2026-10-14 02:59"` puis la même commande avec `--debut 2026-10-14T02:00Z --fin 2026-10-14T02:59Z`.
|
||||
Expected : sorties identiques (une ligne `2026-10-14T02:00Z`).
|
||||
|
||||
Run : `python3 agents/diagnostic/outils/resume.py data/PS_DES_COUDRES/ --debut 2027-01-01T00:00Z`
|
||||
Expected : `Aucune mesure dans la fenêtre demandée.`, code 1.
|
||||
|
||||
Run : `python3 agents/diagnostic/outils/resume.py data/PS_DES_COUDRES/ --capteurs REF_X`
|
||||
Expected : `Capteurs absents : REF_X. Présents : BJ_C, BJ_D, …`, code 1.
|
||||
|
||||
Run : `python3 agents/diagnostic/outils/resume.py data/WEISSHORN/`
|
||||
Expected : `Aucun export « advanced » dans data/WEISSHORN/ (voir inventaire.py).`, code 1.
|
||||
|
||||
Run : `python3 agents/diagnostic/outils/resume.py data/PS_DES_COUDRES/ --pas 2x`
|
||||
Expected : erreur argparse `pas invalide : '2x' (ex. 15min, 1h, 1d)`.
|
||||
|
||||
- [ ] **Step 4 : commit**
|
||||
|
||||
```bash
|
||||
git add agents/diagnostic/outils/resume.py
|
||||
git commit -m "Add the diagnostic agent's numeric summary tool (D-046)" -m "Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3 : matplotlib et graphique
|
||||
|
||||
**Files :**
|
||||
- Create : `agents/diagnostic/outils/graphique.py`
|
||||
- Modify : `.devcontainer/devcontainer.json` (`postCreateCommand`)
|
||||
|
||||
**Interfaces :**
|
||||
- Consumes : `charger`, `est_reference`, `filtrer`, `instant` (Task 1).
|
||||
- Produces : CLI `.venv/bin/python agents/diagnostic/outils/graphique.py <dossier> [--capteurs A,B] [--colonnes C1,C2] [--debut T] [--fin T]`, qui imprime le chemin du PNG écrit dans `out/diagnostic/`.
|
||||
|
||||
- [ ] **Step 1 : installer matplotlib dans `.venv` et le dev container**
|
||||
|
||||
Run : `.venv/bin/pip install matplotlib && .venv/bin/python -c "import matplotlib; print(matplotlib.__version__)"`
|
||||
Expected : un numéro de version.
|
||||
|
||||
Dans `.devcontainer/devcontainer.json`, remplacer :
|
||||
```json
|
||||
"postCreateCommand": "pip install --user plotly"
|
||||
```
|
||||
par :
|
||||
```json
|
||||
"postCreateCommand": "pip install --user plotly matplotlib"
|
||||
```
|
||||
|
||||
- [ ] **Step 2 : écrire `graphique.py`**
|
||||
|
||||
```python
|
||||
"""Graphique PNG des séries d'un export « advanced », pour que l'agent de diagnostic les regarde.
|
||||
|
||||
Usage : .venv/bin/python agents/diagnostic/outils/graphique.py data/PS_DES_COUDRES/
|
||||
[--capteurs REF_G,REF_D] [--colonnes error_value,corr_x,corr_y] [--debut ...] [--fin ...]
|
||||
Un panneau par colonne, une courbe par capteur, heures UTC. Imprime le chemin du PNG (out/diagnostic/).
|
||||
"""
|
||||
import argparse
|
||||
import os
|
||||
import sys
|
||||
|
||||
import matplotlib
|
||||
|
||||
matplotlib.use("Agg")
|
||||
import matplotlib.dates as mdates # noqa: E402
|
||||
import matplotlib.pyplot as plt # noqa: E402
|
||||
|
||||
from donnees import charger, est_reference, filtrer, instant # noqa: E402
|
||||
|
||||
RACINE = os.path.normpath(os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", ".."))
|
||||
COLONNES = ("error_value", "corr_x", "corr_y", "relative_x", "relative_y", "x", "y", "sigma0", "reproj_err")
|
||||
|
||||
|
||||
def borne(t, defaut):
|
||||
return t.strftime("%Y%m%dT%H%MZ") if t else defaut
|
||||
|
||||
|
||||
def main():
|
||||
a = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
a.add_argument("dossier")
|
||||
a.add_argument("--capteurs", help="liste séparée par des virgules (défaut : tous)")
|
||||
a.add_argument("--colonnes", default="error_value,corr_x,corr_y")
|
||||
a.add_argument("--debut", type=instant)
|
||||
a.add_argument("--fin", type=instant)
|
||||
o = a.parse_args()
|
||||
|
||||
par = charger(o.dossier)
|
||||
if not par:
|
||||
sys.exit(f"Aucun export « advanced » dans {o.dossier} (voir inventaire.py).")
|
||||
noms = o.capteurs.split(",") if o.capteurs else sorted(par, key=lambda s: (not est_reference(par[s]), s))
|
||||
colonnes = o.colonnes.split(",")
|
||||
for demandes, connus, quoi in ((noms, par, "Capteurs"), (colonnes, COLONNES, "Colonnes")):
|
||||
absents = [x for x in demandes if x not in connus]
|
||||
if absents:
|
||||
sys.exit(f"{quoi} inconnus : {', '.join(absents)}. Connus : {', '.join(sorted(connus))}.")
|
||||
series = {s: filtrer(par[s], o.debut, o.fin) for s in noms}
|
||||
if not any(series.values()):
|
||||
sys.exit("Aucune mesure dans la fenêtre demandée.")
|
||||
|
||||
fig, axes = plt.subplots(len(colonnes), 1, sharex=True, figsize=(14, 3.2 * len(colonnes)), squeeze=False)
|
||||
couleurs = plt.get_cmap("tab20").colors
|
||||
for ax, col in zip(axes[:, 0], colonnes):
|
||||
for i, s in enumerate(noms):
|
||||
ms = [m for m in series[s] if m[col] is not None]
|
||||
ax.plot([m["t"] for m in ms], [m[col] for m in ms], ".-", ms=2, lw=0.7,
|
||||
color=couleurs[i % len(couleurs)], label=s)
|
||||
ax.set_ylabel(col)
|
||||
ax.grid(alpha=0.3)
|
||||
axes[0, 0].legend(loc="upper left", bbox_to_anchor=(1.0, 1.0), fontsize=8)
|
||||
axes[-1, 0].xaxis.set_major_formatter(mdates.DateFormatter("%d/%m\n%H:%MZ"))
|
||||
station = os.path.basename(os.path.normpath(o.dossier))
|
||||
fig.suptitle(f"{station} : {', '.join(colonnes)} (heures UTC)")
|
||||
|
||||
dossier_sortie = os.path.join(RACINE, "out", "diagnostic")
|
||||
os.makedirs(dossier_sortie, exist_ok=True)
|
||||
qui = "-".join(noms) if o.capteurs else "tous"
|
||||
sortie = os.path.join(dossier_sortie, f"{station}_{'-'.join(colonnes)}_{qui}_"
|
||||
f"{borne(o.debut, 'debut')}_{borne(o.fin, 'fin')}.png")
|
||||
fig.savefig(sortie, dpi=100, bbox_inches="tight")
|
||||
print(sortie)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
```
|
||||
|
||||
- [ ] **Step 3 : vérifier le graphique**
|
||||
|
||||
Run : `.venv/bin/python agents/diagnostic/outils/graphique.py data/PS_DES_COUDRES/ --capteurs REF_CT,REF_G,REF_D --colonnes error_value`
|
||||
Expected : imprime `/home/maxime/Support-Agent/out/diagnostic/PS_DES_COUDRES_error_value_REF_CT-REF_G-REF_D_debut_fin.png`. Ouvrir le PNG avec Read : trois courbes, deux bosses nocturnes de `REF_G` et `REF_D` (13/10 et 14/10), `REF_CT` plate, axe des temps lisible en UTC.
|
||||
|
||||
Run : `.venv/bin/python agents/diagnostic/outils/graphique.py data/PS_DES_COUDRES/`
|
||||
Expected : PNG des 15 capteurs sur trois panneaux (`error_value`, `corr_x`, `corr_y`), légende à droite ; PM_G absente des panneaux `corr_*`.
|
||||
|
||||
- [ ] **Step 4 : vérifier les cas limites (Review Focus 1 à 3)**
|
||||
|
||||
Run : `.venv/bin/python agents/diagnostic/outils/graphique.py data/WEISSHORN/` → `Aucun export « advanced » …`, code 1.
|
||||
Run : `.venv/bin/python agents/diagnostic/outils/graphique.py data/PS_DES_COUDRES/ --colonnes erreur` → `Colonnes inconnus : erreur. Connus : …`, code 1.
|
||||
Run : `.venv/bin/python agents/diagnostic/outils/graphique.py data/PS_DES_COUDRES/ --debut 2027-01-01T00:00Z` → `Aucune mesure dans la fenêtre demandée.`, code 1.
|
||||
|
||||
- [ ] **Step 5 : commit**
|
||||
|
||||
```bash
|
||||
git add agents/diagnostic/outils/graphique.py .devcontainer/devcontainer.json
|
||||
git commit -m "Add the diagnostic agent's plot tool and matplotlib (D-046)" -m "Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4 : instructions, point d'entrée et README
|
||||
|
||||
**Files :**
|
||||
- Create : `agents/diagnostic/instructions.md`
|
||||
- Create : `.claude/agents/diagnostic.md`
|
||||
- Create : `agents/diagnostic/README.md`
|
||||
|
||||
**Interfaces :**
|
||||
- Consumes : les trois CLI des tâches 1 à 3, telles que définies plus haut.
|
||||
- Produces : le sous-agent `diagnostic`, chargé par Claude Code au démarrage d'une session.
|
||||
|
||||
- [ ] **Step 1 : écrire `agents/diagnostic/instructions.md`**
|
||||
|
||||
````markdown
|
||||
# Instructions de l'agent de diagnostic
|
||||
|
||||
Tu diagnostiques les données d'une station AIMsight. Une caméra suit des cibles (réflecteurs) fixées sur un ouvrage ; le mouvement de la caméra elle-même est compensé grâce à des cibles de référence, supposées fixes. Tu trouves ce qui sort de l'ordinaire, tu l'expliques avec des preuves, et tu dis ce qui reste non établi. Tu ne modifies rien.
|
||||
|
||||
## 1. La demande
|
||||
|
||||
Tu reçois un dossier de `data/` (ex. `data/PS_DES_COUDRES/`) et, parfois, une question.
|
||||
|
||||
- **Sans question : scan.** Trouve les événements de toute la période et explique chacun.
|
||||
- **Avec une question : enquête.** Concentre-toi sur la fenêtre et les capteurs concernés ; la période entière sert de référence.
|
||||
- Si le dossier n'existe pas ou ne contient aucun export « advanced », dis-le dans ta réponse et n'écris pas de rapport.
|
||||
|
||||
## 2. Ce que tu as le droit de lire
|
||||
|
||||
Seulement :
|
||||
|
||||
- les fichiers du dossier fourni, par tes outils (§3), et ses images avec Read ;
|
||||
- `docs/domaine/colonnes-des-deplacements.md` : formats des exports et sens des colonnes. **Lis-le en premier** ;
|
||||
- `docs/domaine/pieges-des-donnees.md` ;
|
||||
- `docs/aimsight/AIMsight_agentic_support_project_context.md`, sections 4 (chaîne de dépendance), 12 (familles d'hypothèses) et 13 (*support query workflow*) ;
|
||||
- `docs/aimsight/AIMsight_reference_quality_event_explainer_roadmap.md`, section 4.3 (classifications) ;
|
||||
- `docs/aimsight/AIMsight FAQ.pdf`, pour `error` : `pdftotext -layout "docs/aimsight/AIMsight FAQ.pdf" - | grep -n -i -B2 -A12 'error value'`.
|
||||
|
||||
Pour un long fichier AIMsight, trouve la section avec `grep -n '^#' <fichier>`, puis lis-la seule (Read avec `offset` et `limit`).
|
||||
|
||||
**Ne lis rien d'autre** : ni `CLAUDE.md`, ni `docs/decisions.md`, ni les autres documents du projet, ni les rapports de `agents/diagnostic/rapports/`. Ils peuvent contenir des conclusions sur ces données ; ton diagnostic doit partir des données. Tu listes dans ton rapport tout ce que tu as lu.
|
||||
|
||||
## 3. Tes outils
|
||||
|
||||
Lance-les depuis la racine du dépôt. Ils rendent des valeurs, jamais des verdicts : c'est toi qui juges.
|
||||
|
||||
| Commande | Ce qu'elle rend |
|
||||
|---|---|
|
||||
| `python3 agents/diagnostic/outils/inventaire.py <dossier>` | Fichiers par type, images (heures couvertes), période, cadence, mesures manquantes, capteurs (référence ou cible, seuil d'erreur, mesures rejetées) |
|
||||
| `python3 agents/diagnostic/outils/resume.py <dossier> [--colonne C] [--stat median\|min\|max] [--pas 1h] [--capteurs A,B] [--debut T] [--fin T]` | Niveau habituel de chaque capteur sur toute la période (médiane, MAD, min, max), puis un tableau par pas de temps. Colonnes : `error_value`, `corr_x`, `corr_y`, `relative_x`, `relative_y`, `x`, `y`, `sigma0`, `reproj_err` |
|
||||
| `.venv/bin/python agents/diagnostic/outils/graphique.py <dossier> [--capteurs A,B] [--colonnes C1,C2] [--debut T] [--fin T]` | Un PNG des séries ; il imprime son chemin. **Regarde-le avec Read** : tu lis mieux un graphique qu'un tableau |
|
||||
| `ls <dossier>/images/`, puis Read sur `<AAAAMMJJ>T<HHMM>Z_*.jpg` | L'image de la caméra à cette heure (UTC). Les colonnes `x` et `y` (pixels) situent chaque capteur sur l'image |
|
||||
|
||||
Instants : `2026-10-13T23:00Z` (une heure sans fuseau est lue en UTC). Bash ne sert qu'à lancer ces outils, `ls`, `grep`, `pdftotext` et `date`. N'écris aucun autre script.
|
||||
|
||||
## 4. Déroulé
|
||||
|
||||
1. **Inventaire** (`inventaire.py`) : ce qui est disponible, ce qui manque, et ce que ce manque empêche de conclure (par exemple, sans métriques système, un arrêt de la station ne peut pas être écarté).
|
||||
2. **Repérage** : commence large, puis zoome.
|
||||
- `graphique.py` sur tous les capteurs, puis `resume.py` sur `error_value`, `corr_x`, `corr_y` avec un pas large (6h ou 1d), puis 1h ou 15min sur les fenêtres intéressantes ;
|
||||
- compare chaque capteur **à son propre niveau habituel** (sa médiane et sa MAD), jamais à un seuil absolu ;
|
||||
- un seuil de repérage (ex. « au-dessus de médiane + 6 MAD ») est un choix d'exploration : annonce-le, et ne t'en sers jamais comme critère de conclusion.
|
||||
3. **Faits**, pour chaque événement repéré :
|
||||
- début, fin, durée ; capteurs touchés : cibles ou références, combien, lesquels, ensemble ou non ;
|
||||
- amplitude face au niveau habituel ; retour à la normale ;
|
||||
- déplacement associé (`corr_x`, `corr_y`) ou non ; mesures rejetées ;
|
||||
- images autour de l'instant, s'il y en a : regarde au moins une image pendant et une hors de l'événement, à la même heure de la journée si possible.
|
||||
4. **Hypothèses** : prends-les dans les familles de la section 12 du contexte support, plus le mouvement réel de l'ouvrage. Pour chacune, ce qui la soutient et ce qui la contredit.
|
||||
5. **Réfutation obligatoire** de l'hypothèse principale : cherche le fait qui la contredirait, avec un outil, et dis ce que tu as trouvé. Exemple : on pense à un mouvement de l'ouvrage ; les références ont-elles bougé ? Toutes les cibles ensemble ?
|
||||
6. **Rapport** (§6), puis ta réponse (§7).
|
||||
|
||||
## 5. Règles
|
||||
|
||||
- Vocabulaire de preuve, et seulement lui : `confirmed` / `strongly supported` / `consistent with` / `possible` / `insufficient evidence` / `not observed`. Pas de pourcentage de confiance.
|
||||
- Sépare fait observé (lu dans les données), fait dérivé (calculé), contexte donné par l'utilisateur, hypothèse et inconnu.
|
||||
- Aucun chiffre ni seuil sans source : chaque fait cite la commande qui l'a produit.
|
||||
- Ne construis rien sur `inlier` (binaire). `sigma0` ne suffit jamais seul. Un mouvement commun à toutes les cibles n'est pas un mouvement de l'ouvrage. Une référence cohérente n'est pas forcément fixe.
|
||||
- Un trou n'est pas forcément une coupure : acquisition, traitement, transport et affichage sont des couches distinctes.
|
||||
- Toute heure est en UTC.
|
||||
- « Rien d'anormal » est une conclusion valable.
|
||||
- Lecture seule : tu n'écris que ton rapport.
|
||||
- Rapport en français ; termes AIMsight en anglais (classifications, noms de colonnes).
|
||||
|
||||
## 6. Le rapport
|
||||
|
||||
Écris-le dans `agents/diagnostic/rapports/<AAAA-MM-JJ>_<STATION>.md` (date du jour en UTC : `date -u +%F` ; station : nom du dossier). Avec une question, ajoute un sujet court : `<AAAA-MM-JJ>_<STATION>_<sujet>.md`. Si le fichier existe, ajoute `_2`, `_3`…
|
||||
|
||||
```markdown
|
||||
# Diagnostic <STATION> : <scan | sujet de la question>
|
||||
|
||||
- **Date du diagnostic** : AAAA-MM-JJ (UTC)
|
||||
- **Données** : <dossier> ; mesures du <début> au <fin> (UTC)
|
||||
- **Demande** : scan | « <question> »
|
||||
- **Modèle** : <ton modèle>
|
||||
|
||||
## Sources lues
|
||||
- <chaque document et fichier ouvert>
|
||||
|
||||
## Inventaire
|
||||
- **Disponible** : …
|
||||
- **Manquant** : … ; ce que ça empêche de conclure : …
|
||||
|
||||
## Événements
|
||||
|
||||
### E1 : <titre court> (<début> → <fin> UTC)
|
||||
- **Classification** : une de : *monitored-object motion*, *camera/reference compensation event*, *weak/unstable reference solution*, *model mismatch/parallax*, *target-local degradation*, problème système, rien d'anormal, indéterminé
|
||||
- **Cause probable** : buée ou eau | occlusion | turbulence | éclairage | inconnue (seulement pour une cause externe à l'ouvrage)
|
||||
- **Couche** : la couche de la chaîne de dépendance (section 4 du contexte support)
|
||||
- **Niveau de preuve** : …
|
||||
- **Preuves** :
|
||||
- <fait> (observé | dérivé) : `<commande>`
|
||||
- **Réfutation** : hypothèse principale ; fait cherché pour la contredire ; résultat (`<commande>`)
|
||||
- **Alternatives** : autres explications, et pourquoi elles ne sont pas écartées
|
||||
- **Inconnus** : …
|
||||
- **Prochaine vérification** : la plus discriminante
|
||||
|
||||
## Constats permanents
|
||||
- <ce qui dure toute la période, ex. un capteur toujours rejeté>
|
||||
|
||||
## Validation (à remplir par l'utilisateur)
|
||||
- **Verdict** : accepté tel quel | corrigé
|
||||
- **Corrections** :
|
||||
- **Diagnostic final** :
|
||||
```
|
||||
|
||||
## 7. Ta réponse
|
||||
|
||||
Après avoir écrit le rapport, réponds en 5 à 10 lignes : les événements trouvés (classification, niveau de preuve), les constats permanents, le principal inconnu, et le chemin du rapport.
|
||||
````
|
||||
|
||||
- [ ] **Step 2 : écrire `.claude/agents/diagnostic.md`**
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: diagnostic
|
||||
description: Diagnostic des données d'une station AIMsight (déplacements optiques, images). À appeler avec un dossier de data/ et, si on veut, une question. Rend un rapport traçable dans agents/diagnostic/rapports/.
|
||||
tools: Read, Bash, Write
|
||||
model: opus
|
||||
effort: high
|
||||
omitClaudeMd: true
|
||||
---
|
||||
|
||||
Tu es l'agent de diagnostic du projet. Commence par lire `agents/diagnostic/instructions.md` et suis-le à la lettre. Ta demande : le dossier de `data/` et l'éventuelle question qui suivent.
|
||||
```
|
||||
|
||||
- [ ] **Step 3 : écrire `agents/diagnostic/README.md`**
|
||||
|
||||
```markdown
|
||||
# Agent de diagnostic
|
||||
|
||||
Un sous-agent Claude Code qui diagnostique les données d'une station : il repère ce qui sort de l'ordinaire, l'explique avec des preuves et dit ce qui reste non établi. Première version : déplacements optiques (export « advanced ») et images de la caméra. Pilote de l'enquête à la demande (D-042) ; décision D-046 ; spec : `docs/agents/agent-diagnostic.md`.
|
||||
|
||||
## L'appeler
|
||||
|
||||
- Dans une session Claude Code : `@agent-diagnostic data/PS_DES_COUDRES/`, suivi au besoin d'une question (« que s'est-il passé dans la nuit du 13 au 14/10 ? »). Sans question, il fait le scan de toute la période.
|
||||
- Dans un terminal, une session entière avec l'agent : `claude --agent diagnostic`.
|
||||
- Les sous-agents se chargent au démarrage d'une session : après une modification de `.claude/agents/diagnostic.md`, ouvrir une nouvelle session.
|
||||
|
||||
## Ce qu'il rend
|
||||
|
||||
Un rapport par diagnostic dans `rapports/` (sources lues, inventaire, un bloc par événement, constats permanents), et un résumé dans la conversation. La section « Validation » du rapport est à remplir : un rapport validé deviendra un cas.
|
||||
|
||||
## Contenu du dossier
|
||||
|
||||
- `instructions.md` : sa méthode, ses règles et le format du rapport. C'est ici qu'on corrige son comportement.
|
||||
- `outils/` : `inventaire.py`, `resume.py`, `graphique.py` (et `donnees.py`, la lecture commune). Ils rendent des valeurs, pas des verdicts. Le graphique demande matplotlib (`.venv`).
|
||||
- `rapports/` : ses rapports.
|
||||
|
||||
## Limites
|
||||
|
||||
Claude Code ne restreint ni ce qu'il lit, ni ce que lance son `Bash`, ni où écrit son `Write` : ses instructions le font. Son rapport liste ce qu'il a lu.
|
||||
```
|
||||
|
||||
- [ ] **Step 4 : vérifier les fichiers**
|
||||
|
||||
Run : `head -9 .claude/agents/diagnostic.md && grep -c '' agents/diagnostic/instructions.md`
|
||||
Expected : le frontmatter (7 lignes entre les `---`), puis un nombre de lignes de l'ordre de 110.
|
||||
|
||||
Run : `.venv/bin/python -c "import re,sys; t=open('.claude/agents/diagnostic.md').read(); fm=t.split('---')[1]; print(sorted(re.findall(r'^(\w+):', fm, re.M)))"`
|
||||
Expected : `['description', 'effort', 'model', 'name', 'omitClaudeMd', 'tools']`. Les outils sont `Read, Bash, Write` : `ls` et `grep` passent par `Bash` (la spec citait aussi `Glob` et `Grep`, absents de cette version de Claude Code ; la tâche 5 met la spec à jour).
|
||||
|
||||
- [ ] **Step 5 : commit**
|
||||
|
||||
```bash
|
||||
git add agents/diagnostic/instructions.md agents/diagnostic/README.md .claude/agents/diagnostic.md
|
||||
git commit -m "Add the diagnostic subagent: entry point, instructions and README (D-046)" -m "Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 5 : décision, carte du dépôt et spec
|
||||
|
||||
**Files :**
|
||||
- Modify : `docs/decisions.md` (ajout de D-046 en fin de fichier ; statut de D-044)
|
||||
- Modify : `CLAUDE.md` (état, commandes, carte, environnement)
|
||||
- Modify : `docs/agents/agent-diagnostic.md` (statut ; ligne de `resume.py` au §6)
|
||||
|
||||
- [ ] **Step 1 : ajouter D-046 à la fin de `docs/decisions.md`**
|
||||
|
||||
```markdown
|
||||
|
||||
## D-046 — 2026-10-14 — Agent de diagnostic : pilote de l'enquête à la demande dans Claude Code
|
||||
- **Statut** : active. Version pilote de D-042 ; déroge à D-027 sur le harnais, pour ce pilote seulement ; met au second plan la chaîne analytique de D-044.
|
||||
- **Décision** :
|
||||
- un sous-agent Claude Code `diagnostic` (`.claude/agents/diagnostic.md`), avec son dossier `agents/diagnostic/` (instructions, outils, rapports), diagnostique à la demande un dossier de `data/` : scan sans question, enquête avec une question ; un rapport par diagnostic dans `agents/diagnostic/rapports/`, avec une section de validation pour l'utilisateur ;
|
||||
- première version : déplacements (export « advanced ») et images ; métriques système plus tard ;
|
||||
- outils en lecture qui rendent des valeurs, pas des verdicts : `inventaire.py`, `resume.py`, `graphique.py` (matplotlib, ajouté à `.venv` et au dev container) ;
|
||||
- Opus 5.5, effort `high` ; `omitClaudeMd` : l'agent ne lit que les sources listées dans ses instructions, pour diagnostiquer sans connaître nos conclusions ;
|
||||
- spec : `docs/agents/agent-diagnostic.md`.
|
||||
- **Pourquoi** : demande de l'utilisateur : profiter de la souplesse d'un agent plutôt que d'écrire des méthodes analytiques complexes, et pouvoir l'appeler à tout moment. Claude Code ne demande ni clé API ni harnais, prérequis bloquants de D-027 et D-042.
|
||||
- **Options écartées** : un skill dans la conversation courante (il hériterait des hypothèses de la conversation) ; un skill seul avec `context: fork` (caché sous `.claude/`) ; les graphiques par plotly (kaleido embarque un navigateur) ; pas de graphique (l'agent verrait mal les formes des séries).
|
||||
- **Conséquence** :
|
||||
- D-027 avait écarté un harnais de codage pour l'agent serveur, à cause d'un Bash large et peu auditable ; ce refus vaut toujours pour un agent qui notifie des clients. Ici, outil de travail interne : Claude Code ne restreint ni `Read`, ni `Bash`, ni `Write` à des chemins ; les instructions le font, et le rapport liste ses sources ;
|
||||
- pas de LLM dans `src/` : la couche déterministe ne change pas ;
|
||||
- vérification par un test à l'aveugle sur PS des Coudres, attendus écrits avant le premier passage (§7 de la spec).
|
||||
```
|
||||
|
||||
- [ ] **Step 2 : statut de D-044**
|
||||
|
||||
Dans `docs/decisions.md`, remplacer :
|
||||
```markdown
|
||||
- **Statut** : active, cadrage (`docs/displacement/cadrage.md`, rien n'est construit).
|
||||
```
|
||||
par :
|
||||
```markdown
|
||||
- **Statut** : active, cadrage (`docs/displacement/cadrage.md`, rien n'est construit) ; l'exploration passe d'abord par l'agent de diagnostic (D-046), la chaîne analytique au second plan.
|
||||
```
|
||||
|
||||
- [ ] **Step 3 : `CLAUDE.md`, sept remplacements et une ligne ajoutée**
|
||||
|
||||
1. Remplacer la puce `- **Enquête à la demande (D-042)** : …` (ligne entière) par :
|
||||
```markdown
|
||||
- **Agent de diagnostic (D-046)** : pilote de l'enquête à la demande (D-042) dans Claude Code : sous-agent `diagnostic` (`.claude/agents/diagnostic.md`, dossier `agents/diagnostic/`, spec `docs/agents/agent-diagnostic.md`) ; un dossier de `data/` et une question facultative donnent un rapport dans `agents/diagnostic/rapports/` ; déplacements et images seulement. L'enquête par API (D-042) reste un document.
|
||||
```
|
||||
2. Dans la puce **Séries optiques (D-044)**, remplacer `; rien n'est construit.` par `; exploration confiée d'abord à l'agent de diagnostic (D-046), chaîne analytique au second plan.`
|
||||
3. Dans **Prochaine étape**, remplacer `séries optiques : décider avec l'utilisateur de l'exploration de PS des Coudres (étape 1 du cadrage).` par `agent de diagnostic : test à l'aveugle sur PS des Coudres (§7 de sa spec), puis validation du rapport par l'utilisateur.`
|
||||
4. Remplacer `python3 -m venv .venv && .venv/bin/pip install plotly # recréer .venv` par `python3 -m venv .venv && .venv/bin/pip install plotly matplotlib # recréer .venv`
|
||||
5. Remplacer `Le code d'agent vivra à part (`agents/`, proposé, pas créé).` par `Le code d'agent vit à part, dans `agents/`.`
|
||||
6. Après la ligne `- `docs/agents/enquete-a-la-demande.md` …`, ajouter :
|
||||
```markdown
|
||||
- `docs/agents/agent-diagnostic.md` : spec de l'agent de diagnostic (D-046) ; code dans `agents/diagnostic/` (`instructions.md`, `outils/`, `rapports/`). Appel : `@agent-diagnostic data/<STATION>/ [question]`, ou `claude --agent diagnostic` dans un terminal.
|
||||
```
|
||||
7. Dans la puce `- `.claude/` : `rules/analyses.md` (se charge seule, voir « Analyses »), …`, insérer après `(se charge seule, voir « Analyses »), ` : `` `agents/diagnostic.md` (point d'entrée de l'agent de diagnostic, D-046), ``
|
||||
8. Remplacer `- `.venv/` (Python 3.14) ne contient que plotly, pour le poste de dev.` par `- `.venv/` (Python 3.14) ne contient que plotly et matplotlib (graphiques de l'agent de diagnostic), pour le poste de dev.`
|
||||
9. Mettre à jour `(503 l, D-001 à D-045)` avec le nouveau nombre de lignes de `docs/decisions.md` et `D-046`.
|
||||
|
||||
Run : `wc -l CLAUDE.md docs/decisions.md`
|
||||
Expected : `CLAUDE.md` à 199 lignes au plus ; le nombre de lignes de `docs/decisions.md` est celui écrit dans `CLAUDE.md`.
|
||||
|
||||
- [ ] **Step 4 : la spec**
|
||||
|
||||
Dans `docs/agents/agent-diagnostic.md` :
|
||||
- remplacer `- **Statut** : design validé par l'utilisateur, à construire.` par `- **Statut** : construit le 2026-10-14 (outils, instructions, point d'entrée) ; test à l'aveugle : §7.` ;
|
||||
- au §3, remplacer `tools: Read, Glob, Grep, Bash, Write` par `tools: Read, Bash, Write`, et `` `Read` (CSV, docs, images), `Glob`, `Grep`, `Bash` (ses scripts), `Write` (son rapport) `` par `` `Read` (CSV, docs, images), `Bash` (ses scripts, `ls`, `grep`), `Write` (son rapport) `` ;
|
||||
- au §6, remplacer la ligne de `resume.py` par :
|
||||
```markdown
|
||||
| `resume.py <dossier> [--colonne C] [--stat median\|min\|max] [--pas 1h] [--capteurs] [--debut] [--fin]` | Pour une colonne : le niveau habituel de chaque capteur sur la période (médiane, MAD, min, max), puis un tableau, une ligne par pas de temps et une colonne par capteur, avec la statistique choisie ; « rej » quand toutes les mesures du pas sont rejetées |
|
||||
```
|
||||
|
||||
- [ ] **Step 5 : commit**
|
||||
|
||||
```bash
|
||||
git add docs/decisions.md CLAUDE.md docs/agents/agent-diagnostic.md
|
||||
git commit -m "Record the diagnostic agent (D-046) in decisions, CLAUDE.md and its spec" -m "Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 6 : test à l'aveugle sur PS des Coudres
|
||||
|
||||
**Files :**
|
||||
- Create (par l'agent) : `agents/diagnostic/rapports/<date>_PS_DES_COUDRES.md`, `agents/diagnostic/rapports/<date>_PS_DES_COUDRES_<sujet>.md`
|
||||
- Modify : `docs/agents/agent-diagnostic.md` (§7 : résultats)
|
||||
- Modify (si un attendu est manqué) : `agents/diagnostic/instructions.md`
|
||||
|
||||
**Interfaces :**
|
||||
- Consumes : le sous-agent de la tâche 4.
|
||||
|
||||
Le test tourne en mode non interactif : l'agent reçoit exactement notre prompt, sans passer par une session qui connaît nos conclusions. `--allowedTools` limite son `Bash` à ses outils et son `Write` à `rapports/` pendant le test. Ce lancement consomme l'abonnement Claude de l'utilisateur.
|
||||
|
||||
- [ ] **Step 1 : lancer le scan**
|
||||
|
||||
Run (en tâche de fond, plusieurs minutes) :
|
||||
```bash
|
||||
mkdir -p out/diagnostic && env -u CLAUDECODE claude -p "data/PS_DES_COUDRES/" --agent diagnostic \
|
||||
--output-format json \
|
||||
--allowedTools "Read" "Write(agents/diagnostic/rapports/**)" \
|
||||
"Bash(python3 agents/diagnostic/outils/*)" "Bash(.venv/bin/python agents/diagnostic/outils/*)" \
|
||||
"Bash(ls *)" "Bash(grep *)" "Bash(pdftotext *)" "Bash(date *)" \
|
||||
> out/diagnostic/test_scan.json 2>&1
|
||||
```
|
||||
Expected : un JSON avec `result` (la réponse), `total_cost_usd`, `num_turns`, `duration_ms` ; un nouveau rapport dans `agents/diagnostic/rapports/`. Si les règles `--allowedTools` bloquent un outil légitime (message de refus dans `result`), corriger la règle et relancer ; en dernier recours, remplacer les règles `Write(...)` et `Bash(...)` par `--permission-mode acceptEdits` et le noter dans les résultats.
|
||||
|
||||
- [ ] **Step 2 : juger le scan face aux attendus du §7 de la spec**
|
||||
|
||||
Lire le rapport. Pour chacun des 7 attendus, noter : atteint, partiel ou manqué, avec la phrase du rapport qui le montre. Vérifier aussi que la section « Sources lues » ne contient que des sources autorisées.
|
||||
|
||||
- [ ] **Step 3 : lancer la question**
|
||||
|
||||
Run :
|
||||
```bash
|
||||
env -u CLAUDECODE claude -p "data/PS_DES_COUDRES/ — Que s'est-il passé dans la nuit du 13 au 14/10 ?" --agent diagnostic \
|
||||
--output-format json \
|
||||
--allowedTools "Read" "Write(agents/diagnostic/rapports/**)" \
|
||||
"Bash(python3 agents/diagnostic/outils/*)" "Bash(.venv/bin/python agents/diagnostic/outils/*)" \
|
||||
"Bash(ls *)" "Bash(grep *)" "Bash(pdftotext *)" "Bash(date *)" \
|
||||
> out/diagnostic/test_question.json 2>&1
|
||||
```
|
||||
Expected : un second rapport, `<date>_PS_DES_COUDRES_<sujet>.md`, centré sur le second épisode, avec les images de la nuit regardées.
|
||||
|
||||
- [ ] **Step 4 : corriger si besoin**
|
||||
|
||||
Un attendu manqué ou une conclusion au-delà des preuves : corriger `agents/diagnostic/instructions.md` (la règle ou l'étape en cause, sans y écrire la réponse), supprimer le rapport du passage raté, relancer le passage concerné. Au plus deux corrections ; au-delà, s'arrêter et en parler à l'utilisateur.
|
||||
|
||||
- [ ] **Step 5 : consigner les résultats dans la spec**
|
||||
|
||||
Ajouter à la fin du §7 de `docs/agents/agent-diagnostic.md` :
|
||||
```markdown
|
||||
**Résultats du 2026-10-14** (lancement non interactif, `claude -p --agent diagnostic`, outils limités par `--allowedTools`) :
|
||||
|
||||
| Attendu | Scan | Question |
|
||||
|---|---|---|
|
||||
| 1. Deux épisodes `REF_G` / `REF_D` | … | … |
|
||||
| 2. `REF_CT` et cibles non touchées | … | … |
|
||||
| 3. Pas de mouvement de l'ouvrage, réfutation | … | … |
|
||||
| 4. PM_G rejetée (constat permanent) | … | … |
|
||||
| 5. Inconnus | … | … |
|
||||
| 6. Niveau de preuve mesuré | … | … |
|
||||
| 7. Mesures manquantes non présentées comme des coupures | … | … |
|
||||
|
||||
- **Coût et durée** : scan … $ en … tours et … min ; question … $ en … tours et … min.
|
||||
- **Sources lues** : conformes | écarts : …
|
||||
- **Corrections des instructions** : aucune | … (relancé)
|
||||
```
|
||||
en remplaçant chaque « … » par le résultat observé.
|
||||
|
||||
- [ ] **Step 6 : commit**
|
||||
|
||||
```bash
|
||||
git add agents/diagnostic/rapports/ docs/agents/agent-diagnostic.md agents/diagnostic/instructions.md
|
||||
git commit -m "Run the diagnostic agent blind on PS des Coudres and record the results" -m "Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
|
||||
```
|
||||
Reference in new issue
Block a user