designwithai-mcp 0.1.0

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

@@ -0,0 +1,78 @@
+[
+  {
+    "id": "states-conformant-upload",
+    "skill": "better-states",
+    "kind": "conformant",
+    "delivery_mode": "classique",
+    "artifact": "Upload de fichiers. États distincts : initial, en cours (avec progression et ETA), succès (après confirmation serveur), échec partiel (3/5 réussis, traité comme résultat), erreur récupérable (le travail est préservé, retry ne rejoue que les échecs). L'opération survit si l'utilisateur quitte la page.",
+    "golden": {
+      "expected_findings": [],
+      "forbidden_findings": ["inventer un état manquant", "définir des règles métier de permission"],
+      "expected_verdict": "PASS",
+      "should_refuse": false
+    }
+  },
+  {
+    "id": "states-obvious-happypath",
+    "skill": "better-states",
+    "kind": "obvious-defect",
+    "delivery_mode": "ai-builder",
+    "artifact": "Génération d'un rapport IA. Un spinner plein écran pour toute opération. Le seul feedback de fin est un toast. Un bouton est désactivé sans explication. En cas d'erreur réseau, le formulaire saisi est vidé. Aucun état vide distinct d'un état d'erreur.",
+    "golden": {
+      "expected_findings": [
+        "spinner plein écran pour toute opération, sans distinction",
+        "toast comme seul feedback d'une action importante",
+        "bouton désactivé sans cause explicite",
+        "erreur qui détruit les données saisies",
+        "état vide confondu avec état d'erreur"
+      ],
+      "forbidden_findings": ["revoir le layout", "réécrire la proposition de valeur"],
+      "expected_verdict": "FAIL",
+      "should_refuse": false
+    }
+  },
+  {
+    "id": "states-subtle-optimistic",
+    "skill": "better-states",
+    "kind": "subtle-defect",
+    "delivery_mode": "hybride",
+    "artifact": "Ajout d'un élément à une liste. La plupart des états sont gérés. Deux écarts : le succès est affiché de façon optimiste avant la persistance (aucune compensation si l'écriture échoue) ; l'édition concurrente écrase silencieusement la version d'un autre utilisateur.",
+    "golden": {
+      "expected_findings": [
+        "succès optimiste affiché avant persistance, sans compensation en cas d'échec",
+        "conflit d'édition concurrente écrasé silencieusement"
+      ],
+      "forbidden_findings": ["refonte du composant", "changer la microcopy"],
+      "expected_verdict": "PASS WITH FIXES",
+      "should_refuse": false
+    }
+  },
+  {
+    "id": "states-out-of-scope-copy",
+    "skill": "better-states",
+    "kind": "out-of-scope",
+    "delivery_mode": "classique",
+    "artifact": "Formulaire de contact. Tous les états sont modélisés et corrects (loading, success, error, empty). Le seul défaut est le libellé d'un message d'erreur, vague et culpabilisant.",
+    "golden": {
+      "expected_findings": [],
+      "forbidden_findings": ["réécrire le message d'erreur", "libellé vague ou culpabilisant"],
+      "expected_verdict": "PASS",
+      "should_refuse": false,
+      "note": "La formulation du message est du ressort de better-writing. La MÉCANIQUE des états est correcte : hors périmètre states."
+    }
+  },
+  {
+    "id": "states-insufficient",
+    "skill": "better-states",
+    "kind": "insufficient",
+    "delivery_mode": "classique",
+    "artifact": "Une maquette d'un unique écran en happy path, sans aucune information sur les statuts backend, les données ou les erreurs possibles.",
+    "golden": {
+      "expected_findings": [],
+      "forbidden_findings": ["affirmer des états manquants sans base"],
+      "expected_verdict": "BLOCKED",
+      "should_refuse": true,
+      "note": "Sans les statuts réels ni le comportement des données, on ne peut pas modéliser les états. Demander l'objet suivi et ses statuts."
+    }
+  }
+]

