/video-new
Écrire, avant toute construction, ce que la vidéo doit expliquer et ce qu'elle peut affirmer, et obtenir la signature du relecteur pour les deux. Puis s'arrêter.
Pourquoi cela existe : dans la production d'où viennent ces compétences, 9 versions sur 26 ont été causées par une vidéo qui n'expliquait pas une fonctionnalité importante pour le relecteur. Personne n'avait écrit ces fonctionnalités avant de construire, donc chacune est apparue lors d'une relecture, a coûté un rendu complet et un cycle d'assurance qualité, puis a dû être appliquée manuellement à toutes les autres vidéos. Le positionnement et les arguments ont coûté 3 versions supplémentaires de la même manière. Deux fiches signées en amont coûtent moins cher que n'importe laquelle de ces itérations.
Avant de commencer
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
Trouver le produit : le dossier parent le plus proche au-dessus du répertoire courant qui contient un fichier product.yaml. S'il n'y en a pas, dire à l'utilisateur d'exécuter /product-new d'abord (vous ne pouvez pas l'exécuter à sa place : c'est une commande utilisateur). Lire product.yaml, kit/RULES.md et le BRIEF de toute vidéo sœur dans videos/ : la matrice de couverture et les arguments d'une sœur constituent le meilleur point de départ, et le casting doit rester identique d'une vidéo à l'autre.
L'identifiant de la vidéo provient de l'argument (minuscules, chiffres, tirets). Si videos/<video>/ existe déjà, s'arrêter : une vidéo existante progresse avec /video-review, jamais en recommençant de zéro.
1. Demander à quoi sert la vidéo
Un seul message, au maximum quatre questions, chacune avec une proposition par défaut :
- Qui la regarde et où elle est publiée (pitch deck, courte visite guidée du produit, page de documentation, onboarding, boucle d'accueil).
- Ce que le spectateur doit croire ou être capable de faire après avoir vu la vidéo (une phrase).
- Durée approximative (par défaut : pitch 90 s, visite 30 s, documentation 120 s, tutoriel 240 s, boucle 15 s). Une visite guidée est un pitch réduit à une ou deux fonctionnalités : même ouverture, même écran de fin et même habillage, moins de chapitres. La choisir quand le relecteur dit « visite rapide » ou demande moins de 45 s.
- Quelles fonctionnalités comptent le plus pour le relecteur. Les demander par leur nom, et demander lesquelles doivent être montrées en fonctionnement plutôt que simplement mentionnées.
2. Créer le dossier
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/video-new/scripts/new_video.py" <product_dir> <video> \
--format <format> [--title "<title>"] [--duration <s>]
Il copie _template/video, remplit les métadonnées du BRIEF (titre, vidéo, format, durée, langue et relecteur depuis product.yaml, version 1) et laisse les deux signatures vides. Il refuse un identifiant en double.
3. Rédiger les trois fiches
Lire references/sheets.md pour le format de chaque fiche et des exemples de lignes avant d'écrire.
- BRIEF.md : intention (citer les propres mots de l'utilisateur), public, les chapitres proposés, notes avec chaque nom fictif et numéro que la vidéo utilisera (depuis le casting du produit, jamais de nouveaux sans demander), et une entrée de journal des modifications vide pour la v1.
- COVERAGE.md : une ligne par fonctionnalité avec « doit expliquer à l'écran ? oui/non », le chapitre qui l'explique, et la preuve (ce que le spectateur voit se produire). Une fonctionnalité simplement nommée sur l'écran de fin n'est pas couverte : c'est exactement l'écart qui a coûté le plus de versions. Inclure les parties configurables (paramètres, déclencheurs y compris planifiés, transfert, relances) car ce sont les fonctionnalités que les relecteurs ont continuellement demandées après coup.
- CLAIMS.md : la ligne de positionnement (depuis
product.yaml, jamais d'un document marketing), les formulations à éviter (never_sayplus tout ce que l'utilisateur ajoute), chaque argument que la narration veut avancer et qui nécessite une approbation, les accroches approuvées, et les noms de produit canoniques par rapport à leurs anciennes appellations.
Vérifier chaque argument et fonctionnalité par rapport à ce que vous pouvez voir dans sources/ et la documentation. Si le produit ne fait pas quelque chose que l'utilisateur a demandé, le signaler avec une question fermée et une option recommandée (« ne montrer que ce qui existe » est généralement le bon choix par défaut). Ne pas inscrire dans la matrice une fonctionnalité que le code ne peut pas justifier.
4. Proposer les chapitres
Ajouter le tableau des chapitres dans BRIEF.md. Une idée par chapitre, un cadrage par chapitre, chaque fonctionnalité « doit expliquer » associée à un chapitre. Commencer par le contexte (le nom du produit et une ligne sur ce qu'il est), jamais en milieu d'interface utilisateur. Cadrer toute la page à 1x par défaut ; les zooms profonds ont été rejetés deux fois dans la production d'origine. Terminer par l'étendue (ce que le produit fait d'autre), puis l'habillage final.
5. S'arrêter et demander les signatures
Afficher à l'utilisateur, en un seul message :
- La matrice de couverture (les lignes « oui ») et le tableau des chapitres.
- La ligne de positionnement, les arguments nécessitant une approbation, et l'accroche proposée.
- Au maximum trois décisions fermées, chacune avec un choix par défaut (par exemple l'accroche, un nom de casting, l'omission d'une fonctionnalité). Indiquer ce que signifie le silence : le choix par défaut.
Puis demander au relecteur de signer. Soit il écrit lui-même son nom dans coverage_signed_by et claims_signed_by dans BRIEF.md, soit il vous dit en ses propres termes de signer en son nom, et vous exécutez :
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/video-new/scripts/sign.py" <video_dir> \
--coverage "<nom du relecteur>" --claims "<nom du relecteur>"
Ne jamais signer de votre propre initiative, ne jamais signer parce que les fiches « semblent complètes », ne jamais signer avec un nom que le relecteur n'a pas donné. La signature est la déclaration du relecteur que la matrice est ce sur quoi il jugera la vidéo. sign.py refuse une matrice vide ou une ligne de positionnement manquante ; sans indicateur, il affiche seulement l'état.
Ne pas construire, rendre, enregistrer de narration ni répartir des sous-agents ici, même si l'utilisateur signe dans le même message. La construction est /video-build, tapé par l'utilisateur. Cette séparation est ce qui empêche l'agent de lancer une construction coûteuse sur un brief non signé.
Rapport
| Élément | Valeur |
|---|---|
| Vidéo | videos/<video>/, format, durée cible |
| Couverture | N fonctionnalités à expliquer à l'écran, M listées seulement, chapitres |
| Arguments | positionnement, arguments en attente d'approbation |
| Décisions | les trois questions fermées maximum et leurs choix par défaut |
| Signatures | non signé (ou signé par qui) |
Ensuite, une fois signée : /video-build <video>.