Files
Support-Agent/docs/superpowers/plans/2026-10-14-base-de-cas.md
T

21 KiB

Base de cas de l'agent de diagnostic — plan de mise en œuvre

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: Donner à l'agent de diagnostic une base de cas validés par l'expert, vide au départ, qu'il consulte après avoir établi ses faits, et vérifier qu'il fonctionne toujours avec l'index vide.

Architecture: Rien que du Markdown. Un index agents/diagnostic/cas/INDEX.md (en-tête seulement), une nouvelle étape « Cas connus » dans agents/diagnostic/instructions.md, de nouveaux champs dans le format du rapport (cas connu, conséquence pour l'ouvrage, action, devient un cas), la procédure d'ajout dans le README. La vérification est un passage à l'aveugle du sous-agent diagnostic sur PS des Coudres.

Tech Stack: Markdown ; sous-agent Claude Code diagnostic (outil Agent) ; git.

Spec: docs/agents/agent-diagnostic.md §11 ; décision D-048 dans docs/decisions.md.

Global Constraints

  • Aucun script, aucun code : la base est du Markdown (§11.8 : pas de cas.py, pas de RAG).
  • La base démarre vide. Aucun cas n'est créé (pas de C-001, même pour PS des Coudres) : un cas n'entre que sur demande explicite de l'utilisateur (§11.6).
  • Ne pas modifier .claude/agents/diagnostic.md : un changement exigerait une nouvelle session pour que le sous-agent le charge.
  • Documents en français ; termes AIMsight en anglais ; toute heure en UTC.
  • Pas de tests automatisés (D-008) : la vérification est le passage de l'agent (Task 3) et des grep.
  • Corps du rapport ~40 lignes (D-047) : les ajouts au format ne prennent qu'une ligne par anomalie.
  • CLAUDE.md reste sous 200 lignes ; il en a 199 : modifier des lignes existantes, n'en ajouter aucune.
  • Messages de commit en anglais, terminés par Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>.

Review Focus

Aucun cas n'existe : la correspondance ne peut pas être exercée avant le premier cas (son passage à l'aveugle, §11.6 étape 2, en sera le premier test). Le relecteur vérifie donc dans le texte des instructions :

  1. Ordre : l'index n'est lu qu'à l'étape 5, après les faits ; les sources (§2) le disent aussi. Une lecture plus tôt ancrerait l'agent.
  2. Index vide : il donne « aucun cas connu (index vide) », conséquence « indéterminée », hypothèses « Non validé (support) », et non une erreur ou un abandon (exercé par Task 3).
  3. Asymétrie : « aucune » conséquence pour l'ouvrage seulement avec une correspondance complète ; en partielle, « aucune » devient « indéterminée » mais « mouvement réel » reste.
  4. Deux cas complets pour une anomalie : garder celui qui a le plus de critères vérifiés, citer l'autre.
  5. Fiche hors index : l'agent n'ouvre une fiche que si l'index la cite (le rejeu d'un cas retire sa ligne).

Task 1: Base vide et instructions de l'agent

Files:

  • Create: agents/diagnostic/cas/INDEX.md
  • Modify: agents/diagnostic/instructions.md (§2 sources, §4 déroulé, §5 règles, §6 format du rapport, §7 réponse)

Interfaces:

  • Produces : le chemin agents/diagnostic/cas/INDEX.md ; les colonnes de l'index Cas | Station · fenêtre (UTC) | Signature | Classification | Cause (expert) | Verdict expert ; les champs du rapport **Cas connu**, **Conséquence pour l'ouvrage**, **Action**, **Devient un cas** ; le préfixe **Non validé (support)** :. Task 2 et Task 3 les citent à l'identique.

  • Step 1: Créer agents/diagnostic/cas/INDEX.md

# Cas connus

Incidents validés par l'expert, un par ligne. La **Signature** résume ce qu'on observe : type de capteurs, combien, colonne, forme, moment, durée, retour à la normale. Ouvre la fiche d'un cas proche par son lien ; ses critères et ses exclusions se vérifient avec tes outils, sur tes données.

| Cas | Station · fenêtre (UTC) | Signature | Classification | Cause (expert) | Verdict expert |
|---|---|---|---|---|---|

*Base vide pour l'instant.*
  • Step 2: §2 des instructions, les sources

Dans agents/diagnostic/instructions.md, après la ligne qui commence par - `docs/aimsight/AIMsight FAQ.pdf`, pour `error` (dernière puce de la liste « Seulement : »), ajouter la puce :