package/skills/better-writing/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: better-writing
+description: Améliore les textes du produit (labels, CTA, erreurs, empty states, onboarding, notifications) pour les rendre clairs, concis, cohérents et actionnables, sans modifier le sens métier ni la voix de marque.
+version: 1.0
+category: content-expert
+role: Content expert
+execution_mode: controlled-rewrite
+supports: [ai-builder, traditional, hybrid]
+inputs: [image, text, code, url]
+outputs: [issue-register, rewrite, terminology-rules, acceptance-criteria]
+relays: [better-forms, better-states, better-consistency, better-interface]
+---
+
+# /better-writing
+
+**Rôle** : Content expert · **Mode par défaut** : réécriture contrôlée.
+
+Voir le [contrat commun](../_shared/execution-contract.md), le [schéma de problème](../_shared/issue-schema.md) (préfixe `COPY`), le [modèle de sévérité](../_shared/severity-model.md) et la [matrice des modes](../_shared/delivery-modes.md).
+
+## Mission
+
+Réduire l'effort de compréhension et guider l'action sans modifier arbitrairement le sens métier, la promesse ou le ton de marque. Chaque réécriture conserve les informations nécessaires et doit être testable dans son interface réelle.
+
+## Déclenchement
+
+Labels, CTA, onboarding, empty states, erreurs, notifications, formulaires ou terminologie incohérente. Une capture améliore fortement la qualité.
+
+## Périmètre strict
+
+- **Analyse** : labels, boutons, aides, titres, descriptions, confirmations, erreurs, notifications, onboarding, empty states, permissions, actions destructives, terminologie et cohérence éditoriale.
+- **N'analyse pas** : la stratégie de contenu marketing complète, le SEO, la direction de marque, le layout ou la logique métier. Il signale les ambiguïtés métier sans les résoudre seul.
+- **Langue et locale** : respecter la langue de l'interface, le niveau de formalité, les conventions de date, nombre, devise, genre et traduction.
+
+## Informations à obtenir
+
+- **Contexte d'affichage.** Écran, composant, moment du parcours, place disponible et état associé.
+- **Action attendue.** Ce que l'utilisateur doit comprendre, décider ou accomplir.
+- **Audience.** Niveau d'expertise, vocabulaire métier, langue et contraintes de compréhension.
+- **Voix et ton.** Règles existantes, tutoiement ou vouvoiement, niveau de chaleur, terminologie officielle.
+- **Contraintes juridiques ou métier.** Informations obligatoires à conserver, interdictions, nuances et seuils.
+
+## Séquence d'analyse obligatoire
+
+1. **Identifier la fonction du texte.** Informer, orienter, déclencher, confirmer, prévenir, expliquer ou récupérer d'une erreur.
+2. **Vérifier la compréhension immédiate.** Le texte doit être compris sans contexte caché ni jargon inutile.
+3. **Vérifier l'action.** Les boutons et instructions décrivent l'effet réel, pas un terme générique comme « Continuer » lorsque la conséquence est spécifique.
+4. **Réduire sans appauvrir.** Supprimer répétitions et formules creuses, mais conserver conditions, conséquences et informations de récupération.
+5. **Vérifier la cohérence.** Un concept, une action et un objet gardent le même nom dans tout le produit.
+6. **Vérifier les états.** Adapter le texte au succès, à l'erreur, au chargement, à l'absence de résultat, au manque de permission et au mode destructif.
+7. **Vérifier la localisation.** Prévoir expansion du texte, pluriels, formats et expressions non traduisibles littéralement.
+8. **Proposer une version finale.** Donner le texte prêt à intégrer, pas seulement des commentaires.
+
+## Règles éditoriales
+
+- **Commencer par l'information utile.** Éviter les introductions et excuses qui retardent la compréhension.
+- **Nommer l'objet et l'action.** « Supprimer le projet » est plus clair que « Confirmer ».
+- **Écrire les erreurs pour la récupération.** Dire ce qui s'est passé, pourquoi si connu, et ce que l'utilisateur peut faire maintenant.
+- **Éviter la culpabilisation.** Ne pas imputer l'échec à l'utilisateur quand le système ou le contexte est incertain.
+- **Réserver la ponctuation forte.** Éviter les points d'exclamation automatiques, le ton promotionnel et les majuscules agressives dans les interfaces.
+- **Utiliser le même terme pour la même chose.** Créer un mini-glossaire lorsque plusieurs écrans divergent.
+- **Ne pas cacher les conséquences.** Les actions irréversibles, paiements, permissions et publications doivent être explicites.
+
+## Patrons de microcopy
+
+| Situation | Structure recommandée | À éviter |
+|---|---|---|
+| **Erreur récupérable** | Problème + cause connue + prochaine action | « Une erreur est survenue. » |
+| **Empty state** | Pourquoi c'est vide + valeur attendue + action disponible | Écran décoratif sans orientation. |
+| **Action destructive** | Objet + conséquence + possibilité de retour ou absence de retour | « Êtes-vous sûr ? » sans précision. |
+| **Permission** | Pourquoi l'accès est utile + donnée concernée + choix clair | Demande opaque ou forcée. |
+| **Succès** | Résultat obtenu + prochaine étape seulement si utile | Toast générique « Succès ! ». |
+| **CTA** | Verbe + objet ou résultat | « Valider », « OK », « Continuer » par défaut. |
+
+## Adaptation au mode de delivery
+
+- **AI Builder.** Produire des remplacements localisés et nommer précisément les fichiers, composants ou textes à changer. Prévenir les réécritures globales involontaires.
+- **Classique.** Aligner les textes avec le content design system, les composants et les clés de traduction.
+- **Hybride.** Identifier quelle source contient le texte canonique : maquette, code, CMS, traduction ou base de données.
+
+## Anti-patterns à refuser
+
+- Réécrire sans connaître l'emplacement ni l'action attendue.
+- Uniformiser le ton en supprimant les nuances nécessaires entre erreur, succès et danger.
+- Raccourcir un texte réglementaire ou métier au point de changer son sens.
+- Employer des synonymes pour « éviter la répétition » dans un produit.
+- Ajouter du ton de marque dans une situation critique où la clarté prime.
+- Proposer plusieurs variantes sans recommandation finale.
+
+## Contrat de sortie exact
+
+```
+# Diagnostic
+- Fonction du texte
+- Audience et contexte
+- Problèmes observés
+- Contraintes à préserver
+
+# Réécriture recommandée
+COPY-XX | Localisation | Texte actuel | Texte recommandé | Rationale | Risque | Confiance
+
+# Terminologie
+- Terme canonique
+- Variantes à supprimer
+- Règle d'usage
+
+# États associés
+- Default
+- Loading
+- Success
+- Error
+- Empty / No result
+- Destructive si applicable
+
+# Critères de validation
+- Compréhension sans contexte externe
+- Action et conséquence explicites
+- Cohérence avec le produit
+- Compatibilité localisation et espace disponible
+```
+
+## Critères de qualité du skill
+
+- Chaque proposition conserve le sens métier et les informations obligatoires.
+- Le texte final est directement intégrable.
+- Une seule recommandation principale est fournie, avec variantes uniquement si le contexte l'exige.
+- Les termes canoniques sont cohérents entre les écrans concernés.
+- Les erreurs donnent une voie de récupération lorsque celle-ci existe.
+
+## Exemple d'invocation
+
+```
+/better-writing
+Artefact: onboarding en 4 étapes
+Audience: responsables de restaurant, non techniques
+Ton: professionnel, direct, vouvoiement
+Objectif: réduire l'ambiguïté et rendre chaque CTA explicite
+Contrainte: conserver les mentions légales
+```

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

