designwithai-mcp 0.1.0

package/skills/better-performance/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: better-performance
+description: Juge pourquoi un produit est lent — poids et découpage des bundles, images, listes longues, cascades de requêtes, cache et re-rendus évitables, coût du chargement perçu. Grille chiffrée quand un seuil existe, refus quand il n'y a ni code ni mesure.
+version: 1.0
+category: performance-expert
+role: Performance expert
+execution_mode: performance-audit
+supports: [ai-builder, traditional, hybrid]
+inputs: [code, bundle-report, traces, measurements, url]
+outputs: [measurement-table, bottleneck-map, risk-register, correction-plan]
+invoked_by: [review-ai-product, better-interface]
+relays: [better-states, better-navigation]
+---
+
+# /better-performance
+
+**Rôle** : Performance expert · **Mode par défaut** : audit de performance.
+
+Voir le [contrat commun](../_shared/execution-contract.md), le [schéma de problème](../_shared/issue-schema.md) (préfixe `PERF`), le [modèle de sévérité](../_shared/severity-model.md) et la [matrice des modes](../_shared/delivery-modes.md).
+
+## Mission
+
+Répondre à « pourquoi c'est lent » par une **mesure ou une structure fautive localisée**. Jamais par une impression. C'est la grille la plus objectivable du parc, et c'est sa raison d'être : sur ce sujet, tout le monde a un avis et presque personne n'a un chiffre.
+
+Ce skill porte **la grille de performance de la maison**. `review-ai-product` l'exécute au lieu de la redécrire, `better-interface` l'appelle quand la lenteur est le symptôme rapporté.
+
+## Périmètre strict
+
+**Analyse** : poids et découpage du code livré, images, listes longues, cascades de requêtes, cache et re-rendus évitables, et le **coût** du chargement perçu.
+
+**La frontière avec `better-states`, écrite une fois pour toutes** :
+
+> **L'état d'attente appartient à `better-states`. Son COÛT appartient ici.**
+
+Qu'un écran affiche un squelette plutôt qu'un vide, que le message d'attente dise quoi que ce soit, que le bouton se désactive pendant l'envoi : `better-states`. Que l'attente dure 4,2 s, qu'elle vienne de vingt-quatre requêtes en série, qu'elle soit évitable : ici. Un skill qui recommande « ajouter un squelette de chargement » a franchi la frontière — le squelette masque le coût, il ne le supprime pas.
+
+**N'analyse pas** : la sécurité et l'accès aux données (`review-data-security`), les chemins entre écrans (`better-navigation`), la formulation d'un message d'attente (`better-writing`).
+
+## Ce que le skill exige pour parler
+
+**Sans code ni mesure, il n'y a pas d'audit de performance.** L'impression de lenteur n'est pas une preuve, et ce skill rend `BLOCKED` plutôt que de la convertir en constat.
+
+| Entrée | Ce qui devient jugeable |
+|---|---|
+| **Mesures de terrain** (Core Web Vitals du produit réel) | Le vécu, chiffré. La référence la plus forte. |
+| **Trace de chargement** (requêtes, séquence, durées) | Cascades, requêtes en série, temps réel de chaque étape. |
+| **Rapport de build** (taille par entrée, dépendances) | Poids livré, découpage, doublons de bibliothèques. |
+| **Code** (composants, requêtes, boucles) | Structures fautives : N+1, absence de mémoïsation, listes non virtualisées. |
+| **Une URL seule** | Presque rien sans mesure associée — demander la mesure. |
+| **« C'est lent chez moi »** | Rien. `BLOCKED`, avec la liste de ce qu'il faut fournir. |
+
+Une structure fautive lue dans le code est un constat recevable **sans mesure**, à condition de dire ce qu'elle coûte en nature (« vingt-quatre requêtes en série là où une jointure suffirait ») et de ne pas inventer une durée qu'on n'a pas mesurée.
+
+## Les seuils, et d'où ils viennent
+
+La grille cite des chiffres. Elle dit **toujours** de quelle nature ils sont — sans quoi elle simule une rigueur qu'elle n'a pas.
+
+### Seuils mesurés, largement partagés
+
+| Indicateur | Bon | Mauvais | Ce qu'il mesure |
+|---|---|---|---|
+| **LCP** | ≤ 2,5 s | > 4 s | Quand le contenu principal devient visible. |
+| **INP** | ≤ 200 ms | > 500 ms | La réponse à une interaction. |
+| **CLS** | ≤ 0,1 | > 0,25 | Les sauts de mise en page pendant le chargement. |
+
+Et les limites de perception, stables depuis des décennies : **100 ms** — la réaction paraît instantanée ; **1 s** — le fil de la pensée tient, un retour visuel devient nécessaire ; **10 s** — l'attention décroche, il faut une progression et une sortie.
+
+### Conventions d'atelier, à citer comme telles
+
+Aucune norme ne les fixe. Elles servent de repère, pas de verdict, et se disent au conditionnel :
+
+- **Poids de code livré** sur la première route : au-delà d'environ 200 Ko compressés de JavaScript, le coût devient sensible sur mobile en réseau contraint. Repère, pas règle.
+- **Listes** : au-delà de quelques centaines de lignes réellement présentes dans le document, la virtualisation ou la pagination se pose. Le seuil dépend du poids de chaque ligne.
+- **Images** : servir plus du double des pixels réellement affichés est du gaspillage mesurable ; le rapport entre dimensions servies et affichées est la preuve, pas le poids seul.
+
+> **Un chiffre cité sans sa nature est un chiffre qui ment.** « LCP à 5,1 s, au-delà du seuil de 4 s » est un constat. « Le bundle fait 1,9 Mo, c'est trop » n'en est pas un tant qu'on n'a pas dit que 200 Ko est un repère d'atelier et non une norme.
+
+## La grille
+
+### 1. Poids et découpage du code livré
+
+- Taille par point d'entrée, et ce qui la compose. Une bibliothèque lourde chargée pour un usage marginal est le cas le plus fréquent.
+- **Doublons** : deux bibliothèques qui font la même chose, ou la même incluse deux fois en versions différentes.
+- Ce qui est chargé d'emblée alors qu'il ne sert qu'après une interaction, ou sur une autre route.
+- Polices : nombre de fichiers, formats, et si le texte attend leur arrivée pour s'afficher.
+
+### 2. Images
+
+- Dimensions servies contre dimensions affichées — le rapport est la preuve.
+- Format : les formats modernes divisent le poids sans perte visible.
+- Chargement différé pour ce qui est hors de l'écran initial, **jamais** pour ce qui y est : différer l'image principale dégrade le LCP au lieu de l'améliorer.
+- Dimensions déclarées : leur absence provoque les sauts de mise en page que mesure le CLS.
+
+### 3. Listes longues
+
+- Nombre de lignes réellement présentes dans le document, pas dans les données.
+- Ce que coûte une ligne : une ligne riche à trois cents exemplaires pèse plus que mille lignes simples.
+- Pagination, chargement progressif ou virtualisation — le choix dépend de l'usage, pas de la mode.
+
+### 4. Cascades de requêtes
+
+- **N+1** : une requête de liste suivie d'une requête par élément. La signature la plus courante et la plus coûteuse.
+- **Séquences évitables** : des requêtes qui s'attendent alors qu'elles ne dépendent pas les unes des autres.
+- **Cascade de rendu** : un composant qui attend son parent pour commencer à charger ce qu'il aurait pu demander en même temps.
+- Requêtes déclenchées à chaque frappe ou à chaque défilement sans limitation.
+
+### 5. Cache et re-rendus
+
+- Ce qui est redemandé alors que rien n'a changé.
+- Re-rendus déclenchés par une valeur recréée à chaque passage, là où la structure du composant les rendait évitables.
+- Absence de cache sur des données stables, ou cache si long que l'écran ment sur l'état réel.
+
+### 6. Le coût du chargement perçu
+
+- Ce que la personne voit pendant l'attente relève de `better-states` ; **combien de temps elle attend, et pourquoi, relève d'ici.**
+- Le travail fait avant le premier affichage utile, et ce qui pourrait attendre.
+- Une attente qui dépasse dix secondes sans progression ni sortie est un problème de performance **et** d'état : le signaler, et passer la partie état.
+
+## Sévérité sur cet axe
+
+| Sévérité | Sur cet axe |
+|---|---|
+| **Bloquant** | Une tâche essentielle devient impraticable : l'écran ne répond plus, l'attente dépasse la patience et n'offre ni progression ni sortie, l'appareil sature. |
+| **Critique** | Un indicateur mesuré dans la zone « mauvaise » sur un parcours principal. Une cascade qui multiplie l'attente d'un facteur visible. Une liste qui fige l'écran à l'usage réel. |
+| **Majeur** | Poids nettement au-delà du repère sans raison identifiée. Images servies plusieurs fois trop grandes. Requêtes en série évitables. Re-rendus systématiques sur un écran fréquenté. |
+| **Mineur** | Gaspillage réel mais sans effet mesurable sur le vécu. |
+| **Note** | Optimisation possible, sans preuve d'impact — à documenter, pas à faire. |
+
+**Une sévérité ne se fonde jamais sur une impression.** Sans mesure ni structure fautive localisée, il n'y a pas de constat, donc pas de sévérité.
+
+## Séquence d'audit obligatoire
+
+1. **Déclarer les entrées.** Ce qui a été reçu, et ce qui manque. Refuser s'il n'y a ni code ni mesure.
+2. **Nommer le parcours** et l'appareil ou le réseau de référence. « Lent » n'a pas de sens sans les deux.
+3. **Poser les mesures disponibles** dans un tableau, avec leur nature et leur origine.
+4. **Chercher les structures fautives dans le code**, indépendamment des mesures.
+5. **Rapprocher les deux** : quelle structure explique quelle mesure. Une mesure sans cause identifiée reste une mesure, pas un constat.
+6. **Chiffrer le gain attendu** quand c'est possible, sinon le dire.
+7. **Ordonner par rapport gain / coût**, jamais par ordre d'apparition.
+8. **Signaler les dépendances** vers `better-states` ou `better-navigation` sans développer leur audit.
+
+## Anti-patterns à refuser
+
+- Écrire « ça semble lent », « ça pourrait être optimisé », « les performances sont perfectibles ».
+- Citer un chiffre sans dire s'il s'agit d'une mesure, d'un standard ou d'un repère d'atelier.
+- Recommander une optimisation sans mesure ni structure fautive derrière.
+- Proposer d'ajouter un squelette de chargement en guise de correction — c'est masquer le coût, pas le réduire.
+- Différer le chargement de l'image principale de l'écran.
+- Recommander une réécriture pour un gain non chiffré.
+- Optimiser un écran rare avant un écran fréquenté.
+- Confondre le nombre de lignes dans les données et le nombre de lignes dans le document.
+
+## Contrat de sortie exact
+
+```
+# Verdict
+- Verdict: PASS | PASS WITH FIXES | FAIL | BLOCKED
+- Parcours audité, appareil et réseau de référence
+- Entrées reçues / manquantes
+
+# Mesures
+Indicateur | Valeur | Nature (mesure terrain | standard | repère d'atelier) | Origine
+
+# Causes localisées
+Symptôme mesuré | Structure fautive | Fichier ou requête | Gain attendu
+
+# Problèmes priorisés
+PERF-XX | Sévérité | Localisation | Preuve chiffrée ou structurelle | Impact | Correction | Critères | Confiance
+
+# Non mesuré
+- Ce qui n'a pas pu être établi, et ce qu'il faudrait pour le mesurer
+
+# À passer à un autre skill
+- Constat pressenti -> skill concerné (sans le développer)
+```
+
+## Critères de qualité du skill
+
+- Chaque constat porte une mesure ou une structure fautive localisée — jamais une impression.
+- Chaque chiffre cité dit sa nature : mesure, standard ou repère d'atelier.
+- Le parcours, l'appareil et le réseau de référence sont nommés.
+- Les corrections sont ordonnées par gain rapporté au coût.
+- Ce qui n'a pas pu être mesuré figure en clair, et non en silence.
+- Aucune recommandation ne masque un coût au lieu de le réduire.
+
+## Exemple d'invocation
+
+```
+/better-performance
+Parcours: écran « Mes factures », le plus consulté
+Entrées: trace de chargement (24 requêtes), rapport de build, code des composants
+Référence: mobile milieu de gamme, réseau 4G
+Symptôme rapporté: « la liste met plusieurs secondes à s'afficher »
+Objectif: identifier la cause et chiffrer le gain avant d'engager le travail
+```

