Vérité produit
Une vidéo produit qui montre quelque chose que le produit ne peut pas faire est pire qu'absence de vidéo. Dans la production d'où proviennent ces compétences, les moments les plus coûteux étaient tous des échecs de vérité : un badge fabriqué à la main avec la mauvaise taille et le mauvais nom de produit, un workflow narré comme « en attendant le résultat de l'appel » alors que le produit ne renvoie les résultats que par un déclencheur séparé, un appel test re-étiqueté comme une réservation confirmée que personne n'avait vérifiée de bout en bout, et un document d'entreprise dont le titre contredisait le positionnement que l'équipe avait accepté. Chacun a été détecté tardivement, par un relecteur, et a coûté une version.
Cette compétence rend la vérification explicite et mécanique : chaque ligne et chaque écran obtient une ligne dans
TRUTH.md avec une source, et truth_check.py refuse une vidéo où une ligne est manquante, obsolète ou
non étayée.
Entrées
videos/<video>/audio/lines.tsv(la narration, une phrase par identifiant de ligne)videos/<video>/SOURCES.md(de source-recon : les écrans et leur code)videos/<video>/BRIEF.md,COVERAGE.md,CLAIMS.md(ce que la vidéo doit expliquer, le positionnement, les phrases à éviter, les affirmations qui nécessitent une approbation)product.yaml:positioning,never_say,names(nom canonique vers chaînes héritées),banned_termssources/<role>/etsources.lock(épinglé par source-recon ; s'il manque, exécutez d'abord source-recon, car les citations doivent pointer vers le commit verrouillé)
1. Lister les affirmations
Divisez chaque ligne de lines.tsv en les affirmations qu'elle fait. « Acme Tasks lit votre calendrier et déplace les tâches en retard à demain » est deux affirmations : il lit le calendrier, et il déplace les tâches en retard. Ajoutez une affirmation par écran et par action à l'écran de SOURCES.md et des chapitres (« cliquer sur Planifier ma journée ouvre le planificateur avec trois suggestions »).
Écrivez les questions que ces affirmations soulèvent, formulées pour que le code puisse y répondre : qu'est-ce qui déclenche cela, qu'est-ce qui est stocké, quelles options existent, ce que l'utilisateur voit et où, ce qui se passe uniquement sur le serveur.
2. Répondre à partir du code et de la documentation
Lancez des sous-agents en lecture seule en parallèle, un par domaine produit (comportement frontend, chaque backend,
docs), avec l'invite dans references/product-facts-prompt.md. Pointez-les vers sources/<role>/,
jamais vers le checkout de l'utilisateur, pour que leurs numéros de ligne correspondent au verrou. Ils répondent
uniquement à partir du code ou de la documentation, citent chaque fait, et disent « non trouvé » au lieu de deviner.
3. Classifier chaque affirmation
| visibilité | signifie | la vidéo peut |
|---|---|---|
ui | Rendu par le frontend ; citez le template ou la ligne i18n | le montrer et le narrer |
backend | Vrai sur le serveur, rien à l'écran ne le montre | le narrer, ne jamais dessiner d'UI pour cela |
docs | Seule la documentation le dit | le narrer avec l'URL de la doc ; vérifiez que le code est d'accord quand il le peut |
mock | Un élément conçu, pas une UI produit (un écran d'appel téléphonique, une carte de fin, du texte généré) | le montrer, marqué comme conçu dans le BRIEF |
| verdict | signifie |
|---|---|
backed | la source dit exactement cela |
approved | nécessitait une approbation (restreint, non publié, une affirmation que CLAIMS.md liste) et le relecteur l'a donnée dans CLAIMS.md |
needs-approval | vrai, mais restreint, soumis à restriction, non publié ou listé dans CLAIMS.md ; en attente du relecteur |
rewrite | partiellement vrai ; vous proposez un libellé étayé dans les notes |
cut | pas vrai, ou aucune source trouvée |
unbacked | pas encore vérifié |
mock | avec la visibilité mock uniquement |
Seuls backed et approved passent pour les lignes narrées. Une fonctionnalité restreinte (visible uniquement par certains
rôles, plans ou équipes internes), une fonctionnalité derrière un drapeau, ou une fonctionnalité sur une branche non fusionnée est
needs-approval jusqu'à ce que le relecteur dise oui dans CLAIMS.md, et le BRIEF note qu'elle est
restreinte. Cela s'est produit dans la production source : une fonctionnalité que seul le personnel interne pouvait voir a été
montrée à la demande du relecteur, et marquée.
4. Corriger ce qui ne tient pas
- Réécrire une phrase partiellement vraie dans la version la plus forte que la source supporte. Gardez le sens que l'auteur voulait ; changez les mécanismes pour les vrais.
- Couper ce qui n'a pas de source. Ne l'adoucissez pas en quelque chose de vague ; les affirmations vagues sont toujours des affirmations.
- Ne laissez jamais une étiquette dériver. Un élément conçu marqué « illustratif » ne doit pas perdre cette étiquette pour des raisons esthétiques plus tard sans re-vérifier l'affirmation que la version non étiquetée fait.
- Le positionnement prime sur les documents. Si un deck ou un PRD dit quelque chose que
never_sayou CLAIMS.md interdit, la règle gagne et la phrase change. - Noms actuels uniquement. Utilisez les noms canoniques dans
product.yaml names, même lorsque l'UI en direct ou le code montre encore une chaîne héritée. Fouillez lines.tsv, les specs et les templates pour chaque chaîne héritée et chaque entréebanned_terms(concurrents, fournisseurs tiers que l'équipe garde hors écran, vrais clients) et corrigez chaque occurrence.
5. Lorsqu'une demande entre en conflit avec le produit
Lorsque le brief ou le relecteur demande quelque chose que le code ne supporte pas, ne construisez pas un faux et ne le supprimez pas silencieusement. Posez une question fermée avec des options et une valeur par défaut recommandée, et gardez au maximum trois questions de ce type par tour, car les listes ouvertes de vetos restent sans réponse et le silence devient une décision que personne n'a prise. Le modèle « seulement ce qui est réel » :
Le brief montre Acme Tasks réservant la salle de réunion elle-même. Le code crée uniquement la tâche et lie le calendrier de la salle (frontend/src/rooms/LinkRoom.tsx:22@1a2b3c4) ; la réservation se fait dans l'application de calendrier. Laquelle ?
- Seulement ce qui est réel (recommandé) : montrez l'étape de liaison et dites « lie le calendrier de la salle ».
- Montrez l'écran de réservation de l'application de calendrier comme un élément conçu, étiqueté, et narrez-le comme l'étape du calendrier.
- Supprimez le temps.
Enregistrez la réponse dans CLAIMS.md et définissez le verdict à partir de celle-ci.
6. Écrire TRUTH.md
# Vérité : <video>
Verrouillé : frontend main@1a2b3c4, backend main@5d6e7f8. Vérifié : 2026-01-12.
| id | phrase | source | visibilité | verdict | notes |
|---|---|---|---|---|---|
| N1 | Acme Tasks planifie votre journée à partir de votre calendrier. | frontend/src/planner/plan.ts:31@1a2b3c4; https://docs.example.com/planner | ui | backed | |
| N2 | Les tâches en retard passent à demain à minuit. | backend/jobs/rollover.py:12-30@5d6e7f8 | backend | backed | non affiché à l'écran |
| screen:board | Tableau avec trois tâches, dont une en retard | frontend/src/pages/board/BoardPage.tsx:14@1a2b3c4 | ui | backed | |
| screen:call | Appel téléphonique avec le client | (conçu) | mock | mock | marqué dans BRIEF |
## Questions ouvertes
1. <question fermée avec une réponse recommandée>
Une ligne par identifiant de ligne de lines.tsv, avec la phrase copiée exactement (la vérification les compare, donc
modifier une ligne après le passage de vérification échoue jusqu'à ce que vous la re-vérifiiez). Une ligne par écran, avec l'id
screen:<name> correspondant à SOURCES.md. Plusieurs citations vont dans une seule cellule, séparées par ;.
7. Vérifier
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/product-truth/scripts/truth_check.py" <video_dir>
Il échoue sur une ligne sans ligne correspondante, une phrase modifiée, un verdict autre que backed ou approved sur une ligne narrée, une citation dont le rôle n'est pas verrouillé, dont le sha n'est pas celui du verrou (le code a bougé ; re-vérifiez), dont le fichier n'est pas dans l'export, ou dont la ligne dépasse la fin du fichier. Corrigez chaque échec ; ne modifiez pas la vérification.
Rapportez à l'utilisateur : combien de lignes et d'écrans sont étayés, ce que vous avez réécrit et coupé (avec la raison), ce qui attend une approbation, et les questions ouvertes.