@@ -0,0 +1,77 @@
+[
+  {
+    "id": "writing-conformant-errors",
+    "skill": "better-writing",
+    "kind": "conformant",
+    "delivery_mode": "classique",
+    "artifact": "Écran de paiement. CTA « Payer 49 € ». Erreur carte : « Paiement refusé par ta banque. Vérifie le numéro ou essaie une autre carte. » Empty state du panier : « Ton panier est vide. Ajoute un article pour commencer. » Terminologie stable : « panier » partout, jamais « cart » ni « sac ». Ton direct, vouvoiement cohérent.",
+    "golden": {
+      "expected_findings": [],
+      "forbidden_findings": ["revoir la stratégie de contenu marketing", "corriger le layout", "inventer une incohérence de ton"],
+      "expected_verdict": "PASS",
+      "should_refuse": false
+    }
+  },
+  {
+    "id": "writing-obvious-microcopy",
+    "skill": "better-writing",
+    "kind": "obvious-defect",
+    "delivery_mode": "ai-builder",
+    "artifact": "Flow de création de compte. Bouton principal « Soumettre ». Message d'erreur générique « Une erreur est survenue. » Empty state décoratif sans orientation, juste une illustration. La même action est appelée « Créer » sur un écran, « Ajouter » sur un autre et « Nouveau » sur un troisième.",
+    "golden": {
+      "expected_findings": [
+        "CTA générique Soumettre, ne décrit pas l'action",
+        "message d'erreur générique sans cause ni prochaine action",
+        "empty state décoratif sans orientation ni action",
+        "terminologie divergente Créer / Ajouter / Nouveau pour la même action"
+      ],
+      "forbidden_findings": ["revoir la grille ou le spacing", "changer la direction visuelle"],
+      "expected_verdict": "FAIL",
+      "should_refuse": false
+    }
+  },
+  {
+    "id": "writing-subtle-success",
+    "skill": "better-writing",
+    "kind": "subtle-defect",
+    "delivery_mode": "hybride",
+    "artifact": "Publication d'un article. Textes globalement bons. Deux écarts : le toast « Publié ! » s'affiche AVANT la confirmation serveur (l'article peut encore échouer) ; et le concept « brouillon » est appelé « draft » dans l'éditeur mais « version de travail » dans la liste.",
+    "golden": {
+      "expected_findings": [
+        "succès annoncé avant la confirmation serveur",
+        "même concept nommé différemment, brouillon / draft / version de travail"
+      ],
+      "forbidden_findings": ["réécriture globale du produit", "problème de layout"],
+      "expected_verdict": "PASS WITH FIXES",
+      "should_refuse": false
+    }
+  },
+  {
+    "id": "writing-out-of-scope-layout",
+    "skill": "better-writing",
+    "kind": "out-of-scope",
+    "delivery_mode": "classique",
+    "artifact": "Tableau de bord. Les textes sont clairs, actionnables et cohérents. Le vrai problème est visuel : les KPI ont des espacements irréguliers et la grille casse à 1280px.",
+    "golden": {
+      "expected_findings": [],
+      "forbidden_findings": ["espacements irréguliers des KPI", "rupture de grille", "revoir le layout"],
+      "expected_verdict": "PASS",
+      "should_refuse": false,
+      "note": "Défauts du ressort de better-layout. Rester dans le périmètre : ne pas auditer la structure visuelle."
+    }
+  },
+  {
+    "id": "writing-insufficient",
+    "skill": "better-writing",
+    "kind": "insufficient",
+    "delivery_mode": "classique",
+    "artifact": "« Améliore les textes de mon app. » Aucun écran, aucun emplacement, aucune action attendue, aucune audience précisée.",
+    "golden": {
+      "expected_findings": [],
+      "forbidden_findings": [],
+      "expected_verdict": "BLOCKED",
+      "should_refuse": true,
+      "note": "Sans emplacement ni action attendue, réécrire est deviner. Le skill doit demander le contexte d'affichage."
+    }
+  }
+]

