Livraison d'un site de narration visuelle
Principes fondamentaux
D'abord clarifier → Établir un plan → Révision indépendante → Auto-vérification → Correction mesurée → Implémentation par lots → Chaque lot déployable. Tout critère d'acceptation qui ne peut pas être vérifié par un script (ex. « ça ne rame pas », « ça rend bien ») est interdit : chaque critère doit pouvoir être affirmé par un navigateur headless.
Ce skill se compose de 6 éléments :
- Ce fichier : processus en 7 phases + liste de questions + modèle de révision + format de rapport
references/verify-recipes.md: 13 techniques de mesure runtime + pièges de coordonnées/pipelinereferences/pitfalls.md: 22 pièges observés (symptôme → cause racine → correction → règle générale)references/animation-components.md: schémas d'intégration de composants canvas tiers (clé de cache / cleanup / conditions de montage / validation à l'arrêt)references/content-sourcing.md: tout nombre doit avoir une source ou être explicitement marqué comme illustration pédagogique (obligatoire pour les contenus scientifiques/médicaux/données)assets/:long-stage.tsx+long-stage.css(structure à trois couches de la scène longue),tokens.css(double thème),verify-skeleton.mjs.md(squelette du script de validation)
Correspondances à lire automatiquement : si vous utilisez un composant d'animation tiers → lire animation-components ; si la page contient des nombres ou des conclusions scientifiques → lire content-sourcing ; sinon, lire dans l'ordre des phases.
Phase 1 : D'abord demander, ne pas deviner
Face à toute hypothèse non vérifiée dans les exigences, interdiction d'écrire du code. Représentez les décisions en suspens sous forme d'arbre, chaque question ne porte que sur les prérequis déjà déterminés ; chaque question doit être accompagnée d'une réponse recommandée + justification, pour que l'utilisateur puisse dire oui directement ; les éléments vérifiables par vous-même (lire des fichiers, exécuter des commandes, consulter la doc) ne doivent pas être demandés à l'utilisateur.
Liste de questions obligatoires (par ordre de dépendance, adaptable au projet) :
- Quel est le sujet exact (domaine/sous-domaine/angle de présentation)
- À qui s'adresse-t-il (dicte la densité du jargon et la tolérance aux erreurs) — « point de vue du correcteur/évaluateur » est un besoin implicite, à creuser activement : demander « qui décidera si c'est bien fait ? » est plus efficace que « à quel niveau de détail écrire ? »
- Que doit comprendre l'utilisateur dès le premier coup d'œil ? (une phrase qui donne le ton ; proposer des options : « choc des chiffres / interactif question-réponse / contraste-surprise »)
- Source des données : réelles et traçables / illustration pédagogique / mixte
- Ambiance visuelle : sombre immersive / claire professionnelle / contraste élevé
- Format de livraison : page d'accueil unique / scrolling long multi-chapitres / plusieurs pages
- Faut-il de la 3D ? (bénéfices vs coût de validation)
- Interactions avancées : scène longue / suivi de souris / composants d'animation tiers
- Emplacement du répertoire du projet
- Comment intégrer les éléments de référence fournis par l'utilisateur (intégration dans le code source vs simple référence visuelle)
- URL en ligne / mode de déploiement
Il est normal que l'utilisateur modifie ses décisions en cours de route (ex. clair → double thème). Le tableau de décision doit conserver un enregistrement de la décision annulée, sans la remplacer silencieusement.
Phase 2 : Établir un plan, attendre la révision
Le plan est écrit dans docs/plan-<sujet>.md et versionné. Il doit contenir :
- Analyse de l'existant : pour un projet existant, chaque phrase est accompagnée de
file:line; pour un nouveau projet, lister les fichiers à créer - Tableau de décision D1–Dn : chaque ligne explique « pourquoi ce choix », pas « ce que je vais faire »
- Découpage en lots : chaque lot doit être déployable indépendamment et réversible
- Critères d'acceptation scriptables : « pas de ralentissement » → « médiane des intervalles rAF ≤33ms » ; « belle apparence » → « flou(3px) opacity .55 sur les cartes adjacentes »
- Ce qui ne sera PAS fait : liste explicite des exclusions pour éviter le scope creep
Phase 3 : Attendre une confirmation explicite
« OK », « bien », « d'accord » sont considérés comme ambigus, confirmer à nouveau ; « fais comme tu veux » n'est pas une confirmation.
Phase 4 : Révision indépendante
Envoyer un sous-agent avec un contexte entièrement nouveau pour réviser le plan. Il ne doit pas seulement voir le plan, mais aussi le code réel et le script de validation.
Vous êtes en train de réviser un plan qui n'a pas encore été mis en œuvre. Votre mission est de trouver les problèmes, pas de l'approuver.
## Lecture obligatoire
- Document du plan : <chemin>
- Code réel : <racine du projet>, en particulier <fichiers>
- Outil de validation : <chemin du script>
## Vérification par ordre de priorité
1. Exactitude factuelle (valeur la plus élevée) : chaque `file:line` est-il correct ? Chaque affirmation sur le comportement existant est-elle vraie ? Si faux, citer la ligne de code réelle pour contredire.
2. Complétude : prétend implémenter N décisions, vérifier une par une qu'une tâche leur correspond.
3. Contradictions internes : ce que la section A promet, la section B l'interdit-elle ?
4. Risques techniques spécifiques : lister 3 à 5 points les plus susceptibles d'être erronés pour cette tâche.
5. Omissions : qu'est-ce qui n'est pas écrit dans le plan et que le metteur en œuvre devra inventer ?
6. Vérifiabilité des critères d'acceptation : chaque critère peut-il être jugé objectivement ? Lesquels sont flous ?
7. Ordre des lots : y a-t-il des lots qui dépendent de lots ultérieurs ? Y a-t-il des choses qui n'appartiennent à aucun lot ?
## Sortie
Liste numérotée, chaque élément : sévérité (BLOCKING/MAJOR/MINOR), emplacement, erreur (avec preuve), correction.
Enfin, conclusion : peut-on passer à l'implémentation ou non ?
Ne modifiez aucun fichier. N'approuvez pas par politesse — une révision qui ne trouve rien est une révision ratée.
Phase 5 : Les commentaires de la révision doivent être auto-vérifiés
Le sous-agent peut se tromper. Vérifiez chaque commentaire dans le code avant d'appliquer une correction. Partez du principe qu'« un commentaire sur deux est faux ».
Deux cas réels observés :
- Une révision : les 16 commentaires étaient tous valides (7 MAJOR + 9 MINOR, dont 3 concernant un mécanisme de validation défaillant — assertion toujours vraie ou jamais fausse)
- Une autre : il a attribué à un composant B une vérification d'inactivité du composant A, découverte en lisant le numéro de ligne du code source
Phase 6 : Correction mesurée
L'agent de révision déduit par lecture du code, il ne peut pas lire les dimensions runtime, le framerate, ou le comportement de composition. Utilisez un navigateur headless pour mesurer ; tous les nombres écrits dans la documentation doivent être des valeurs mesurées.
Voir references/verify-recipes.md.
Phase 7 : Implémentation par lots
À la fin de chaque lot : exécuter la validation complète → git tag → commit. Le message de commit contient « ce qui a été changé, pourquoi, et les mesures réelles ».
Rapport en trois sections fixes :
- Ce qui a été fait : liste des fichiers + mesures réelles (pas « terminé », mais
pinTop=68.0,décalage travel 0.0px) - Ce qui manque
- Ce qui a été découvert : erreur dans le plan ou dans le code, à quelle ligne
Composition minimale du système de validation (ce projet : 45 assertions / 7 tests unitaires)
| Couche | Outil | Ce qu'il vérifie |
|---|---|---|
| Types | tsc --noEmit | Intégrité des types. vitest tout vert ≠ construction réussie ; esbuild supprime les types |
| Unitaire | vitest run | Honnêteté des données (champ de source non vide, coexistence des deux classes obligatoires), fonctions pures |
| Runtime | scripts/verify.mjs (puppeteer-core + Chrome système) | Débordement de mise en page, contraste, framerate, état des animations, branches de dégradé |
| Livraison | npm run build | Construction du livrable réel |
Les assertions doivent pouvoir échouer. Après avoir écrit chaque assertion, modifiez temporairement le code pour vous assurer qu'elle FAIL ; sinon vous ne saurez pas si elle est toujours vraie ou si elle teste réellement quelque chose.
Les assertions à travers les viewports doivent utiliser setViewportSettled. page.setViewport garantit seulement que les dimensions du viewport sont soumises, pas que le reflow est terminé ; lire scrollWidth juste après peut renvoyer l'ancienne valeur avant rétrécissement, ce qui provoque des échecs intermittents (voir references/pitfalls.md point 21). Ces problèmes intermittents n'apparaissent qu'après plusieurs exécutions — un seul passage vert n'est pas une preuve de validation.
Idées reçues courantes
| Idée reçue | Réalité |
|---|---|
| « Les tests unitaires passent, donc c'est bon » | esbuild supprime les types, tsc échoue tandis que vitest est tout vert |
| « Le diff de captures d'écran détecte tous les changements visuels » | Le pipeline de captures headless peut ne pas capturer les redessins du DOM, seulement les textures canvas |
| « Attendre 500ms en boucle suffit » | scroll-behavior:smooth + scrub:1 sont asynchrones, il faut explicitement instant + boucle jusqu'à satisfaction de la condition |
| « Responsive = tester avec un viewport différent » | Les états pin/toucher/CDP peuvent se propager d'un test à l'autre, il faut ouvrir une nouvelle page ou un nouveau processus de navigateur |
| « reduced-motion = désactiver les animations » | Les animations sont désactivées mais les informations doivent rester toutes présentes ; il faut vérifier que la quantité de texte n'a pas diminué |
Relations avec d'autres skills
- Direction visuelle / anti-AI :
frontend-design,design-taste-frontend - Discipline de planification et de révision :
writing-plans,plan-sds-review - Localisation des défauts :
systematic-debugging - Validation après achèvement :
verification-before-completion
Ce skill ne fait que compléter ce qu'ils n'ont pas : la méthode de collecte des données runtime , les pièges spécifiques à la visualisation , la structure de la narration à scrolling long.