carnufex/pr-demo

Démo PR

Un·e réviseur·e doit comprendre un changement en moins d'une minute sans ouvrir le diff : ce qui a changé, comment ça fonctionne maintenant, la preuve que ça marche, et où regarder. Les faits du dépôt — langue des légendes, comment enregistrer le flux modifié, où publier — se trouvent dans .claude/profiles/delivery.md (Demo, Notify).

Court et percutant bat complet. Cinq scènes en 30 secondes, dans cet ordre, et omettez ce que le changement n'a pas plutôt que de le remplir :

1. Ce qui a changé — le titre et au maximum trois puces.
2. Comment ça fonctionne maintenant — le flux, avec le nœud modifié marqué.
3. Avant et après — uniquement pour quelque chose de visible ; sautez-le pour un changement backend.
4. Le correctif en action — l'enregistrement, recadré sur la partie qui compte, moins de 12 s.
5. Preuve — les vérifications de la clé de revue et les tests dans une seule scène key. Ils répondent à la même question, donc ils n'ont pas chacun leur scène.

1. Rassembler le matériel

Dans out/demo/<pr ou issue>/ (ignoré par git) :

• Les preuves de la clé de revue : out/review-key/<n>/result.json et le verdict du key-reviewer (review-key).
• Captures d'écran pour un changement visible : la même vue avant (branche de base) et après, même taille et mêmes données. Recadrez sur la partie qui a changé ; une page entière à 1280 px rend le changement trop petit pour être vu.
• Un enregistrement du flux modifié (la commande Demo du profil, ou Playwright avec browser.newContext({ recordVideo: { dir, size: { width: 1280, height: 800 } }, viewport: { width: 1280, height: 800 } }) autour des étapes du test e2e qui le couvre ; le fichier apparaît lorsque le contexte se ferme). Gardez-le sous 20 s : commencez sur l'écran qui compte, pas de connexions en vidéo.
• Le flux du changement sous forme de flowchart LR (ou TD) mermaid : cinq à neuf nœuds, le chemin de l'utilisateur ou de la requête, avec :::changed sur ce qui a changé, :::added sur ce qui est nouveau et :::removed sur ce qui a disparu. Expliquez le comportement, pas les fichiers.
• Les tests qui ont été exécutés, avec un nombre chacun (476 tests, 12 flows).

2. Écrire demo.json

À côté du matériel (les chemins sont relatifs). Texte dans la langue de légende du profil ; court — une scène est lue en ses secondes. Les backticks et **gras** fonctionnent.

{
  "lang": "fr",
  "brand": "**boutique** · PR #352",
  "ref": "Ferme #331",
  "kicker": "Correction de bug",
  "title": "Le checkout tient à 1280 px",
  "subtitle": "Le bouton de paiement recouvrait le panier, et le champ coupon faisait 49 px de large.",
  "chips": [{ "text": "Clé de revue : PASS", "ok": true }, "3 fichiers"],
  "scenes": [
    { "type": "title", "seconds": 3 },
    { "type": "bullets", "items": ["…", "…", "…"], "seconds": 5 },
    { "type": "flow", "mermaid": "flowchart LR\n  A[Largeur] --> B{\"< 1440 px ?\"}\n  B -- oui --> C[Icônes]:::changed", "seconds": 6 },
    { "type": "compare", "before": "before.png", "after": "after.png", "seconds": 5 },
    { "type": "clip", "heading": "Enregistré à 1280 px", "src": "run.webm", "caption": "e2e : checkout-fit", "speed": 1.5, "maxSeconds": 12 },
    { "type": "key", "result": "../../review-key/331/result.json", "baseFails": true, "seconds": 7,
      "rows": [{ "ok": true, "text": "`verify.sh` · 476 tests" }] },
    { "type": "end", "title": "Prêt pour la revue", "lines": ["PR : **github.com/…/pull/352**", "3 am : …"], "seconds": 3 }
  ]
}

Scènes : title, bullets (items, au plus quatre), flow (mermaid, legend: false pour masquer la légende), compare (before, after, étiquettes ; layout: "stack" les place l'une au-dessus de l'autre, pour les bandes larges comme une barre d'outils), clip (src .webm/.mp4, from/to secondes, speed, maxSeconds par défaut 20, crop {x, y, w, h} en pixels de l'enregistrement pour zoomer sur la partie qui compte ; sa durée vient du fichier), key (result = result.json de keycheck ou un objet ; verdict, baseFails, claim, rows et count {value, total, label} en remplacement — par ex. une vérification qui exécute huit cas se lit mieux comme 8/8), checks (items avec name, detail, ok), end (title, lines). Chaque scène accepte heading, kicker et seconds. Omettez ce que le changement n'a pas — un changement backend n'a pas de compare ou clip ; un pur refactoring a une scène key avec parité et peu d'autre.