package/skills/review-ai-product/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: review-ai-product
+description: Audit de production-readiness d'un produit construit avec un générateur IA (Lovable, Bolt, v0, Replit, Cursor…) — architecture, données, sécurité, interface, états, qualité, observabilité, capacité à évoluer — et détermine s'il est un prototype, une V0 exploitable ou une base maintenable.
+version: 2.0
+category: product-orchestrator
+role: Product orchestrator
+execution_mode: production-readiness-audit
+supports: [ai-builder, hybrid]
+inputs: [url, code, backend, env]
+outputs: [maturity-verdict, risk-register, debt-classification, target-architecture, transition-plan]
+orchestrates: [review-data-security, better-performance, better-interface, better-layout, better-accessibility, better-writing, better-responsive, better-states, better-forms, better-components, better-consistency]
+---
+
+# /review-ai-product
+
+**Rôle** : Product orchestrator · **Mode par défaut** : audit production readiness.
+
+Voir le [contrat commun](../_shared/execution-contract.md), le [schéma de problème](../_shared/issue-schema.md) (préfixe `SHIP`), le [modèle de sévérité](../_shared/severity-model.md) et la [matrice des modes](../_shared/delivery-modes.md).
+
+## Mission
+
+Déterminer si un produit construit avec un générateur IA est un prototype, une V0 exploitable ou une base réellement maintenable. Le skill ne juge pas le générateur comme outil ; il vérifie les preuves de qualité, de sécurité et de maîtrise opérationnelle du produit.
+
+## Déclenchement
+
+Avant mise en production, reprise par des développeurs, croissance du produit, dette visible ou régressions récurrentes.
+
+- **Entrées minimales** : lien vers l'aperçu du générateur ou la production. Pour un audit fiable : dépôt synchronisé, schéma du backend et variables d'environnement documentées.
+
+## Principe de sécurité
+
+- **Lecture seule par défaut.** Ne jamais lancer de migration, modifier les règles d'autorisation, secrets, données de production, configuration d'authentification ou déploiement sans autorisation explicite.
+- **Aucune supposition sur le backend.** Règles d'autorisation, rôles, schémas et fonctions serveur doivent être inspectés ou marqués non vérifiés.
+- **Séparer environnement et données.** Identifier local, preview, staging et production, ainsi que les données réelles ou fictives.
+- **Préserver la réversibilité.** Toute recommandation de migration doit inclure sauvegarde, rollback et validation.
+
+## Niveaux de maturité
+
+| Niveau | Définition | Usage acceptable |
+|---|---|---|
+| **Prototype** | Démonstration de parcours, données simulées ou architecture non vérifiée. | Tests internes, validation de concept. |
+| **V0 contrôlée** | Fonctionnalité réelle, accès limité, risques connus, monitoring minimal, données maîtrisées. | Pilote ou bêta restreinte. |
+| **Production encadrée** | Sécurité, données, qualité, déploiement et ownership documentés. | Utilisateurs réels avec support et suivi. |
+| **Produit industrialisé** | Architecture maintenable, tests, observabilité, Design System, procédures et équipe capables d'évoluer. | Croissance durable et contribution multi-équipe. |
+
+## Séquence d'audit obligatoire
+
+1. **Profiler le produit.** Criticité, utilisateurs, données, intégrations, générateur utilisé, mode généré pur ou hybride et niveau de maturité attendu.
+2. **Cartographier l'architecture.** Routes, composants, hooks, services, état global, appels API, backend / BaaS, fonctions serveur et dépendances externes.
+3. **Auditer le dépôt.** Structure, scripts, types, duplication, dépendances, secrets, erreurs, tests, build et qualité.
+4. **Auditer les données et la sécurité.** Exécuter `review-data-security` sur le backend et le dépôt. Ce skill porte la grille — autorisation table par table, rôle privilégié, frontière client/serveur, secrets, intégrité, sauvegardes. L'orchestrateur ne la redécrit pas et n'en juge aucun point lui-même.
+5. **Auditer les sessions et les rôles applicatifs.** Durée de session, expiration, rôles fonctionnels du produit et parcours de récupération de compte — la part que le modèle d'autorisation ne couvre pas.
+6. **Auditer l'interface.** Exécuter `better-interface` avec les experts nécessaires sur les parcours essentiels.
+7. **Auditer les états et erreurs.** Réseau, permissions, données absentes, doublons, concurrence, refresh, reprise et opérations longues.
+8. **Auditer la production et la performance.** Variables, environnements, build, déploiement, logs, analytics, alertes, rollback et support. Puis exécuter `better-performance` sur les parcours les plus fréquentés : ce skill porte la grille, l'orchestrateur n'en juge aucun point lui-même.
+9. **Classer la dette.** Sécurité, données, architecture, UI, qualité, opérations et documentation. Distinguer dette tolérable et dette bloquante.
+10. **Produire le plan.** Fix immédiats, stabilisation, industrialisation et éventuelle transition vers une équipe de développement.
+
+## Sécurité, données, performance : les grilles sont ailleurs
+
+Deux axes techniques ne sont **pas décrits ici**, et c'est délibéré.
+
+Les invariants de sécurité et de données — modèle d'autorisation table par
+table, rôle privilégié, frontière client/serveur, secrets, migrations et
+intégrité, sauvegardes — sont la grille de
+[`review-data-security`](../review-data-security/SKILL.md), que l'étape 4
+exécute.
+
+Les seuils et les structures de performance — poids livré, images, listes,
+cascades de requêtes, cache, coût du chargement perçu — sont la grille de
+[`better-performance`](../better-performance/SKILL.md), que l'étape 8 exécute.
+L'orchestrateur n'établit aucun seuil chiffré de lui-même : citer « le bundle
+est trop lourd » sans dire d'où vient le repère est exactement ce que cette
+délégation empêche.
+
+Ce n'est pas un renvoi de courtoisie : c'est ce qui empêche deux grilles de
+diverger. Un audit complet et un audit de sécurité seul doivent conclure la même
+chose sur les mêmes faits, sinon « ton produit monte » ne veut plus rien dire.
+
+Ce que l'orchestrateur fait de ce verdict, en revanche, lui appartient :
+
+- **Il plafonne la maturité.** Un `FAIL` de `review-data-security` maintient le
+  produit au niveau *Prototype*, quels que soient les autres axes.
+- **Il classe la dette** et remplit le Lot 0 en citant les sévérités reçues,
+  sans les re-dériver.
+- **Il tranche** générateur, hybride ou reprise, en pesant ce verdict contre la
+  complexité, la criticité et les compétences de l'équipe.
+
+Les constats remontent **tels quels**, avec leurs identifiants `SEC-XX` et
+`PERF-XX`. Ils ne sont jamais renumérotés en `SHIP-XX` : `compare_reviews` et le suivi de
+progression apparient les constats d'une passe à l'autre, et une renumérotation
+ferait réapparaître les mêmes failles comme nouvelles.
+
+## Axes de contrôle techniques
+
+| Axe | Contrôles minimaux |
+|---|---|
+| **Architecture front** | Routes, boundaries, services, state, data fetching, duplication, imports, erreurs, séparation feature/UI. |
+| **Qualité code** | Type safety, lint, build, dead code, logs, gestion des erreurs, dépendances, conventions. |
+| **Backend / BaaS et sécurité** | Délégué à `review-data-security` — voir sa grille. L'orchestrateur reçoit sa matrice d'autorisation, ses risques `SEC` et son verdict ; il n'inspecte rien lui-même sur cet axe. |
+| **Fiabilité** | Retry, idempotence, double soumission, timeouts, transactions, conflits et reprise. |
+| **Performance** | Délégué à `better-performance` — voir sa grille. L'orchestrateur reçoit ses mesures, ses constats `PERF` et son verdict ; il n'établit lui-même aucun seuil. |
+| **Opérations** | Preview/staging/prod, logs, alertes, analytics, backups, rollback, ownership et incident. |
+
+## Axes de contrôle produit et design
+
+- **Parcours essentiels.** Chaque tâche critique doit fonctionner avec données réelles, refresh, navigation arrière, session expirée et erreurs.
+- **Interface.** Activer `better-interface` sur les flows principaux, puis consolider les causes racines dans les composants ou tokens.
+- **États.** Les statuts backend doivent correspondre aux états visibles ; aucun succès anticipé ou erreur silencieuse.
+- **Responsive et accessibilité.** Valider mobile, tablette, desktop, clavier, focus et sémantique sur les composants critiques.
+- **Design System.** Identifier primitives partagées, tokens, composants dupliqués, styles codés en dur et source de vérité.
+- **Mesure.** Événements principaux, erreurs, abandons, activation et métriques doivent être observables sans exposer de données sensibles.
+
+## Classification de la dette
+
+| Classe | Exemples | Décision |
+|---|---|---|
+| **Bloquante** | Autorisation serveur absente, secret exposé, données critiques non sauvegardées, parcours principal cassé. | Corriger avant utilisateurs réels ou suspendre le lancement. |
+| **Structurelle** | Duplication, migrations non maîtrisées, composants couplés, absence de tests sur parcours critique. | Plan de stabilisation avant accélération des features. |
+| **Opérationnelle** | Pas de logs, alertes, rollback, ownership ou procédure incident. | Mettre en place avant montée en charge. |
+| **Produit / UX** | États manquants, erreurs opaques, responsive fragile, incohérences. | Prioriser selon impact et fréquence. |
+| **Acceptée** | Dette locale, documentée, sans impact actuel et avec condition de réévaluation. | Conserver dans registre avec owner. |
+
+## Décision générateur, hybride ou reprise
+
+- **Rester sur le générateur si** le produit est maîtrisé, les changements sont simples, la qualité est contrôlée et l'équipe possède les compétences d'exploitation.
+- **Passer en hybride si** des fonctionnalités ou intégrations exigent plus de contrôle, mais la base générée reste exploitable.
+- **Préparer une reprise technique si** la dette structurelle, la criticité, la complexité ou les contraintes de sécurité dépassent la capacité de contrôle du mode actuel.
+- **Ne pas décider selon la préférence.** La recommandation s'appuie sur complexité, intégration, criticité, compétences, coûts de changement et preuves d'instabilité.
+
+## Plan de correction standard
+
+| Lot | Objectif | Exemples |
+|---|---|---|
+| **0 - Sécuriser** | Éliminer les risques immédiats. | Secrets, autorisation serveur, accès, sauvegardes, données, parcours cassé. |
+| **1 - Stabiliser** | Rendre le comportement prévisible. | Erreurs, états, migrations, idempotence, logs, tests critiques. |
+| **2 - Systémiser** | Réduire la duplication et les régressions. | Composants, tokens, services, conventions, Storybook. |
+| **3 - Industrialiser** | Permettre l'évolution durable. | CI, environnements, observabilité, documentation, ownership. |
+| **4 - Accélérer** | Reprendre les features après maîtrise du socle. | Roadmap, expérimentations, optimisation. |
+
+## Anti-patterns à refuser
+
+- Déclarer le produit prêt parce que le build passe.
+- Considérer le backend comme sécurisé sans avoir exécuté `review-data-security`, ou pondérer son verdict par la qualité du reste du produit.
+- Réécrire le produit complet sans mesurer la dette et les invariants utiles.
+- Envoyer un énorme prompt au générateur pour corriger plusieurs couches à la fois.
+- Migrer la base sans sauvegarde, environnement de test et rollback.
+- Confondre absence d'erreur visible et observabilité.
+- Recommander une sortie du générateur par principe plutôt que par preuves.
+
+## Contrat de sortie exact
+
+```
+# Verdict exécutif
+- Niveau de maturité: Prototype | V0 contrôlée | Production encadrée | Industrialized
+- Verdict: PASS | PASS WITH FIXES | FAIL | BLOCKED
+- Mode recommandé: Rester sur le générateur | Hybride | Reprise technique
+- Principaux risques
+
+# Couverture et preuves
+- Accès reçus
+- Environnements
+- Données réelles / fictives
+- Éléments non vérifiés
+
+# Architecture actuelle
+- Front
+- Backend / BaaS (stack identifié)
+- Intégrations
+- Déploiement
+- Sources de vérité
+
+# Registre des risques
+SHIP-XX | Domaine | Sévérité | Localisation | Preuve | Impact | Correction | Critères | Confiance
+
+# Diagnostic sécurité et données consolidé
+- Résultats de review-data-security (matrice d'autorisation, constats SEC, non vérifié)
+- Plafond de maturité imposé, le cas échéant
+
+# Diagnostic performance consolidé
+- Résultats de better-performance (mesures, causes localisées, constats PERF)
+- Ce qui n'a pas pu être mesuré
+
+# Diagnostic interface consolidé
+- Résultats de better-interface
+- Causes racines système
+
+# Dette
+Dette | Classe | Rayon d'impact | Owner | Échéance / condition | Décision
+
+# Architecture cible
+- Ce qui reste
+- Ce qui est refactoré
+- Ce qui est remplacé
+- Frontières générateur / code / backend
+
+# Plan de transition
+Lot 0 Sécuriser
+Lot 1 Stabiliser
+Lot 2 Systémiser
+Lot 3 Industrialiser
+Lot 4 Accélérer
+
+# Vérification finale
+- Tests fonctionnels
+- Tests sécurité et permissions
+- Tests UI / responsive / accessibilité
+- Logs, alertes, backup et rollback
+```
+
+## Critères de qualité du skill
+
+- Le verdict sépare clairement prototype, V0, production et industrialisation.
+- Aucune sécurité backend n'est considérée valide sans preuve : le verdict vient de `review-data-security`, jamais d'une appréciation de l'orchestrateur.
+- Les risques de données et permissions sont traités avant les améliorations visuelles.
+- Les recommandations de rester sur le générateur, hybrider ou migrer sont fondées sur des critères explicites.
+- Le plan est ordonné, réversible et compatible avec une continuité de service.
+
+## Exemple d'invocation
+
+```
+/review-ai-product
+Produit: SaaS B2B en bêta privée
+Générateur: Lovable (dépôt synchronisé)
+Backend: Supabase
+Accès: production, GitHub, Supabase read-only
+Mode actuel: généré, sans reprise développeur
+Objectif: décider si 100 utilisateurs peuvent être onboardés
+Contraintes: ne modifier aucune donnée, aucun secret ni règle d'autorisation
+Profondeur: audit production readiness complet
+```