package/skills/better-performance/evals/cases.json

@@ -0,0 +1,114 @@
+[
+  {
+    "id": "perf-conformant-releves",
+    "skill": "better-performance",
+    "kind": "conformant",
+    "delivery_mode": "classique",
+    "artifact": "ENTRÉES REÇUES\n- Mesures de terrain sur 30 jours (produit réel, 12 400 sessions).\n- Trace de chargement de l'écran le plus consulté.\n- Rapport de build.\n- Code des composants de l'écran.\n\nPARCOURS AUDITÉ : « Mes relevés », écran le plus consulté.\nRÉFÉRENCE : mobile milieu de gamme, réseau 4G.\n\nMESURES DE TERRAIN (75e centile)\n  LCP  1,9 s\n  INP  120 ms\n  CLS  0,04\n\nTRACE DE CHARGEMENT\n  1  document HTML                    180 ms\n  2  bundle principal                 240 ms   (en parallèle du 3)\n  3  police Inter, 2 fichiers woff2    90 ms   (en parallèle du 2)\n  4  requête liste des relevés        160 ms   (une seule, avec ses compteurs joints)\n  Total jusqu'au contenu principal : 1,9 s (mesure de terrain ci-dessus).\n\nRAPPORT DE BUILD\n  entrée principale : 148 Ko compressés (JavaScript)\n  route /consommation : 62 Ko compressés, chargée à la demande\n  une seule bibliothèque de graphiques, chargée uniquement sur /consommation\n  aucune dépendance en double\n\nIMAGES\n  courbe-consommation.avif : servie en 720x360, affichée en 720x360,\n  dimensions déclarées dans le balisage, hors écran initial et différée.\n\nLISTE\n  « Mes relevés » affiche 24 lignes réellement présentes dans le document.\n  Au-delà de 50, une pagination prend le relais.\n\nCODE\n  La liste est mémoïsée sur la clé des données. Les gestionnaires sont stables.\n  La recherche est limitée à une requête toutes les 300 ms de frappe.",
+    "golden": {
+      "expected_findings": [],
+      "forbidden_findings": [
+        "réduire encore le poids du bundle principal",
+        "reprocher l'absence de virtualisation sur la liste",
+        "recommander de différer le chargement des polices",
+        "prétendre que les mesures pourraient être meilleures"
+      ],
+      "expected_verdict": "PASS",
+      "should_refuse": false,
+      "note": "Tout est dans la zone bonne : LCP, INP et CLS mesurés sur le terrain, une seule requête pour la liste, 148 Ko livrés, image au bon format et aux bonnes dimensions, liste bornée, mémoïsation en place, frappe limitée. Le piège de ce cas est l'optimisation gratuite : 148 Ko est sous le repère, 24 lignes ne réclament pas de virtualisation, et une police en woff2 chargée en parallèle n'est pas un défaut. Recommander une optimisation sans preuve d'impact est exactement ce que ce skill interdit — et un constat sans mesure ni structure fautive n'a pas de sévérité."
+    }
+  },
+  {
+    "id": "perf-obvious-factures",
+    "skill": "better-performance",
+    "kind": "obvious-defect",
+    "delivery_mode": "ai-builder",
+    "artifact": "ENTRÉES REÇUES\n- Mesures de terrain sur 30 jours (produit réel, 8 900 sessions).\n- Trace de chargement de l'écran le plus consulté.\n- Rapport de build.\n- Code des composants.\n\nPARCOURS AUDITÉ : « Mes factures », écran le plus consulté du produit.\nRÉFÉRENCE : mobile milieu de gamme, réseau 4G.\n\nMESURES DE TERRAIN (75e centile)\n  LCP  6,4 s\n  INP  610 ms\n  CLS  0,31\n\nTRACE DE CHARGEMENT\n  1  document HTML                         210 ms\n  2  bundle principal                     3 100 ms\n  3  requête liste des factures             180 ms\n  4-27  requête de détail de paiement, une par facture, EN SÉRIE\n        24 requêtes, 140 ms en moyenne chacune, 3 360 ms cumulés\n  28 requête des préférences d'affichage    120 ms (ne dépend d'aucune autre,\n        déclenchée après la 27)\n\nRAPPORT DE BUILD\n  entrée principale : 1 940 Ko compressés (JavaScript)\n  trois bibliothèques de graphiques incluses : chart.js, recharts, apexcharts\n  moment.js et date-fns présentes toutes les deux\n  lodash importé en entier pour deux fonctions\n  la bibliothèque de graphiques est chargée sur toutes les routes, alors qu'un\n  seul écran affiche un graphique\n\nIMAGES\n  entete-facture.png : servie en 2400x1200, affichée en 600x300,\n  aucune dimension déclarée dans le balisage\n  logo-partenaire.png : servi en 1200x1200, affiché en 48x48\n  Les deux sont dans l'écran initial et portent l'attribut de chargement différé.\n\nLISTE\n  « Mes factures » construit 1 850 lignes dans le document, toutes présentes en\n  même temps. Chaque ligne contient un graphique de miniature.\n\nCODE\n  Le tableau reçoit à chaque rendu un objet d'options recréé sur place, et une\n  fonction de tri redéfinie dans le corps du composant.\n  La recherche déclenche une requête à chaque frappe, sans limitation.",
+    "golden": {
+      "expected_findings": [
+        "vingt-quatre requêtes de détail exécutées en série après la liste",
+        "le LCP mesuré dépasse largement le seuil au-delà duquel il est mauvais",
+        "trois bibliothèques de graphiques cohabitent dans la même entrée",
+        "deux bibliothèques de dates présentes ensemble, moment et date-fns",
+        "la bibliothèque de graphiques est chargée sur toutes les routes sans y servir",
+        "images servies plusieurs fois plus grandes que leur affichage",
+        "chargement différé appliqué aux images de l'écran initial",
+        "dimensions absentes dans le balisage, ce que traduit le décalage mesuré",
+        "mille huit cent cinquante lignes construites simultanément dans le document",
+        "options et fonction de tri recréées à chaque rendu du tableau",
+        "une requête déclenchée à chaque frappe sans limitation"
+      ],
+      "forbidden_findings": [
+        "ajouter un squelette de chargement pendant l'attente",
+        "réécrire l'écran avec une autre bibliothèque de composants",
+        "reprocher la formulation des intitulés de colonnes",
+        "prétendre que le seuil de deux cents kilo-octets est une norme"
+      ],
+      "expected_verdict": "FAIL",
+      "should_refuse": false,
+      "note": "Le catalogue complet, et tout est chiffré ou structurellement localisé : aucun constat ne repose sur une impression. LCP et CLS dans la zone mauvaise sur le parcours le plus consulté, cascade de 24 requêtes en série, bundle dix fois au-dessus du repère, images en 2400 px pour 600 px affichés, différé appliqué à l'envers. Le bloquant est la liste de 1 850 lignes avec un graphique chacune, qui fige l'appareil. Deux pièges : proposer un squelette de chargement masque le coût au lieu de le réduire, et le repère des 200 Ko doit être cité comme repère d'atelier, jamais comme norme."
+    }
+  },
+  {
+    "id": "perf-subtle-cascade-et-cache",
+    "skill": "better-performance",
+    "kind": "subtle-defect",
+    "delivery_mode": "hybride",
+    "artifact": "ENTRÉES REÇUES\n- Mesures de terrain sur 30 jours (produit réel, 5 200 sessions).\n- Trace de chargement.\n- Rapport de build.\n- Code des composants de l'écran.\n\nPARCOURS AUDITÉ : « Détail d'un dossier », deuxième écran le plus consulté.\nRÉFÉRENCE : mobile milieu de gamme, réseau 4G.\n\nMESURES DE TERRAIN (75e centile)\n  LCP  2,9 s\n  INP  180 ms\n  CLS  0,06\n\nTRACE DE CHARGEMENT\n  1  document HTML                    190 ms\n  2  bundle principal                 420 ms\n  3  requête du dossier               210 ms\n  4  requête des pièces               230 ms   déclenchée APRÈS la 3, alors\n        qu'elle ne dépend que de l'identifiant présent dans l'adresse\n  5  requête des membres              200 ms   déclenchée APRÈS la 4, même\n        remarque\n\nRAPPORT DE BUILD\n  entrée principale : 190 Ko compressés (JavaScript)\n  aucune dépendance en double\n  l'éditeur de texte riche (140 Ko) est chargé avec l'entrée principale ; il ne\n  sert que si la personne clique sur « Ajouter une note », ce que font 6 % des\n  sessions selon les mesures fournies\n\nIMAGES\n  apercu-piece.webp : servie en 1600x900, affichée en 400x225,\n  dimensions déclarées, hors écran initial et différée.\n\nLISTE\n  L'écran affiche 40 pièces au maximum, toutes présentes dans le document.\n\nCODE\n  Le composant d'en-tête est mémoïsé. La liste des pièces ne l'est pas, mais\n  elle ne se re-rend qu'au changement du dossier.\n  Le cache des données du dossier expire après 24 h ; les mesures montrent que\n  les pièces sont modifiées plusieurs fois par jour, et deux tickets de support\n  signalent une pièce ajoutée qui n'apparaît pas avant rechargement.",
+    "golden": {
+      "expected_findings": [
+        "trois requêtes s'enchaînent alors que deux ne dépendent que de l'adresse",
+        "l'éditeur de texte riche est livré à toutes les sessions pour six pour cent d'usage",
+        "le cache de vingt-quatre heures ment sur des données modifiées plusieurs fois par jour"
+      ],
+      "forbidden_findings": [
+        "reprocher l'absence de virtualisation sur la liste",
+        "ajouter un squelette de chargement pendant l'attente",
+        "les mesures sont dans la zone mauvaise",
+        "réécrire l'écran avec une autre bibliothèque de composants"
+      ],
+      "expected_verdict": "PASS WITH FIXES",
+      "should_refuse": false,
+      "note": "Aucune mesure n'est dans le rouge : LCP à 2,9 s est au-delà du bon sans atteindre le mauvais, INP et CLS sont bons. Les défauts sont donc STRUCTURELS, pas mesurés — et c'est ce que ce cas exige de savoir faire : deux requêtes qui s'attendent sans raison, 140 Ko livrés à tout le monde pour 6 % d'usage, et un cache dont la durée contredit la fréquence réelle de changement, avec deux tickets de support en preuve. Que des majeures, donc PASS WITH FIXES. Le piège inverse : 40 lignes ne réclament aucune virtualisation."
+    }
+  },
+  {
+    "id": "perf-out-of-scope-attente-muette",
+    "skill": "better-performance",
+    "kind": "out-of-scope",
+    "delivery_mode": "classique",
+    "artifact": "ENTRÉES REÇUES\n- Mesures de terrain sur 30 jours (produit réel, 3 100 sessions).\n- Trace de chargement.\n- Rapport de build.\n- Code des composants, et captures des écrans du parcours.\n\nPARCOURS AUDITÉ : « Réserver un créneau », tunnel en trois écrans.\nRÉFÉRENCE : mobile milieu de gamme, réseau 4G.\n\nMESURES DE TERRAIN (75e centile)\n  LCP  1,7 s\n  INP  95 ms\n  CLS  0,02\n\nTRACE DE CHARGEMENT\n  1  document HTML              170 ms\n  2  bundle principal           210 ms\n  3  requête des créneaux       190 ms   (une seule, pour la semaine entière)\n  Aucune requête en série. Aucune requête redondante entre les trois écrans :\n  les créneaux chargés au premier écran servent aux deux suivants.\n\nRAPPORT DE BUILD\n  entrée principale : 121 Ko compressés\n  aucune dépendance en double, aucune bibliothèque inutilisée\n\nIMAGES\n  Aucune image dans ce parcours.\n\nLISTE\n  L'écran des créneaux affiche 42 lignes dans le document.\n\nCODE\n  Les données de créneaux sont mises en cache 60 s, cohérent avec leur fréquence\n  de changement. Aucun re-rendu déclenché par une valeur recréée.\n\nCE QUE MONTRENT LES CAPTURES ET LES TEXTES\n  Pendant les 190 ms de chargement des créneaux, l'écran reste blanc : aucun\n  indicateur, aucun squelette, rien n'annonce que quelque chose arrive.\n  L'écran de confirmation affiche « Valider » sans dire ce qui sera validé.\n  Quand aucun créneau n'est libre, l'écran affiche « Aucun résultat ».\n  Le bouton d'envoi ne se désactive pas pendant la soumission : deux tickets de\n  support signalent des réservations en double.",
+    "golden": {
+      "expected_findings": [],
+      "forbidden_findings": [
+        "l'écran reste blanc sans indicateur pendant le chargement",
+        "le bouton de validation ne dit pas ce qu'il valide",
+        "la liste vide se contente d'annoncer aucun résultat",
+        "le bouton d'envoi ne se désactive pas pendant la soumission"
+      ],
+      "expected_verdict": "PASS",
+      "should_refuse": false,
+      "note": "LA FRONTIÈRE AVEC better-states, à l'état pur. Les mesures sont bonnes, une seule requête sert les trois écrans, le cache est cohérent, rien à reprocher au coût. Et le matériau montre quatre vrais défauts d'ÉTAT : écran blanc pendant 190 ms, libellé muet, état vide sans suite, double soumission possible. Ils appartiennent à better-states et better-writing. La règle du skill le dit : l'état d'attente est à states, son coût est ici — et 190 ms ne sont pas un coût. Les signaler en dépendance est prévu par le contrat de sortie ; en faire des constats échoue le cas."
+    }
+  },
+  {
+    "id": "perf-insufficient-cest-lent",
+    "skill": "better-performance",
+    "kind": "insufficient",
+    "delivery_mode": "ai-builder",
+    "artifact": "ENTRÉES REÇUES\n- Une adresse : https://mon-app.exemple.fr\n- Un message.\n\nLE MESSAGE\n  « C'est lent. Surtout le tableau de bord, je crois. Sur mon téléphone c'est\n  pire que sur mon ordinateur. Un client m'a dit la même chose la semaine\n  dernière. Vous pouvez regarder ? »\n\nCE QUI N'A PAS ÉTÉ FOURNI\n  Aucune mesure, ni de terrain ni de laboratoire.\n  Aucune trace de chargement.\n  Aucun rapport de build.\n  Aucun accès au code.\n  Aucune indication d'appareil, de réseau ni de parcours précis.\n\nCE QUI A ÉTÉ TENTÉ\n  L'adresse répond. La page se dessine dans le navigateur. Aucune mesure n'a été\n  prise : le juge n'a pas d'outil de mesure sur ce produit, et une observation à\n  l'œil n'est pas une mesure.",
+    "golden": {
+      "expected_findings": [],
+      "forbidden_findings": [
+        "le tableau de bord charge trop de données au démarrage",
+        "commencer par découper le bundle en plusieurs entrées",
+        "la lenteur vient probablement des images non optimisées",
+        "prétendre que rien d'anormal n'a été observé sur ce produit",
+        "recommander de différer le chargement des polices"
+      ],
+      "expected_verdict": "BLOCKED",
+      "should_refuse": true,
+      "note": "Une impression de lenteur, deux témoignages, et rien d'autre. C'est le cas qui définit ce skill : sans mesure ni code, il n'y a pas d'audit de performance, et une observation à l'œil n'est pas une mesure. Les deux trahisons sont piégées. Le diagnostic au flair d'abord — « ça doit être les images », « commence par découper le bundle » — qui est ce que tout le monde fait sur ce sujet et qui envoie travailler au hasard. La rassurance ensuite : « rien d'anormal observé » alors que rien n'a été mesuré. La sortie attendue demande ce qui manque : une mesure de terrain, une trace, un rapport de build, et le parcours précis."
+    }
+  }
+]