- à l'étape 5 du déroulé (§4) seulement, jamais avant : `agents/diagnostic/cas/INDEX.md`, puis les fiches `cas.md` qu'il cite et leurs figures. Ce sont des incidents validés par l'expert.

Dans le paragraphe Ne lis rien d'autre, remplacer :

ni les rapports de `agents/diagnostic/rapports/`.

par :

ni les rapports de `agents/diagnostic/rapports/`, ni une fiche de `agents/diagnostic/cas/` que l'index ne cite pas.
  • Step 3: §4 des instructions, l'étape « Cas connus »

Remplacer :

5. **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.
6. **Réfutation obligatoire**

par :

5. **Cas connus**, après les faits, jamais avant : sinon tu chercherais ce que dit le cas au lieu de ce que montrent les données.
   - Lis `agents/diagnostic/cas/INDEX.md`. Pour chaque anomalie, choisis au plus 3 cas dont la signature est proche de tes faits et ouvre leurs fiches.
   - Vérifie chaque critère de la signature et chaque exclusion de la fiche sur **tes** données, avec tes outils : vérifié, contredit ou non vérifiable (donnée absente).
   - Conclus, par anomalie :

     | Correspondance | Quand | Suite |
     |---|---|---|
     | **complète** | tous les critères vérifiés, aucune exclusion observée | le diagnostic de l'expert (classification, cause, conséquence, action) est ton hypothèse principale |
     | **partielle** | aucun critère contredit, certains non vérifiables | même hypothèse principale ; niveau de preuve au plus `consistent with` ; conséquence « aucune » ramenée à « indéterminée » (« mouvement réel » reste) ; les critères non vérifiables vont en « à vérifier » |
     | **aucune** | pour chaque cas ouvert, un critère contredit ou une exclusion observée ; ou index vide | tes propres hypothèses (étape 6), marquées « Non validé (support) » ; conséquence « indéterminée » |

   - Si deux cas correspondent, garde celui qui a le plus de critères vérifiés et cite l'autre.
6. **Hypothèses** : avec un cas (correspondance complète ou partielle), l'hypothèse principale est son diagnostic ; ajoute les alternatives que tes faits n'écartent pas. Sans cas, 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.
7. **Réfutation obligatoire**

Puis renuméroter les deux étapes suivantes : 7. **Preuves** devient 8. **Preuves**, 8. **Rapport** (§6), puis ta réponse (§7). devient 9. **Rapport** (§6), puis ta réponse (§7).

  • Step 4: §5 des instructions, la règle d'asymétrie

Après la ligne - « Rien d'anormal » est une conclusion valable., ajouter :

- **Asymétrie** : « Conséquence pour l'ouvrage : aucune » seulement avec une correspondance complète à un cas (étape 5). Sinon « indéterminée », ou « mouvement réel » si tes preuves l'établissent. Une fausse assurance coûte plus qu'une fausse alerte.
  • Step 5: §6 des instructions, le format du rapport

Dans le gabarit, remplacer :

<2-3 phrases : la station fonctionne-t-elle normalement ? Les anomalies, par importance, une ligne chacune. Ou : aucune anomalie.>

par :

<2-3 phrases : la station fonctionne-t-elle normalement ? Les anomalies, par importance, une ligne chacune, avec le cas connu qui leur correspond. Ou : aucune anomalie.>

Remplacer la ligne de classification :

- **Classification** : <la principale, parmi : *monitored-object motion*, *camera/reference compensation event*, *weak/unstable reference solution*, *model mismatch/parallax*, *target-local degradation*, problème système, indéterminé> · **Niveau de preuve** : … · **Cause probable** : <buée ou eau | occlusion | turbulence | éclairage | inconnue>

par :

- **Cas connu** : <C-xxx, complète (critères 1 à n vérifiés, aucune exclusion) | C-xxx, partielle (critère k non vérifiable : <raison>) | aucun cas connu (<cas ouverts et critère contredit> ou index vide)>
- **Classification** : <la principale, parmi : *monitored-object motion*, *camera/reference compensation event*, *weak/unstable reference solution*, *model mismatch/parallax*, *target-local degradation*, problème système, indéterminé> · **Niveau de preuve** : … · **Cause probable** : <buée ou eau | occlusion | turbulence | éclairage | inconnue> · **Conséquence pour l'ouvrage** : <aucune | mouvement réel | indéterminée> · **Action** : <aucune | à vérifier | intervention>. Sans cas connu, la ligne commence par « **Non validé (support)** : ».

