Triage des exécutions de revue visuelle

Visual Review est le produit de regression de captures d'écran de PostHog : la CI capture des captures d'écran storybook + playwright, les compare à des hashes de baseline commités, et bloque la PR jusqu'à ce qu'un humain approuve les changements visibles. Une PR avec des changements visuels porte un check de statut GitHub visual-review qui reste rouge jusqu'à ce que chaque snapshot diffé soit approuvé ou toléré dans l'interface VR.

Cette skill apprend à un agent comment répondre aux questions qu'un vérificateur humain poserait vraiment, en chaînant les outils MCP VR en lecture seule — au lieu de recourir à gh pr view et de sauter entre onglets vers l'interface web VR.

Quand appliquer cette skill

Déclenchez cette skill sur l'un des cas suivants :

• Un numéro de PR, un nom de branche ou un SHA de commit associé à des mots comme visual review, VR, snapshot, screenshot, storybook diff, playwright snapshot, baseline, approve, tolerated, quarantine.
• Des questions sur la raison pour laquelle une PR est bloquée, ce qui a changé visuellement, ou si un diff est réel.
• « Mon exécution est-elle terminée ? » / « Qu'est-ce qui reste à revérifier ? » / « Cette story a-t-elle déjà échoué ? »
• Un check GitHub visual-review échouant ou un commentaire de PR du posthog-bot mentionnant la revue visuelle.

Quand l'utilisateur demande l'image diff rendue elle-même, l'interface web VR est plus rapide — dirigez-le là-bas. Cette skill concerne tout ce qui entoure le diff : statut, périmètre, historique, triage.

Outils

Tous en lecture seule. Aucun de ces outils ne nécessite de scopes d'écriture ; l'approbation/tolérance se fait toujours dans l'interface web.

Aide-mémoire du vocabulaire

Ces termes apparaissent dans la sortie des outils et importent pour l'interprétation :

• review_state d'exécution : needs_review (ouvert, en attente d'humain), clean (zéro diffs), processing (CI en cours de téléchargement), stale (une exécution plus récente sur la même PR a remplacé celle-ci — consultez superseded_by_id).
• run_type d'exécution : storybook (snapshots de composant) ou playwright (snapshots e2e pleine page).
• result de snapshot : unchanged, changed (vrai diff), new (pas encore de baseline), removed.
• classification_reason de snapshot : tolerated_hash (correspond à un hash toléré connu, aucune action requise), below_threshold (en dessous du plancher de bruit), exact (identique en octets), "" (vrai diff nécessitant une revue).
• review_state de snapshot : pending ou approved.
• summary d'exécution : total / changed / new / removed / unchanged / unresolved / tolerated_matched — unresolved est ce qui bloque vraiment la revue.

Workflows

« Quel est le statut VR de cette PR ? »

Le travail le plus courant. Mappez un numéro de PR à son état d'exécution en deux appels.

1. posthog:visual-review-runs-list { pr_number: <n>, limit: 5 } — triez par created_at desc, prenez la dernière non-stale.
2. Si l'exécution a summary.changed > 0 ou summary.unresolved > 0, creusez : posthog:visual-review-runs-snapshots-list { id: <run_id> } et rapportez les snapshots changed.

Rapportez : numéro de PR, UUID d'exécution, review_state, comptages résumés, et le deep link _posthogUrl pour que l'utilisateur puisse cliquer directement vers le visualiseur de diff.

« Le diff est-il réel ou sans rapport ? »

Le jugement le plus utile qu'un agent conscient du code puisse ajouter. Combinez trois signaux : correspondance de périmètre, historique de flake, et les images rendues réelles. L'agent doit regarder les captures d'écran — pas seulement décrire les métadonnées.

1. Vérification du périmètre — git diff master...HEAD --stat (ou contre la branche de base de la PR) → liste des chemins touchés. Recoupez avec posthog:visual-review-runs-snapshots-list { id } filtré par result: changed → identifiants de story. Les stories sont namespacées comme <area>-<scene>--<story>--<theme> ; par ex. scenes-app-settings-user--settings-user-profile--dark correspond à frontend/src/scenes/settings/user/.... Utilisez ceci pour traduire l'id de story → chemin source probable.