package/skills/better-responsive/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: better-responsive
+description: Définit et vérifie le comportement réel d'une interface entre mobile, tablette, desktop et contenus extrêmes ; le responsive n'est pas une réduction proportionnelle du desktop.
+version: 1.0
+category: design-expert
+role: Design expert
+execution_mode: multi-viewport-audit
+supports: [ai-builder, traditional, hybrid]
+inputs: [image, url, code, figma]
+outputs: [behavior-matrix, issue-register, transformation-rules, test-plan]
+relays: [better-layout, better-components, better-states, better-accessibility]
+---
+
+# /better-responsive
+
+**Rôle** : Design expert · **Mode par défaut** : audit multi-viewport.
+
+Voir le [contrat commun](../_shared/execution-contract.md), le [schéma de problème](../_shared/issue-schema.md) (préfixe `RESP`), le [modèle de sévérité](../_shared/severity-model.md) et la [matrice des modes](../_shared/delivery-modes.md).
+
+## Mission
+
+Garantir que l'interface conserve sa priorité, sa compréhension et son action principale quand l'espace, le contenu et le mode d'interaction changent. Le responsive n'est pas une réduction proportionnelle du desktop.
+
+## Déclenchement
+
+Débordements, composants qui rétrécissent mal, navigation mobile fragile, tableaux ou modals, ou écrans générés pour un seul viewport.
+
+- **Entrées minimales** : au moins deux viewports ou un artefact testable. Idéalement contenu long et états réels.
+- **N'analyse pas** la qualité générale du layout sur un seul viewport, sauf lorsqu'elle empêche l'adaptation.
+- **Principe** : spécifier le comportement entre les points de rupture plutôt que choisir des breakpoints arbitraires.
+
+## Scénarios obligatoires
+
+| Scénario | Objectif |
+|---|---|
+| **Petit mobile** | Détecter compression, débordement, actions inaccessibles et scroll horizontal. |
+| **Grand mobile** | Vérifier navigation, barres fixes, clavier logiciel et orientation. |
+| **Tablette / intermédiaire** | Détecter la zone souvent oubliée où ni le mobile ni le desktop ne fonctionnent correctement. |
+| **Desktop standard** | Valider largeur de lecture, densité et équilibre. |
+| **Large desktop** | Éviter étirement excessif, lignes trop longues et vide sans intention. |
+| **Contenu extrême** | Titres longs, traductions, valeurs élevées, listes vides ou très longues. |
+
+## Séquence d'analyse obligatoire
+
+1. **Identifier les priorités.** Lister ce qui doit rester visible, accessible ou compréhensible à chaque largeur.
+2. **Cartographier les transformations.** Pour chaque bloc : conserver, empiler, déplacer, condenser, masquer avec alternative, transformer ou rendre scrollable.
+3. **Tester les conteneurs.** Largeur maximale, marges, gutters, colonnes, cartes, grilles et zones fixes.
+4. **Tester la navigation.** Menu, tabs, breadcrumbs, actions secondaires, retour et orientation dans le produit.
+5. **Tester les composants complexes.** Tableaux, charts, filtres, formulaires, modals, drawers, éditeurs et drag-and-drop.
+6. **Tester les interactions tactiles.** Cibles, espacement, gestures, hover-only, clavier logiciel et éléments collants.
+7. **Tester le contenu réel.** Longueurs extrêmes, erreurs, chargement, empty state et données partielles.
+8. **Spécifier les règles.** Décrire le comportement attendu, pas seulement « optimiser mobile ».
+
+## Règles de décision
+
+- **Prioriser plutôt que cacher.** Si une information disparaît sur mobile, justifier son importance moindre et fournir un accès alternatif si nécessaire.
+- **Transformer le pattern lorsque nécessaire.** Un tableau desktop peut devenir liste, cartes, colonnes prioritaires ou vue détaillée ; pas un tableau miniaturisé.
+- **Éviter les hauteurs fixes.** Le contenu dynamique, le zoom et la traduction doivent pouvoir s'étendre.
+- **Préserver l'action principale.** Les CTA essentiels ne doivent pas se déplacer dans une zone imprévisible ou être masqués par le clavier.
+- **Contrôler les sticky elements.** Barres fixes, headers et footers ne doivent pas réduire excessivement la zone utile ni masquer du contenu.
+- **Tester entre les breakpoints.** Les défauts apparaissent souvent à 700-900 px ou lors de redimensionnements progressifs.
+
+## Adaptation au mode de delivery
+
+- **AI Builder.** Vérifier les classes générées, les breakpoints par défaut, les widths fixes, les scroll containers imbriqués et les changements involontaires sur desktop après correction mobile.
+- **Classique.** Rattacher les comportements aux primitives de layout, aux tokens de breakpoint et aux stories responsive.
+- **Hybride.** Aligner la spécification responsive entre Figma, implémentation générée et code maintenu.
+
+## Anti-patterns à refuser
+
+- Réduire toutes les tailles et espaces de 20 % sur mobile.
+- Masquer des fonctionnalités importantes sans alternative.
+- Ajouter un scroll horizontal global pour éviter de traiter les composants.
+- Spécifier uniquement 375 px et 1440 px.
+- Utiliser des hauteurs fixes pour des cartes contenant du texte dynamique.
+- Transformer tous les éléments en colonne sans hiérarchiser.
+
+## Contrat de sortie exact
+
+```
+# Résumé exécutif
+- Verdict par famille de viewport
+- Parcours ou composants à risque
+
+# Matrice responsive
+Zone / composant | Petit mobile | Grand mobile | Tablette | Desktop | Large desktop | Règle
+
+# Problèmes priorisés
+RESP-XX | Sévérité | Viewport | Localisation | Preuve | Impact | Correction | Critères | Confiance
+
+# Règles de transformation
+- Ordre de contenu
+- Navigation
+- Actions
+- Tableaux et données
+- Overlays
+- Contenu extrême
+
+# Plan de test
+- Dimensions minimales
+- Redimensionnement continu
+- Clavier logiciel
+- Orientation
+- Zoom / texte agrandi
+```
+
+## Critères de qualité du skill
+
+- Le skill couvre au moins un viewport intermédiaire, pas uniquement mobile et desktop.
+- Chaque masquage ou transformation est justifié par la priorité du contenu.
+- Les scénarios de contenu extrême sont explicitement testés.
+- Les corrections ne cassent pas les viewports déjà valides.
+- Les règles sont assez précises pour être implémentées et testées.
+
+## Exemple d'invocation
+
+```
+/better-responsive
+Artefact: dashboard React en production
+Viewports: 360, 768, 1024, 1440 px
+Objectif: préserver les filtres, KPI et action « Créer une alerte »
+Mode: audit + spécification, sans patch
+```