Dans le bloc « Validation », après - **Diagnostic final** :, ajouter :

- **Devient un cas** : oui (C-xxx) | non
  • Step 6: §7 des instructions, la réponse

Remplacer :

le verdict, les anomalies (classification, niveau de preuve), le chemin du rapport.

par :

le verdict, les anomalies (cas connu, classification, niveau de preuve, conséquence pour l'ouvrage), le chemin du rapport.
  • Step 7: Vérifier la cohérence

Run: grep -n -E '^[0-9]\. \*\*|étape [0-9]|INDEX.md|Cas connu|Devient un cas|Non validé|Asymétrie' agents/diagnostic/instructions.md Expected : les étapes numérotées 1 à 9 sans doublon ; « étape 5 » dans §2, §4 et §5 désigne bien « Cas connus » ; « étape 6 » désigne « Hypothèses » ; INDEX.md en §2 et §4 ; Cas connu, Non validé (support) et Devient un cas dans le gabarit.

Run: grep -n '§4\|§6\|§7' agents/diagnostic/instructions.md Expected : les renvois internes (§6 rapport, §7 réponse) restent justes après la renumérotation des étapes (seules les étapes changent, pas les sections).

  • Step 8: Commit
git add agents/diagnostic/cas/INDEX.md agents/diagnostic/instructions.md
git commit -m "$(cat <<'EOF'
Add the empty case base and the known-cases step to the diagnostic agent (D-048)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
EOF
)"

Task 2: Documentation (README, spec, D-048, CLAUDE.md)

Files:

  • Modify: agents/diagnostic/README.md
  • Modify: docs/agents/agent-diagnostic.md (en-tête, §4, §5)
  • Modify: docs/decisions.md (statut de D-048)
  • Modify: CLAUDE.md (état, prochaine étape, carte)