2. Inspection visuelle — pour chaque snapshot changed, le résultat de l'outil contient current_artifact.download_url et baseline_artifact.download_url. Ce sont des URLs S3 pré-signées vers des fichiers PNG ; téléchargez-les et regardez :

   curl -s -o /tmp/vr-baseline.png "<baseline_artifact.download_url>"
   curl -s -o /tmp/vr-current.png "<current_artifact.download_url>"

   Puis Read les deux fichiers (l'outil Read rend les images visuellement) et comparez. Choses à signaler :

   • Le delta visible réel (texte changé, bouton déplacé, changement de layout, dérive de couleur, élément manquant).
   • Si le changement est cohérent avec diff_pixel_count et diff_percentage dans les métadonnées (par ex. 54% de diff mais les images sont quasi identiques → cadrage de capture d'écran changé, pas l'UI).
   • Si la baseline et l'actuel ont des dimensions différentes (champs width / height). Les dimensions mal appairées signifient généralement que la story s'est rendue pour un viewport différent ou ne s'est pas complètement rendue avant capture d'écran — un signal de flake, pas une regression.

3. Historique de flake — exécutez la vérification de flake ci-dessous pour toute story qui semble suspecte.

4. Verdict — combinez les trois :

   • Périmètre plausible + regression visible cohérente avec le changement de code → diff réel, recommandez l'approbation.
   • Périmètre mal appairé + dimensions mal appairées + changements fréquents antérieurs → flake, recommandez de tolérer le hash.
   • Périmètre plausible + regression visible semble non intentionnelle → poussez un fix ; ne pas approuver.

Incluez toujours une description d'une ligne de ce que vous avez vu dans les images — l'utilisateur l'utilise pour décider s'il doit faire confiance à votre verdict sans ouvrir l'interface VR lui-même.

Vérification de flake : « Cette story a-t-elle changé ? »

Une fois que vous avez un identifiant de snapshot suspect :

posthog:visual-review-runs-snapshot-history-list { id: <snapshot_id> } → retourne les résultats antérieurs pour la même story.

Verdicts :

• Surtout unchanged et le diff de cette exécution est l'exception → probablement une vrai regression causée par cette PR.
• changed fréquent à travers des branches/master non liées → story flaky ; recommandez de tolérer le hash via l'interface.
• removed récent ou grand changement de dimension → baseline probablement obsolète ; recommandez de re-baseline sur master.

Triage de la file

Quand l'utilisateur fait du ménage plutôt que de poser des questions sur une PR spécifique :

1. posthog:visual-review-runs-counts-retrieve → taille totale de la file.
2. posthog:visual-review-runs-list { review_state: needs_review, limit: 50 } (paginez si nécessaire).
3. Groupez par auteur de branch ou run_type pour identifier les clusters (par ex., « 12 PRs bloquées sur le même changement de composant partagé » signifie généralement une seule cause racine sous-jacente à traiter).
4. Préférez surfacer les exécutions dont summary.changed > 0 plutôt que les exécutions qui sont seulement new — new signifie pas encore de baseline, ce qui est généralement trivial à approuver ; changed est le vrai travail de revue.

Attentes de sortie

Pour les questions de statut de PR, commencez par le verdict d'une ligne, puis 2-4 puces de contexte de soutien. Incluez toujours le deep link _posthogUrl de l'exécution — les humains ont besoin de voir les images rendues pour prendre la décision, l'agent ne peut que décrire les métadonnées.

Pour les questions de triage / agrégées, un court tableau bat la prose. Groupez par ce sur lequel l'utilisateur va agir.

Ce qu'il NE FAUT PAS faire

• N'approuvez pas ou ne tolérez pas les snapshots depuis cette skill — ces endpoints ne sont intentionnellement pas encore exposés comme outils MCP. Dirigez l'utilisateur vers le _posthogUrl de l'exécution.
• Ne supposez pas que le check GitHub échouant sur une PR est sans rapport avec VR — si un check visual-review est rouge sur une PR sur laquelle vous travaillez, c'est le déclencheur pour exécuter cette skill.
• Ne déclarez pas de verdict à partir de métadonnées seules quand result: changed. Téléchargez les PNGs baseline et actuels et regardez-les ; les métadonnées peuvent seulement dire « quelque chose a changé », pas si le changement est intentionnel.