Le panneau gauche de la scène key contient jusqu'à huit lignes et prend vos rows avant les vérifications de la clé, donc les tests y vont comme une ligne chacun ("verify.sh · 476 tests") au lieu d'une scène checks après. Utilisez une scène checks séparée seulement lorsqu'il n'y a pas de clé de revue à afficher.

Formulation

Les légendes sont lues dans les secondes où elles sont à l'écran, donc chaque mot doit porter. Trois règles, apprises de démos qui ont agacé leur lecteur :

• Énoncez le résultat, ne le louez pas. Le tampon du verdict et « vérifié indépendamment par key-reviewer » disent déjà que la clé est passée et qui l'a vérifiée. Ajouter « PASS, pas de triche » ou « entièrement vérifié » donne l'impression que l'auteur note son propre devoir. N'éditorialisez jamais sur le verdict.
• Les étiquettes de comptage sont des noms simples : checks pass, cas identiques, tests. Un verbe comme échec/échoue comme étiquette transforme « 5/5 » en une phrase qui se lit à l'envers — « 5 sur 5 échouent » donne l'impression que le changement est cassé alors que cela signifie que la branche de base l'est. Si vous devez dire que la base échoue, c'est la ligne baseFails, qui se formule elle-même.
• Pas de remplissage. Supprimez « avec succès », « comme prévu », « cela garantit que », et toute puce qui reformule le titre. Si une puce ferait dire à un·e réviseur·e « oui, évidemment », ce n'est pas une puce.

3. Rendu

node <chemin du répertoire de cette compétence>/scripts/render-demo.mjs out/demo/<n>/demo.json [--webm]

Il dessine chaque scène dans Chromium image par image (texte net, aucune image sautée) et encode demo.mp4 (H.264, jouable en ligne dans Slack, GitHub et les navigateurs), demo.png (une affiche : la scène de flux ou de clé) et, avec --webm, un VP9 demo.webm. Il nécessite ffmpeg et utilise Playwright du projet, sinon l'installe une fois dans ~/.cache/carnufex-showcase. Environ une seconde de rendu par seconde de vidéo.

Regardez-le avant d'envoyer : extrayez des images de chaque scène (ffmpeg -ss <t> -i demo.mp4 -frames:v 1 f.png) et examinez-les. Texte coupé, diagramme vide, extrait d'écran de connexion : corrigez et rendez à nouveau.

4. Publier

Sur le canal que nomme Notify du profil, en tant que bot, afin que la personne reçoive une vraie notification (un message posté via un connecteur Slack vient de la personne elle-même, et Slack ne notifie personne de ses propres messages). Un fil par PR : la démo commence le fil de la PR ; tout ce qui suit — CI, cycles de revue, fusion, déploiement, vérification en direct, rollback — est une réponse dans ce fil (ship publie ces messages). Le canal reste une ligne par PR, tous dépôts confondus. Écrivez le message dans un fichier ; il doit se suffire à lui-même (mrkdwn Slack) et commencer par le dépôt :

*<dépôt>* · PR #<n> · <titre> — prêt pour la revue
<URL de la PR>
• <ce qui a changé, ligne 1>
• <ligne 2>
Clé de revue (<type>) : *PASS*, vérifié indépendamment : <une ligne du verdict>
3 am : <signal>

node <chemin du répertoire de cette compétence>/scripts/post-slack.mjs --channel <id> --pr <URL de la PR> --file out/demo/<n>/demo.mp4 --title "<dépôt> PR #<n>: <titre> (<secondes> s)" --comment-file out/demo/<n>/message.md
node <chemin du répertoire de cette compétence>/scripts/post-slack.mjs --channel <id> --pr <URL de la PR> --text-file update.md [--broadcast]

--pr trouve le fil de la PR par son URL dans le canal (aucun état persistant) : trouvé, le message va dans le fil ; non trouvé, il le commence. --text-file publie un message sans fichier ; --broadcast montre également une réponse de fil dans le canal (utilisez-le pour le résultat : en direct, ou rollback). Il imprime le fil et le permalien. Le jeton du bot vient de SLACK_BOT_TOKEN ou du plugin slack-channel dans ~/.claude/channels/slack/.env ; le bot doit être dans le canal (not_in_channel : /invite @<bot>). Sans bot, reculez sur le connecteur Slack (slack_get_file_upload_url → POST des octets → slack_complete_file_upload), et dites qu'aucune notification ne part.

Placez les mêmes trois lignes, le diagramme mermaid et le lien Slack dans la description de la PR (GitHub dessine mermaid ; il ne lit pas une vidéo téléchargée via l'API).