Interfaces:

  • Consumes : les noms de Task 1 (agents/diagnostic/cas/INDEX.md, champs Cas connu, Conséquence pour l'ouvrage, Action, Devient un cas, Non validé (support)).

  • Step 1: README, ce qu'il rend

Dans agents/diagnostic/README.md, remplacer :

La section « Validation » du rapport est à remplir : un rapport validé deviendra un cas.

par :

La section « Validation » du rapport est à remplir ; « Devient un cas : oui » y demande d'en faire un cas (ci-dessous).
  • Step 2: README, contenu du dossier

Après la puce - `rapports/` : ses rapports, un dossier chacun., ajouter :

- `cas/` : la base de cas validés par l'expert (D-048) : `INDEX.md`, une ligne par incident, et un dossier par incident (`cas.md` et ses figures). L'agent la lit après avoir établi ses faits. Spec : §11 de `docs/agents/agent-diagnostic.md`.
  • Step 3: README, ajouter un cas

Avant la section ## Limites, ajouter :

## Ajouter un cas

Seulement sur demande explicite de l'utilisateur : en conversation, ou « Devient un cas : oui » dans la validation d'un rapport. Recevoir des données ou valider un rapport sans ce « oui » ne suffit pas.

1. Les données vont dans `data/<STATION>/` (D-029) ; l'avis de l'expert reste hors du dépôt jusqu'à l'étape 4.
2. Commiter (arbre propre : un `git status` sale a déjà fuité), puis lancer l'agent à l'aveugle sur la fenêtre de l'incident : `@agent-diagnostic data/<STATION>/ que s'est-il passé du <début> au <fin> (UTC) ?`. Il doit répondre « aucun cas connu » ou citer le bon cas, jamais un faux.
3. Comparer son rapport à l'avis de l'expert ; un attendu manqué se corrige dans `instructions.md`.
4. Écrire `cas/C-<numéro>_<STATION>_<AAAA-MM-JJ>/cas.md` au modèle du §11.3 de la spec (signature tirée des faits et des commandes du rapport, diagnostic de l'expert), y copier les figures du rapport, ajouter sa ligne à `cas/INDEX.md` (et retirer « Base vide pour l'instant »), commiter.

**Rejouer un cas** : retirer sa ligne de `cas/INDEX.md` sans commiter, lancer l'agent sur sa fenêtre, comparer son rapport à « Attendu de l'agent » de la fiche, restaurer la ligne (`git checkout agents/diagnostic/cas/INDEX.md`).
  • Step 4: Spec, en-tête

Dans docs/agents/agent-diagnostic.md, remplacer :

base de cas conçue le 2026-10-14 (D-048, §11), non construite.

par :

base de cas construite le 2026-10-14 (D-048, §11), vide.
  • Step 5: Spec §4, sources, déroulé et règles

Après la ligne 74 (- les docs AIMsight, par section : … qui finit par la FAQ pour error (pdftotext).), ajouter :

- la base de cas, `agents/diagnostic/cas/` (§11), à l'étape 5 seulement.

Remplacer :

5. **Hypothèses**, dans les familles du §12 : événement externe (occlusion, eau ou buée, turbulence, éclairage), mouvement de l'ouvrage, mouvement de la caméra ou compensation, cible dégradée, problème système.
6. **Réfutation obligatoire** de l'hypothèse principale : chercher le fait qui la contredirait, dire ce qu'on a trouvé.
7. **Preuves** :

par :

5. **Cas connus** (§11.4) : après les faits, l'index puis au plus 3 fiches par anomalie ; critères et exclusions vérifiés avec les outils ; correspondance complète, partielle ou aucune.
6. **Hypothèses** : avec un cas, son diagnostic ; sinon, dans les familles du §12 : événement externe (occlusion, eau ou buée, turbulence, éclairage), mouvement de l'ouvrage, mouvement de la caméra ou compensation, cible dégradée, problème système, marquées « non validé ».
7. **Réfutation obligatoire** de l'hypothèse principale : chercher le fait qui la contredirait, dire ce qu'on a trouvé.
8. **Preuves** :

et 8. **Rapport** (§5). par 9. **Rapport** (§5).

Après - « rien d'anormal » est une conclusion valable ;, ajouter :

- asymétrie : « aucune conséquence pour l'ouvrage » seulement avec une correspondance complète à un cas (§11.4) ;
  • Step 6: Spec §5, le rapport

Remplacer :

2. **Verdict** : 2-3 phrases ; la station fonctionne-t-elle normalement, et ses anomalies par importance.

par :

2. **Verdict** : 2-3 phrases ; la station fonctionne-t-elle normalement, et ses anomalies par importance, avec leur cas connu.

Avant la puce - une ligne : **classification** (liste fermée : …, ajouter :

   - une ligne **cas connu** : le cas et sa correspondance (complète, partielle, aucune), §11.4 ;

Dans la puce de classification, remplacer **cause probable** (buée ou eau, occlusion, turbulence, éclairage, inconnue) ; par **cause probable** (buée ou eau, occlusion, turbulence, éclairage, inconnue), **conséquence pour l'ouvrage** (aucune, mouvement réel, indéterminée), **action** (aucune, à vérifier, intervention) ; sans cas connu, la ligne est marquée « Non validé (support) » ;.

Remplacer :

6. **Validation**, laissée vide pour l'utilisateur : accepté tel quel ou corrigé (en quoi), diagnostic final. Un rapport validé deviendra un cas.

par :

6. **Validation**, laissée vide pour l'utilisateur : accepté tel quel ou corrigé (en quoi), diagnostic final, devient un cas (oui, C-xxx, ou non) ; ce « oui » déclenche l'ajout (§11.6).
  • Step 7: D-048, statut

Dans docs/decisions.md, remplacer :

- **Statut** : active, conçue (spec : §11 de `docs/agents/agent-diagnostic.md`) ; rien n'est construit. Remplace en partie D-042 (base de cas chargée dans le prompt).

par :

- **Statut** : active, construite le 2026-10-14 (spec : §11 de `docs/agents/agent-diagnostic.md`) ; base vide. Remplace en partie D-042 (base de cas chargée dans le prompt).
  • Step 8: CLAUDE.md, sans ajouter de ligne

Remplacer, dans la puce « Agent de diagnostic (D-046) » de l'état :

cas de référence du spécialiste : PS des Coudres est sain, seule anomalie les pics d'erreur de `REF_G` et `REF_D`. L'enquête par API (D-042) reste un document.

par :

cas de référence du spécialiste : PS des Coudres est sain, seule anomalie les pics d'erreur de `REF_G` et `REF_D` ; base de cas validés (D-048, `agents/diagnostic/cas/`), lue après les faits, vide : un cas n'y entre que sur demande explicite de l'utilisateur. L'enquête par API (D-042) reste un document.

Dans la prochaine étape, remplacer :

(marche de `corr_x` de BJ_G).

par :

(marche de `corr_x` de BJ_G) ; premiers cas de la base, quand l'utilisateur les apporte et le demande.

Remplacer - `docs/decisions.md` (530 l, D-001 à D-047) par - `docs/decisions.md` (542 l, D-001 à D-048).

Remplacer :

spec de l'agent de diagnostic (D-046, D-047) ; code dans `agents/diagnostic/` (`instructions.md`, `outils/`, `rapports/`, un dossier par rapport avec ses figures).

par :

spec de l'agent de diagnostic (D-046 à D-048), base de cas au §11 ; code dans `agents/diagnostic/` (`instructions.md`, `outils/`, `rapports/`, un dossier par rapport avec ses figures, `cas/`, la base de cas).
  • Step 9: Vérifier

Run: wc -l CLAUDE.md docs/decisions.md && grep -n -E '^[0-9]\. \*\*' docs/agents/agent-diagnostic.md | sed -n '1,12p' && grep -c 'Ajouter un cas' agents/diagnostic/README.md Expected : CLAUDE.md à 199 lignes ; le compte de docs/decisions.md cité dans CLAUDE.md (542) corrigé à la valeur réelle si elle diffère ; étapes du §4 de la spec numérotées 1 à 9 ; 1 pour le README.

  • Step 10: Commit
git add agents/diagnostic/README.md docs/agents/agent-diagnostic.md docs/decisions.md CLAUDE.md docs/superpowers/plans/2026-10-14-base-de-cas.md
git commit -m "$(cat <<'EOF'
Document the diagnostic agent case base: spec, D-048, README and CLAUDE.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
EOF
)"

Task 3: Vérification à l'aveugle, index vide (§11.7)

Files:

  • Create: agents/diagnostic/rapports/<AAAA-MM-JJTHHMMZ>_PS_DES_COUDRES/ (écrit par l'agent)
  • Modify: docs/agents/agent-diagnostic.md (§11.7 : résultat)

Interfaces:

  • Consumes : Task 1 (instructions, index vide) et Task 2 commités : l'arbre doit être propre.

  • Step 1: Arbre propre

Run: git status --short Expected : aucune ligne. Sinon, commiter d'abord : le sous-agent reçoit le git status et un nom de fichier peut trahir une conclusion (§7).

  • Step 2: Lancer l'agent

Outil Agent, subagent_type: diagnostic, premier plan (run_in_background: false), prompt réduit au dossier, sans question ni contexte :

data/PS_DES_COUDRES/
  • Step 3: Vérifier les attendus de §11.7

Lire le rapport.md produit et cocher :

  1. le même diagnostic que le deuxième passage (§7) : une seule anomalie, REF_G et REF_D les deux nuits, figures dans le dossier du rapport ;
  2. la ligne **Cas connu** : aucun cas connu (index vide) ;
  3. la ligne de classification commence par « Non validé (support) : » et donne **Conséquence pour l'ouvrage** : indéterminée et une **Action** ;
  4. « Sources lues » cite agents/diagnostic/cas/INDEX.md et aucune fiche ni aucun rapport ;
  5. la validation contient **Devient un cas** : oui (C-xxx) | non, laissée vide ;
  6. le corps (jusqu'à « Hors anomalie » compris) en ~40 lignes : sed -n '/^## Verdict/,/^## Annexe/p' <rapport.md> | wc -l.

Ordre de lecture (attendu : INDEX.md après les premiers resume.py) : chercher la transcription du sous-agent, ls -t ~/.claude/projects/-home-maxime-Support-Agent/*/subagents/*.jsonl | head -1, puis grep -n -o -E 'resume.py|cas/INDEX.md' <fichier> | head. Si elle est introuvable, le noter comme non vérifié.

Un attendu manqué : corriger agents/diagnostic/instructions.md, commiter, relancer (Step 1).

  • Step 4: Consigner le résultat

À la fin du §11.7 de docs/agents/agent-diagnostic.md, ajouter un paragraphe **Mise en place, le 2026-10-14 (index vide).** : chemin du rapport, appels d'outils, durée et tokens (rendus par l'outil Agent), puis un tableau | Attendu | Résultat | avec les six attendus du Step 3 et l'ordre de lecture, chacun « atteint » ou « manqué » avec le fait qui le montre, et les corrections faites aux instructions s'il y en a.

  • Step 5: Commit
git add agents/diagnostic/rapports/ docs/agents/agent-diagnostic.md agents/diagnostic/instructions.md
git commit -m "$(cat <<'EOF'
Run the diagnostic agent blind with an empty case base and record the results

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
EOF
)"