Diagnostiquer la santé d'une expérience

Cette compétence répond à : Les résultats de mon expérience PostHog semblent incorrects, biaisés ou vides — que se passe-t-il ? C'est le diagnostic et la vérification de santé d'une expérience : sa configuration, ses expositions, ses résultats et ce qui a changé pendant l'exécution.

Faites correspondre la plainte de l'utilisateur dans le tableau de distribution, puis lisez le fichier de référence correspondant pour le diagnostic.

Chaque diagnostic dans les fichiers de référence est marqué [HIGH], [MEDIUM] ou [LOW] selon la force de sa vérification — [HIGH] est vérifié directement dans le code PostHog, [MEDIUM] est partiellement ou vérifié par l'équipe, [LOW] décrit le comportement du SDK/externe qui n'a pas été vérifié ici. Traitez les éléments [LOW] comme des hypothèses à tester, pas comme des faits à affirmer.

Étape 1 — Résoudre l'expérience

Si l'utilisateur fait référence à une expérience par nom ou description, chargez d'abord la compétence finding-experiments pour la résoudre en un ID concret.

Appelez experiment-get et extrayez ces champs. Ce sont des entrées pour presque tous les diagnostics :

• status (draft / running / paused / exposure_frozen / stopped), start_date, end_date, is_legacy
• feature_flag.active et feature_flag.filters.multivariate.variants[] — les clés de variante et la répartition (rollout_percentage). C'est le drapeau tel qu'il est maintenant. Après une mise en ligne ou une édition, la répartition de l'exécution se trouve dans l'historique des modifications (Étape 1.5).
• feature_flag.filters.aggregation_group_type_index — quand défini, l'unité de l'expérience est un groupe, pas une personne
• feature_flag.filters.groups[] — pour chaque groupe, lisez variant, properties et rollout_percentage (le déploiement de ce groupe, % des unités de bucketing mises en correspondance — personnes ou groupes quand le drapeau ou le groupe est agrégé par un type de groupe — qui entrent dans l'expérience ; chaque groupe a le sien, donc il n'y a pas de déploiement global unique à moins que le drapeau n'ait un groupe inconditionnel). Un variant non-null qui est l'une des clés de variante du drapeau est une substitution de variante forcée sur la cohorte mise en correspondance (assignation de condition de sortie, non aléatoire) — surfaces A7. Attention à la forme grave (A7b) : un groupe à variante épinglée avec des properties larges/vides à déploiement élevé, ou aucun groupe resté aléatoire (variant: null) / aucun chemin de sortie vers un bras — qui prive l'autre variante (un bras obtient ~0 expositions analysables). Voir references/bias-and-skew.md.
• feature_flag.bucketing_identifier et feature_flag.ensure_experience_continuity — ce que le drapeau hash (A3, A6, A8, A10)
• holdout et excluded_variants — personnes et bras qui sont hors de l'analyse volontairement
• exposure_criteria.multiple_variant_handling — par défaut "exclude" s'il est absent
• exposure_criteria.exposure_config — l'événement d'exposition et ses filtres de propriété. Non défini ou nommant $feature_flag_called, signifie l'événement d'exposition par défaut : lisez lequel dans resolved_exposure_event. Une config qui nomme $experiment_exposure compte cet événement, quoi que resolved_exposure_event dise. Tout autre événement, ou une action, est un événement d'exposition personnalisé. Les filtres de propriété dans la config s'appliquent à l'un ou l'autre (B12). Le tableau dans references/diagnostic-snapshot.md indique quelle propriété porte la variante.
• exposure_criteria.activation_config — un événement d'activation, ou une action, en plus de l'exposition par défaut. Quand il est défini, une personne compte comme exposée uniquement à partir de son premier événement d'activation à ou après sa première exposition au drapeau, et l'heure de cet événement est l'heure d'exposition. Il ne se combine pas avec un événement d'exposition personnalisé.
• exposure_criteria.filterTestAccounts — par défaut true
• metrics et metrics_secondary, avec métriques partagées — pour chacune : le nom, le type et la définition. Décrivez une métrique à partir de sa définition, pas à partir de son nom (D13).
• stats_config — method (Bayésien ou Fréquentiste), le niveau de confiance (bayesian.ci_level, frequentist.alpha), frequentist.sequential_testing_enabled, cuped, baseline_variant_key. Une method manquante se lit comme Bayésienne et un niveau de confiance manquant comme 95 %. Les tests séquentiels et CUPED reviennent par défaut au projet (C13).
• running_time_calculation — l'échantillon cible (un total sur tous les variants), les jours manquants pour l'atteindre et l'effet détectable minimum. Quand l'estimation provient de nombres que l'utilisateur a tapés, ou a été écrite à la création et jamais actualisée par la page, les jours sont la longueur estimée entière (C12). Une expérience dupliquée commence par les valeurs de sa source jusqu'à ce que la page les actualise.
• only_count_matured_users — E11

Étape 1.5 — Extraire un snapshot de diagnostic (vérifier avant de demander)

Avant de poser des questions de clarification à l'utilisateur, extrayez le snapshot de diagnostic dans references/diagnostic-snapshot.md. La plupart des diagnostics dans cette compétence peuvent être confirmés ou exclus à partir de ces données sans entretien.

Lisez d'abord les sources bon marché, dans chaque diagnostic : les résultats stockés, puis l'historique des modifications. Quand l'utilisateur rapporte un changement surprenant, lisez l'historique des modifications avant les résultats stockés. Puis les données d'exposition, quand le diagnostic a besoin de ce que seules elles contiennent. Interrogez les événements bruts uniquement pour ce que ceux-ci ne peuvent pas montrer.

Étape 2 — Faire correspondre le symptôme au diagnostic

Si le symptôme est flou, posez une question de clarification avant de choisir. La plupart des diagnostics ont des corrections différentes — ne devinez pas. Une plainte qui correspond à des lignes de plusieurs groupes en lit chacun (Étape 3).

Un rapport d'un scout ou d'une autre vérification automatisée nomme sa découverte : acheminez par la découverte et réutilisez les chiffres du rapport avant de les extraire à nouveau.

Étape 3 — Mettre en évidence chaque diagnostic que les preuves soutiennent

Après avoir correspondu le symptôme à l'Étape 2 et lu le(s) fichier(s) de référence pertinent(s), énumérez chaque diagnostic qui s'applique avant de recommander une action.

Mettez en évidence les mécanismes co-occurrents indépendamment — même quand l'un est plus saillant, ne les effondrez pas en une seule recommandation « attendre » ou « corriger ». Les mécanismes différents ont des corrections différentes : un biais systématique (ex. répartition inégale + Exclure) ne se résout pas en attendant ; une structure statistique (ex. variance petit-échantillon) le fait. Les regrouper laisse le biais en place après que l'utilisateur suive le conseil regroupé.

Énumérez uniquement les mécanismes qui ont un chemin de vérification dans l'état du projet — config (de experiment-get), données snapshot, journal d'activité ou source repo (quand l'agent a le repository). Les mécanismes dérivés de config comptent : une répartition 80/20 avec multiple_variant_handling="exclude" par défaut est visible dans experiment-get et est donc énumérable. Nommer un mécanisme sans source (ex. SRM quand le snapshot montre un ratio de variante propre) ne l'est pas.

Deux vérifications appartiennent à chaque diagnostic, quelle que soit la plainte :

• À quel point l'expérience est-elle jeune ? Déclarez son âge (start_date) et sa part de l'échantillon cible (l'exposition totale par rapport à running_time_calculation.recommended_sample_size) avant de lire un résultat (C1 dans references/interpretation.md). La page prend l'exposition totale de la première métrique primaire : la somme de son number_of_samples sur tous les variants dans les résultats stockés, pas exposures.total_exposures. recommended_sample_size est la cible que la page a sauvegardée quand elle a dernièrement calculé l'estimation. Quand il est absent, aucune cible n'a été sauvegardée : dites-le.
• Qui est exposé ? Comparez la population exposée (exposure_criteria et les conditions de sortie du drapeau) avec les personnes sur lesquelles porte la décision avant d'appeler la configuration saine (D12 dans references/numbers-vs-sql.md). Les paramètres d'exposition par défaut ne sont pas une preuve que les bonnes personnes sont dans l'expérience. Quand rien ne dit qui la décision concerne, demandez.

Groupes de diagnostic

A — Biais et asymétrie

Les variantes ne sont pas équilibrées, une variante semble biaisée, la bannière d'avertissement in-app a apparu, ou des utilisateurs se présentent sous plusieurs variantes. Couvre l'interaction répartition inégale + Exclure, l'asymétrie du ratio d'échantillon et ses causes, les événements d'exposition perdus ou envoyés inégalement entre les bras, les drapeaux qui ne retournent aucune variante pour une partie de l'audience, la fragmentation identitaire, bootstrap × mismatch /flags, les éditions de drapeau en cours d'exécution, les variantes forcées et l'incohérence d'état drapeau/expérience.

→ Voir references/bias-and-skew.md

B — Expérience vide / 0 exposition / « pas assez de données »

Un point douloureux fréquent. Couvre l'appel SDK (mauvaise méthode d'évaluation, délai identify(), dédup), la capture d'exposition (événement personnalisé manquant la propriété variante, propriétés requises, bloqueurs de pub) et l'appariement de critères d'exposition (filtre de compte de test, filtres qui ne peuvent pas correspondre, ordre d'éligibilité, événements se déclenchant avant exposition).

→ Voir references/empty-experiment.md

C — Signification / pièges d'interprétation

Basculement de signification, test A/A montrant une signification, confusion Bayésien vs Fréquentiste, comparaisons multiples, variance bas-volume, peeking / arrêt anticipé. Inclut l'estimation du temps d'exécution (« cible atteinte » n'est pas un résultat) et les paramètres statistiques qui changent la lecture d'un résultat : tests séquentiels, CUPED, le niveau de confiance et la variante de base.

→ Voir references/interpretation.md

D — Les chiffres ne correspondent pas (PostHog vs le décompte SQL/brut de l'utilisateur)

La page d'expérience applique une portée d'exposition, une exclusion $multiple, un filtre de compte de test et une plage de dates que le SQL ad-hoc reproduit presque jamais. Couvre l'attribution d'entonnoir (seul le premier→dernier étape compte pour les stats), les répartitions (lues de l'événement d'exposition, pas de l'événement de métrique), la confusion « somme de revenus » vs moyenne par utilisateur, les résultats stockés périmés, l'onglet Enregistrements par rapport aux stats, un insight qui compte une population plus restreinte que l'expérience et une métrique dont le titre ne correspond pas à sa définition.

→ Voir references/numbers-vs-sql.md

E — Surprises après les changements en cours d'exécution (y compris les bizarreries du cycle de vie et de rétention)

L'augmentation du déploiement est sûre ; la diminution, c'est la prudence ; changer la répartition de variante est une anti-pattern ; ajouter des métriques en cours d'exécution est du p-hacking ; la variante de mise en ligne réécrit le drapeau et l'arrêt seul ne le fait pas ; reset efface les résultats pas le drapeau (à part supprimer une congélation d'exposition) ; une pause, une congélation et un dégel peuvent chacun biaiser le résultat ; une date de début changée déplace l'analyse entière. Couvre aussi les bizarreries des métriques de rétention, le filtrage « utilisateurs mûrs » et la divergence métrique long-terme vs court-terme.

→ Voir references/mid-run-changes.md

F — Commentaires qualitatifs : comment le changement a atterri, pas jusqu'où le chiffre s'est déplacé

Les groupes A–E trouvent des mécanismes. F est pour la question qu'ils ne peuvent pas atteindre : ce que les personnes dans l'expérience ont fait du changement. Une courte enquête, affichée quand les utilisateurs terminent le flux expérimenté, ajoute cette moitié qualitative — une évaluation et un commentaire optionnel, lisible par variante — et fonctionne sur MCP aujourd'hui.

C'est approprié pour certaines expériences et pas pour d'autres. La porte est de savoir si un utilisateur pouvait décrire le changement sans voir les deux versions : un flux, une mise en page ou un processus remodelé fonctionne ; un seuil ou un réglage de classement ne le font pas, peu importe l'ampleur de son effet mesuré. N'offrez pas tandis qu'un diagnostic mécanique est toujours ouvert — une enquête sur un drapeau cassé collecte les opinions d'une fonctionnalité que la moitié de l'audience n'a jamais reçue — et vérifiez si une enquête existante ou récente couvre déjà la fenêtre avant de proposer une nouvelle.

Deux choses à bien faire avant d'en créer une : une enquête affichée à une seule variante est elle-même une différence entre les variantes, et une enquête en cours liée au drapeau peut générer des événements d'exposition.

→ Voir references/qualitative-feedback.md

Étape 4 — Calibrer les recommandations à l'état de l'expérience

Mettez en évidence les diagnostics d'abord (Étape 3). Puis recommandez — mais limitez ce que vous recommandez à ce que l'état actuel de l'expérience permet.

• Brouillon — les changements de config sont gratuits ; recommandez et appliquez. Le drapeau d'un brouillon peut toujours servir les utilisateurs : un brouillon créé par un reset, ou créé sur un drapeau existant, peut avoir feature_flag.active true, et une édition de ce drapeau atteint ces utilisateurs à l'instant.
• En cours d'exécution (et paused ou exposure_frozen, qui sont lancés et non terminés) — chaque changement a un compromis. Expliquez l'impact en cours d'exécution (anti-pattern ? sûr ? visible par l'utilisateur ?) avant de recommander. Voir configuring-experiment-rollout et son fichier de référence references/changing-distribution-after-launch.md pour les règles en cours d'exécution. Une pause, une congélation, un dégel et un reset sont aussi des changements : chacun interrompt l'exécution et peut biaiser le résultat (E8, E9 et E16 dans references/mid-run-changes.md).
• Arrêté / archivé — l'expérience ET son drapeau de fonctionnalité représentent le résultat documenté de l'exécution. Les recommandations se limitent à (a) l'interprétation des données existantes, (b) quoi faire pour l'expérience suivante, ou (c) l'explication de ce qui s'est passé.

Un diagnostic se termine par les découvertes et une recommandation. Un changement à une expérience en cours d'exécution ou à son drapeau (une nouvelle métrique, de nouveaux critères d'exposition, un reset, un relancement, une édition de drapeau) est la décision de l'utilisateur : dites ce que le changement fait aux données collectées jusqu'à présent et ne l'effectuez que sur une instruction explicite.

Sur une expérience arrêtée ou archivée, n'offrez pas de manière préemptive de réversion d'une mutation d'état (récriture du drapeau de variante de mise en ligne, édition manuelle du drapeau, reset, archive). Si l'utilisateur demande « pourquoi X s'est-il produit ? », expliquez X — n'ajoutez pas de coda « voici comment l'annuler ». Ce modèle suppose une intention que l'utilisateur n'a pas signalée. Les offres conditionnelles comme « si ce n'était pas volontaire, vous pouviez… » ou « voulez-vous l'annuler ? » comptent aussi comme préemptives — seul l'utilisateur nommant explicitement l'action d'inversion (« comment j'annule cela ? », « puis-je annuler la variante de mise en ligne ? », « comment je récupère la répartition 50/50 ? ») est une demande de surface des mécaniques d'inversion.

Utilisez une terminologie cohérente : la répartition de variante (entre variantes) est distincte du déploiement (la part de l'audience de condition de sortie qui entre) ; l'événement d'exposition par défaut (resolved_exposure_event) est distinct d'un événement d'exposition personnalisé ; les options Exclure de l'analyse / Utiliser la première variante vue du Traitement de plusieurs variantes (exposure_criteria.multiple_variant_handling) décident comment les personnes exposées à plusieurs variantes sont comptées, pas quel événement est l'exposition.

Compétences associées

• configuring-experiment-analytics — corriger la configuration d'exposition ou de métrique que le diagnostic pointe
• configuring-experiment-rollout — anti-patterns de changement de répartition et ajustements de déploiement sûrs
• managing-experiment-lifecycle — reset, arrêt ou redémarrage quand l'expérience ne peut pas être sauvegardée sur place
• analyzing-experiment-session-replays — quand les chiffres sont corrects mais que vous avez besoin de voir le comportement derrière
• debugging-experiments — quand la question arrive comme une demande de support sur l'expérience de quelqu'un d'autre et la réponse est une réponse écrite