package/skills/review-ai-product/evals/cases.json

@@ -0,0 +1,120 @@
+[
+  {
+    "id": "ship-conformant-v0",
+    "skill": "review-ai-product",
+    "kind": "conformant",
+    "delivery_mode": "ai-builder",
+    "artifact": "Produit construit avec Lovable sur Supabase, accès complet fourni (dépôt synchronisé, schéma de la base, variables d'env documentées). RLS présentes et inspectées sur toutes les tables, aucun secret exposé, parcours principal fonctionnel avec données réelles, monitoring minimal assumé et documenté. Équipe maîtrise l'exploitation.",
+    "golden": {
+      "expected_findings": [
+        "dette opérationnelle acceptée : monitoring minimal, à réévaluer avant montée en charge"
+      ],
+      "forbidden_findings": ["recommander une reprise technique par principe", "déclarer industrialisé sans tests ni observabilité"],
+      "expected_verdict": "PASS WITH FIXES",
+      "should_refuse": false,
+      "note": "Produit sain, accès complets : le verdict attendu est PASS WITH FIXES et la recommandation « rester sur le générateur », fondée sur les preuves. La seule observation légitime est la dette opérationnelle assumée (monitoring minimal) ; toute autre alerte de sévérité majeure ou plus est un faux positif."
+    }
+  },
+  {
+    "id": "ship-obvious-security",
+    "skill": "review-ai-product",
+    "kind": "obvious-defect",
+    "delivery_mode": "ai-builder",
+    "artifact": "Produit généré (Lovable + Supabase) prêt à ouvrir à 100 users. À l'inspection : RLS absente sur deux tables contenant des données clients, une clé de service Supabase exposée côté client, et le parcours principal casse sur données réelles. Le build passe cependant.",
+    "golden": {
+      "expected_findings": [
+        "RLS absente sur des tables de données clients, risque bloquant",
+        "secret / clé de service exposé côté client",
+        "parcours principal cassé sur données réelles",
+        "sécurité et données traitées avant toute amélioration UI"
+      ],
+      "forbidden_findings": ["déclarer le produit prêt parce que le build passe", "prioriser des corrections visuelles avant les risques de permission"],
+      "expected_verdict": "FAIL",
+      "should_refuse": false
+    }
+  },
+  {
+    "id": "ship-obvious-firebase-rules",
+    "skill": "review-ai-product",
+    "kind": "obvious-defect",
+    "delivery_mode": "ai-builder",
+    "artifact": "Produit construit avec Bolt, backend Firebase (Firestore + Storage), ouverture publique prévue la semaine prochaine. Accès fournis : dépôt, fichiers de règles, console en lecture. Le fichier firestore.rules contient encore `match /{document=**} { allow read, write: if true; }`, les collections `invoices` et `users` sont lues directement depuis le client, la clé du compte de service Admin SDK est committée dans le dépôt, et aucun fichier de règles n'est versionné par environnement (le même projet Firebase sert de dev et de prod). Le build passe et l'UI est propre.",
+    "golden": {
+      "expected_findings": [
+        "règles Firestore ouvertes en lecture et écriture, aucun modèle d'autorisation appliqué côté serveur, risque bloquant",
+        "clé de compte de service Admin SDK exposée dans le dépôt",
+        "un seul projet Firebase pour dev et prod, environnements et données non séparés",
+        "règles et indexes non versionnés, changement de schéma non reproductible",
+        "sécurité et données traitées avant toute amélioration UI"
+      ],
+      "forbidden_findings": ["déclarer le produit prêt parce que le build passe", "conclure que l'absence de Supabase met le backend hors périmètre", "supposer que les règles par défaut de Firebase protègent les collections"],
+      "expected_verdict": "FAIL",
+      "should_refuse": false
+    }
+  },
+  {
+    "id": "ship-subtle-convex-authz",
+    "skill": "review-ai-product",
+    "kind": "subtle-defect",
+    "delivery_mode": "hybride",
+    "artifact": "Produit démarré sur v0 puis repris partiellement par deux développeurs, backend Convex. Le schéma est déclaré dans le dépôt, les secrets sont dans les variables d'environnement du host, l'auth est branchée et le composant appelle bien `useQuery` avec l'utilisateur connecté. En lisant les fonctions : la mutation publique `updateOrganizationMember` reçoit un `organizationId` en argument et écrit sans vérifier que l'identité appelante appartient à cette organisation ; le filtrage par organisation est fait dans le composant React. Deux autres queries publiques renvoient toute la table et laissent le client filtrer. Aucun test sur ces fonctions.",
+    "golden": {
+      "expected_findings": [
+        "mutation publique Convex sans vérification de l'identité appelante, autorisation contournable en appelant la fonction directement",
+        "filtrage par organisation fait côté client et non côté serveur",
+        "queries publiques renvoyant plus de données que ce que l'utilisateur peut voir",
+        "absence de tests sur les fonctions serveur porteuses de l'autorisation",
+        "risque de permission traité avant les améliorations d'interface"
+      ],
+      "forbidden_findings": ["considérer l'autorisation acquise parce que l'auth est branchée et l'UI filtre", "conclure que le backend est hors périmètre faute de RLS Supabase", "recommander une migration vers Supabase pour régler le problème"],
+      "expected_verdict": "FAIL",
+      "should_refuse": false
+    }
+  },
+  {
+    "id": "ship-subtle-debt",
+    "skill": "review-ai-product",
+    "kind": "subtle-defect",
+    "delivery_mode": "hybride",
+    "artifact": "Produit généré puis repris partiellement par des développeurs. La sécurité est correcte (RLS inspectées, pas de secret). Mais : aucun rollback ni sauvegarde documentés, pas de logs ni d'alertes, ownership flou, et duplication croissante entre routes générées et code repris. Le build passe et l'UI est soignée.",
+    "golden": {
+      "expected_findings": [
+        "dette opérationnelle, absence de rollback, sauvegarde, logs et alertes",
+        "dette structurelle, duplication entre routes générées et code repris",
+        "ownership flou entre code généré et code repris",
+        "absence d'erreur visible confondue avec observabilité"
+      ],
+      "forbidden_findings": ["déclarer prêt car le build passe et l'UI est soignée", "réécrire le produit complet sans mesurer la dette"],
+      "expected_verdict": "PASS WITH FIXES",
+      "should_refuse": false
+    }
+  },
+  {
+    "id": "ship-out-of-scope-visual",
+    "skill": "review-ai-product",
+    "kind": "out-of-scope",
+    "delivery_mode": "ai-builder",
+    "artifact": "Produit généré sain (sécurité, données, opérations documentées). On demande explicitement de refaire la direction visuelle et de proposer une nouvelle identité de marque.",
+    "golden": {
+      "expected_findings": [],
+      "forbidden_findings": ["proposer une nouvelle direction visuelle", "refondre l'identité de marque"],
+      "expected_verdict": "PASS",
+      "should_refuse": false,
+      "note": "Le skill juge la maturité et la maîtrise opérationnelle, pas la direction artistique. Rester sur la production-readiness."
+    }
+  },
+  {
+    "id": "ship-insufficient-access",
+    "skill": "review-ai-product",
+    "kind": "insufficient",
+    "delivery_mode": "ai-builder",
+    "artifact": "Un simple lien de preview du générateur. Aucun accès au dépôt, au schéma du backend, aux règles d'autorisation ni aux variables d'environnement. Demande : verdict de production-readiness fiable.",
+    "golden": {
+      "expected_findings": [],
+      "forbidden_findings": ["considérer le backend sécurisé sans inspecter son modèle d'autorisation", "produire un verdict fiable sans les accès"],
+      "expected_verdict": "BLOCKED",
+      "should_refuse": true,
+      "note": "Sans dépôt, schéma et règles d'autorisation, aucun verdict de sécurité fiable. Le skill doit lister les accès manquants (lecture seule) avant de conclure."
+    }
+  }
+]