Video-QA

Que fait Video-QA ?

Critique d'une démo MP4 par rapport à son storyboard prévu et retourne la checklist horodatée qu'un relecteur humain avisé écrirait. Deux couches : une sonde déterministe (ffmpeg/ffprobe/node — détection mécanique, aucun raisonnement de modèle) et un sous-agent d'analyse frais qui raisonne sur le rapport JSON compact de la sonde + un ensemble limité d'images extraites, en fonction du script.

Règle impérative : l'analyse s'effectue TOUJOURS dans un sous-agent frais

L'appelant (vous, dans le thread principal) fait le minimum :

1. Localiser les entrées.
2. Exécuter le script de sonde.
3. Créer un sous-agent frais et indépendant (l'outil Agent) pour effectuer l'analyse.
4. Transmettre la liste d'issues du sous-agent à l'utilisateur.

Ne lisez jamais les images extraites et ne raisonnez jamais sur le rapport vous-même dans le thread appelant. Tout l'intérêt est l'isolation des tokens : une vidéo de 5 minutes produit ~50 images et un rapport JSON volumineux ; raisonner dessus coûte des dizaines de milliers de tokens d'images + analyse. Si cela atterrit dans le contexte de l'appelant, cela empoisonne le reste de la session. Le sous-agent absorbe cela et ne retourne que la courte liste d'issues. Ce n'est pas optionnel ou "quand c'est pratique" — chaque invocation de video-qa effectue un transfert. Voir references/handoff.md.

Étape 1 — Rassembler les entrées

Vous avez besoin de :

• Chemin de la vidéo — le MP4 à QA (le montage final/assemblé qu'un relecteur regarderait).
• Storyboard / script — les séquences prévues dans l'ordre, les attentes temporelles et ce que chaque segment doit montrer. Si l'utilisateur n'en a pas fourni, demandez-le (ou l'issue ou le storyboard demo-video dont il provient). N'inventez pas de séquences.
• Cartes attendues — les cartes scénarisées (couverture, ordre du jour, chaque interstice, récapitulatif) dans l'ordre. Écrivez-les dans un petit fichier JSON pour --cards-file : un tableau d'entrées { "label": "Couverture (titre + sous-titre)" } (ajoutez "minRead": <sec> pour remplacer la barre de temps de lecture pour une carte plus verbeuse). Cela alimente la vérification croisée déterministe des cartes — une sortie de première classe, puisque les cartes sont une narration rédigée.
• Marque — couleurs des cartes/fonds et couleurs du curseur/annotations, afin que la sonde puisse classer les cartes de la marque et que le sous-agent puisse vérifier le contraste. Valeurs par défaut si non spécifiées : demandez ; ne devinez pas une marque.

Étape 2 — Exécuter la sonde déterministe

node ${CLAUDE_PLUGIN_ROOT}/skills/video-qa/scripts/probe.mjs \
  --video "<chemin/absolu/vers/video.mp4>" \
  --out   "<workdir>/video-qa-report.json" \
  --frames-dir "<workdir>/video-qa-frames" \
  --card-rgb 15,81,255 \          # la couleur de la carte de marque en R,V,B (p. ex. #0F51FF)
  --cards-file "<workdir>/cards.json"   # les cartes attendues du storyboard, dans l'ordre

Utilisez un <workdir> temporaire (p. ex. sous /tmp), pas le dépôt de l'utilisateur. La sonde écrit le rapport JSON et l'ensemble limité d'images, et affiche le chemin du rapport. Elle exécute trois passes de filtrage sur toute la vidéo (gel, changement de plan, mouvement) plus un échantillonnage par scène — prévoyez ~1–1,5× la durée réelle de la vidéo. Paramètres ajustables (tous optionnels, valeurs par défaut intégrées) : --card-tol, --demo-freeze, --annot-freeze, --card-min-read (barre de temps de lecture, 2,5 s) et --annotate-rgb R,V,B — la couleur de l'annotation. Lorsqu'elle est donnée, une zone de silence contenant un anneau d'annotation "regardez ici" de cette couleur est traitée comme un rythme intentionnel (annotated: true) et exclue du compteur principal de silence plutôt que signalée comme un défaut. Voir references/detectors.md pour ce que chaque détecteur mesure et pourquoi les seuils sont définis là où ils le sont.

La détection d'annotation est limitée aux zones de silence, donc annotatedRegionCount: 0 ne signifie PAS "aucune annotation dans la vidéo". Un anneau n'est enregistré que lorsqu'il coïncide avec une étendue gelée/fixe ; si le montage coupe le silence (ou si l'anneau joue pendant un mouvement), l'anneau s'affiche toujours à l'écran mais aucune zone de silence ne le porte — le compte est 0 par construction. Ne signalez jamais d'annotations manquantes à partir de ce seul nombre ; si une séquence doit montrer un anneau, confirmez-le à partir des images de ce segment (l'image span-* par scène, ou extrayez l'image à l'horodatage de l'annotation).