package/skills/better-responsive/evals/cases.json

@@ -0,0 +1,77 @@
+[
+  {
+    "id": "responsive-conformant-table",
+    "skill": "better-responsive",
+    "kind": "conformant",
+    "delivery_mode": "classique",
+    "artifact": "Liste de commandes. Sur desktop : tableau 6 colonnes. Sur mobile : transformé en cartes prioritaires (n° commande, montant, statut, action). Barre d'action collante qui ne masque pas le contenu et reste au-dessus du clavier logiciel. Testé à 375, 768, 1024 et 1440 : pas de scroll horizontal, contenu long géré.",
+    "golden": {
+      "expected_findings": [],
+      "forbidden_findings": ["revoir la hiérarchie visuelle du desktop", "inventer un problème mono-viewport"],
+      "expected_verdict": "PASS",
+      "should_refuse": false
+    }
+  },
+  {
+    "id": "responsive-obvious-scroll",
+    "skill": "better-responsive",
+    "kind": "obvious-defect",
+    "delivery_mode": "ai-builder",
+    "artifact": "Dashboard généré. Sur mobile 375px : scroll horizontal global, le tableau desktop est juste miniaturisé (illisible). Le CTA principal est masqué par le clavier logiciel à l'ouverture d'un champ. Breakpoints définis uniquement à 375px et 1440px.",
+    "golden": {
+      "expected_findings": [
+        "scroll horizontal global sur mobile",
+        "tableau miniaturisé au lieu d'être transformé en liste ou cartes",
+        "CTA principal masqué par le clavier logiciel",
+        "breakpoints limités à 375 et 1440, pas de viewport intermédiaire"
+      ],
+      "forbidden_findings": ["revoir la stratégie produit", "réécrire les libellés"],
+      "expected_verdict": "FAIL",
+      "should_refuse": false
+    }
+  },
+  {
+    "id": "responsive-subtle-tablet",
+    "skill": "better-responsive",
+    "kind": "subtle-defect",
+    "delivery_mode": "classique",
+    "artifact": "Page de réglages. Impeccable à 375px et à 1440px. Mais à 768px (tablette) la sidebar et le contenu se chevauchent, et une carte de résumé a une hauteur fixe qui tronque un texte traduit plus long.",
+    "golden": {
+      "expected_findings": [
+        "zone tablette 768px cassée, chevauchement sidebar / contenu",
+        "hauteur fixe qui tronque un contenu dynamique ou traduit"
+      ],
+      "forbidden_findings": ["refonte complète", "changer la palette"],
+      "expected_verdict": "PASS WITH FIXES",
+      "should_refuse": false
+    }
+  },
+  {
+    "id": "responsive-out-of-scope-hierarchy",
+    "skill": "better-responsive",
+    "kind": "out-of-scope",
+    "delivery_mode": "classique",
+    "artifact": "Page d'accueil. Le comportement responsive est correct à tous les viewports (reflow, navigation, contenu extrême gérés). Le seul souci est sur le desktop : la hiérarchie typographique entre titre et sous-titre est plate.",
+    "golden": {
+      "expected_findings": [],
+      "forbidden_findings": ["hiérarchie typographique plate", "revoir la hiérarchie visuelle desktop"],
+      "expected_verdict": "PASS",
+      "should_refuse": false,
+      "note": "Défaut mono-viewport de hiérarchie = better-layout. N'empêche pas l'adaptation, donc hors périmètre responsive."
+    }
+  },
+  {
+    "id": "responsive-insufficient",
+    "skill": "better-responsive",
+    "kind": "insufficient",
+    "delivery_mode": "classique",
+    "artifact": "Une seule capture desktop à 1440px, sans code, sans autre viewport, sans variation de contenu.",
+    "golden": {
+      "expected_findings": [],
+      "forbidden_findings": ["conclure sur le comportement mobile", "affirmer un défaut de reflow"],
+      "expected_verdict": "BLOCKED",
+      "should_refuse": true,
+      "note": "Un seul viewport ne permet pas d'évaluer l'adaptation. Le skill doit demander ≥ 2 viewports ou un artefact testable."
+    }
+  }
+]