Vérifiez le résumé imprimé (nombre d'étendues, zones de silence, nombre de défauts, nombre d'images et cardCheck.countMatches) avant de passer la main. Si cardSpans est 0, le --card-rgb est probablement faux — corrigez-le et relancez, sinon chaque carte lira ui et la classification gel/silence/carte est dénuée de sens. Si cardCheck montre une différence de comptage, c'est un résultat réel (une carte manquante ou supplémentaire), pas une erreur de sonde — laissez le sous-agent le confirmer à partir des images.

Étape 3 — Passer la main au sous-agent d'analyse

Créez un sous-agent frais avec l'outil Agent (subagent_type: general-purpose). Construisez son invite à partir de references/analysis-prompt.md, en remplaçant :

• {{REPORT_PATH}} → le chemin --out de l'étape 2.
• {{FRAMES_DIR}} → le chemin --frames-dir.
• {{OUT_FINDINGS}} → un chemin de fichier de résultats que vous lirez (p. ex. <workdir>/video-qa-findings.md).
• {{STORYBOARD}} → les séquences prévues de l'étape 1, textuellement.
• {{BRANDING}} → les règles de marque de l'étape 1.

Dites au sous-agent — comme une instruction explicite dans son invite initiale — d'ÉCRIRE ses résultats dans {{OUT_FINDINGS}} comme dernière étape de son tour. La lecture de ce fichier est le chemin de récupération fiable : le message texte final d'un agent créé n'est pas toujours délivré à l'appelant, et les relances "envoyez-moi vos résultats" atterrissent fréquemment sur un agent inactif qui ne se réengage pas. Le fichier ne contient que la liste d'issues (pas d'images), donc il ne brise pas l'isolation des tokens. Le sous-agent lit toujours le rapport + les images et raisonne séquence par séquence ; il persiste simplement le résultat là où vous pouvez le lire.

Étape 4 — Transmettre

Lisez le fichier de résultats ({{OUT_FINDINGS}}) et transmettez la liste d'issues à l'utilisateur telle quelle (c'est déjà le format livrable). N'ajoutez rien de votre propre raisonnement sur les images — vous ne les avez jamais regardées, par conception. Si l'utilisateur souhaite un artefact HTML avec la marque, cela fera l'objet d'un suivi séparé.

Vérifiez ponctuellement les éléments "n'a pas pu déterminer" avant de les traiter comme des défauts. La sonde échantillonne un ensemble limité d'images (dizaines, pas toutes les images), donc une séquence qui s'est réellement produite peut tomber entre les échantillons et revenir comme "n'a pas pu déterminer" ou un indicateur "semble avoir sauté de page / non affiché" — un écart d'échantillonnage, pas une absence réelle. Ce sont les résultats les moins coûteux à se tromper. Pour chacun de ces éléments, extrayez les quelques images à l'horodatage exact où il devrait se produire (p. ex. ffmpeg -ss <t> -i video.mp4 -frames:v 1 …) et confirmez directement avant de le signaler comme un défaut. Ne signalez que ce que la vidéo complète manque réellement ; rétrogradez les séquences confirmées présentes en ✅ avec une note indiquant qu'elles ont été vérifiées en dehors de l'ensemble échantillonné.

Ce qu'il détecte (et ce qu'il ne peut pas)

• Fiable, mécanique : silence / zones d'UI gelées (balayage de densité de mouvement), structure des scènes/segments, classification carte de marque vs UI, grappes de défauts (rafraîchissement parasite / scintillement de saut de page), statistiques globales de contraste/luminosité.
• Raisonnement du sous-agent sur des images limitées : UI de plomberie hors script (tableaux de bord admin, journaux, traces d'erreur) — y compris les flashs brefs de connexion/chargement/vide/admin entre les séquences et les rechargements en milieu de segment, qui sont traités comme des défauts de polissage, pas des transitions acceptables ; sur-édition / coupures brutales (la coupe de silence a supprimé du mouvement réel — le curseur se téléporte sans déplacement, une transition de page a claqué comme un saut brusque, une coupe en plein milieu d'une action) qui semblent fausses ; séquences manquantes/incorrectes ; style de navigation comme une vérification de première classe (navigation parcourue dans le produit vs saut de page vers une page profonde) ; cartes jugées sur leur impact (durée lisible, non sapées par un voisin contradictoire/vide) plutôt que leur seule présence, avec distinction des cartes de couverture vs ordre du jour par le contenu ; données à l'écran incorrectes (compteurs, lignes cassées) ; annotations manquantes ; pièges de marque/contraste.
• Angles morts : une légende à l'écran manquante pendant une région par ailleurs active (l'animation de chargement est lue comme du mouvement), et si une action a réellement échoué vs a été coupée du cadre. Le sous-agent remonte ces éléments comme "n'a pas pu déterminer".

references/validation-notes.md enregistre comment la compétence a été notée par rapport à la liste dorée examinée par un humain du dispositif de référence.