package/skills/better-states/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: better-states
+description: Rend explicites les états d'un écran, d'un composant ou d'un parcours, ainsi que leurs transitions, messages et voies de récupération, sans inventer les règles métier.
+version: 1.0
+category: interaction-expert
+role: Interaction expert
+execution_mode: state-model-audit
+supports: [ai-builder, traditional, hybrid]
+inputs: [image, prototype, code, url]
+outputs: [state-inventory, transition-matrix, copy, test-matrix]
+relays: [better-writing, better-forms, better-accessibility, better-responsive]
+---
+
+# /better-states
+
+**Rôle** : Interaction expert · **Mode par défaut** : state model et audit.
+
+Voir le [contrat commun](../_shared/execution-contract.md), le [schéma de problème](../_shared/issue-schema.md) (préfixe `STATE`), le [modèle de sévérité](../_shared/severity-model.md) et la [matrice des modes](../_shared/delivery-modes.md).
+
+## Mission
+
+Empêcher les interfaces de s'effondrer dès que les données, le réseau, les permissions ou les actions sortent du scénario idéal. Le skill modélise les états visibles, les transitions et la récupération sans inventer les règles métier.
+
+## Déclenchement
+
+Produit conçu uniquement en happy path, états absents, erreurs génériques, chargements fragiles ou transitions ambiguës.
+
+- **Entrées minimales** : écran, composant ou flow avec son objectif et ses données principales.
+- **Un état est incomplet si** l'utilisateur ne sait pas ce qui se passe, ce qu'il peut faire, si son action a été prise en compte ou comment récupérer.
+
+## Taxonomie des états
+
+| Famille | États typiques | Question |
+|---|---|---|
+| **Interaction** | Default, hover, focus, pressed, selected, disabled, read-only. | Que peut faire l'utilisateur maintenant ? |
+| **Données** | Initial, loading, loaded, empty, partial, stale, syncing. | Quelles données sont disponibles et à quel niveau de fiabilité ? |
+| **Résultat** | Success, warning, error, conflict, cancelled, timeout. | Quel est le résultat et que faire ensuite ? |
+| **Accès** | Unauthenticated, unauthorized, permission required, expired. | Pourquoi l'accès est-il limité et comment le récupérer ? |
+| **Système** | Offline, degraded, maintenance, rate-limited, unsupported. | Le service peut-il fonctionner et sous quelles limites ? |
+| **Processus** | Draft, queued, processing, completed, failed, retrying. | Où est l'opération dans le temps ? |
+
+## Périmètre strict
+
+- **Analyse** : états visibles, transitions, déclencheurs, persistance, feedback, récupération, données partielles, concurrence, actions disponibles et cohérence des messages.
+- **N'analyse pas** la stratégie métier qui détermine les permissions ou statuts. Il documente les questions non résolues.
+
+## Séquence d'analyse obligatoire
+
+1. **Définir l'objet suivi.** Page, ressource, action, upload, génération, paiement, synchronisation ou autre processus.
+2. **Lister les états existants.** À partir des écrans, du code, de la base, des statuts ou de la documentation.
+3. **Lister les états manquants.** Réseau lent, zéro donnée, permission, conflit, erreur partielle, expiration, double soumission, reprise.
+4. **Tracer les transitions.** Événement déclencheur, état source, état cible, délai, annulation, retry et persistance.
+5. **Vérifier le feedback.** Message, indicateur, blocage ou possibilité de poursuivre pendant chaque transition.
+6. **Vérifier la récupération.** Retry, retour, sauvegarde de brouillon, annulation, support, résolution du conflit.
+7. **Vérifier la cohérence.** Les mêmes états emploient les mêmes patterns, textes et comportements.
+8. **Produire la matrice de test.** Chaque état doit être déclenchable et vérifiable.
+
+## Règles de décision
+
+- **Loading n'est pas unique.** Distinguer chargement initial, rechargement, action locale, génération longue et synchronisation en arrière-plan.
+- **Empty n'est pas no result.** Un produit jamais configuré ne demande pas la même réponse qu'une recherche sans résultat.
+- **Disabled doit avoir une cause.** Quand l'utilisateur peut raisonnablement se demander pourquoi, expliquer la condition ou proposer l'action nécessaire.
+- **Success doit confirmer le résultat réel.** Ne pas annoncer un succès avant la persistance ou la confirmation serveur.
+- **Error doit préserver le travail.** Éviter de vider un formulaire ou de perdre un brouillon après un échec récupérable.
+- **Les opérations longues doivent être traçables.** Afficher progression ou statut, permettre de quitter la page et retrouver le résultat lorsque possible.
+- **Les conflits doivent être explicites.** Édition concurrente, version obsolète ou données modifiées ne doivent pas être écrasées silencieusement.
+
+## Adaptation au mode de delivery
+
+- **AI Builder.** Vérifier les états codés uniquement côté client, les données fictives, les mutations optimistes non compensées, les loaders globaux et les erreurs Supabase non exposées.
+- **Classique.** Relier la state machine aux contrats API, composants, stories et tests.
+- **Hybride.** Comparer les statuts en base, les états d'interface et les règles métier documentées. Éliminer les traductions contradictoires.
+
+## Anti-patterns à refuser
+
+- Un spinner plein écran pour toute opération.
+- Un toast comme seul feedback d'une action importante.
+- Un bouton désactivé sans explication.
+- Une erreur générique qui détruit les données saisies.
+- Confondre liste vide, filtre sans résultat et erreur de chargement.
+- Ajouter des états non supportés par le backend en les présentant comme existants.
+
+## Contrat de sortie exact
+
+```
+# Objet et parcours
+- Ressource ou opération suivie
+- Tâche utilisateur
+- Source des statuts
+
+# Inventaire des états
+État | Déclencheur | Affichage | Actions disponibles | Persistance | Sortie
+
+# Transitions
+ÉTAT A -> événement -> ÉTAT B | délai | retry | annulation | edge cases
+
+# Problèmes priorisés
+STATE-XX | Sévérité | État / transition | Preuve | Impact | Correction | Critères | Confiance
+
+# Copy et feedback nécessaires
+- Message
+- Action principale
+- Action secondaire
+- Annonce accessible
+
+# Matrice de test
+- Précondition
+- Action
+- Résultat attendu
+- Données préservées
+```
+
+## Critères de qualité du skill
+
+- Tous les états critiques du parcours sont identifiés ou explicitement marqués comme inconnus.
+- Chaque erreur récupérable possède une voie de récupération.
+- Les transitions sont reliées à une source de statut réelle.
+- Le skill distingue loading initial, action locale et traitement long.
+- La matrice est testable en QA ou automatisation.
+
+## Exemple d'invocation
+
+```
+/better-states
+Parcours: génération d'un rapport IA
+Statuts backend: queued, processing, completed, failed
+Objectif: permettre à l'utilisateur de quitter puis revenir
+Mode: state model + critères de test
+```