Enquête sur un changement de métrique

Pour les questions du type « pourquoi X a-t-il changé ? » sur un insight sauvegardé, une tuile de dashboard ou une requête collée. Ne charge pas cette compétence pour les questions simples du type « qu'est-ce que X ? » — uniquement quand il y a un changement observé à expliquer.

Outils

Cible PostHog MCP v2. Les outils de requête typés acceptent le corps de la requête directement — passe kind, series, dateRange comme champs de niveau supérieur, ne les enveloppe pas dans InsightVizNode.

Plus les outils PostHog standard que les playbooks référencent par nom (feature-flag-get-all, experiment-get-all, annotations-list, error-tracking-issues-list, query-logs, query-session-recordings-list, cohorts-list/-create, annotation-create, insight-create).

Scripts auxiliaires

• compare_to_prior_periods.py — détecte automatiquement l'intervalle et compare les valeurs récentes au cycle naturel (jour de la semaine, heure de la semaine, ou séquentiel). À utiliser pour résoudre l'étape 2.2 efficacement.
• breakdown_attribution.py — classe les segments de breakdown par delta absolu et signale les mouvements compensatoires.

python3 scripts/compare_to_prior_periods.py < query_result.json
WINDOW=7 python3 scripts/breakdown_attribution.py < breakdown_result.json

Étape 1 — Classifier la métrique

Lis query.kind depuis la source que l'utilisateur a pointée :

• Insight sauvegardé (URL, short_id) : posthog:insight-get → query.kind. Utilise posthog:insight-query si tu as aussi besoin des chiffres.
• Une requête que tu as déjà exécutée ou que l'utilisateur a collée : lis kind directement.
• Rien pointé : demande l'URL ou le short_id. Ne devine pas.

Si kind === "TrendsQuery" et trendsFilter.display === "BoxPlot", utilise box-plot-playbook.md — métrique de distribution, pas de breakdowns.

Pour les insights HogQLQuery, classifie par la forme du SQL : décompte dans le temps → playbook trend, conversion multi-étapes → playbook funnel, retour de cohorte → playbook retention. Exécute le SQL via posthog:execute-sql pour obtenir les données, puis suis les étapes du playbook le plus proche. Vois HogQL insights dans shared-patterns.md.

Si la question de l'utilisateur couvre plusieurs kinds, exécute les playbooks en séquence.

Étape 2 — Mouvements d'ouverture communs

2.1 Confirmer l'anomalie

Exécute l'outil primaire. Enregistre la baseline, la valeur actuelle, le delta (absolu et %), et le début de la fenêtre d'anomalie.

2.2 Vérification de la variance

Élargis à 3–4× l'intervalle de l'utilisateur (ou utilise compareFilter: {"compare": true} sur TrendsQuery / StickinessQuery ; pour les autres kinds exécute deux plages de dates). Passe le résultat élargi à travers compare_to_prior_periods.py — il signale la saisonnalité, les buckets de bord droit partiels, et les vraies anomalies. Si le mouvement est une variance normale, rapporte-le et arrête.

2.3 Changements connus dans la fenêtre

En ordre approximatif de signal :

• posthog:feature-flag-get-all → drapeaux avec updated_at près du début de l'anomalie.
• posthog:experiment-get-all → start_date / end_date près du début.
• posthog:annotations-list → date_marker près du début.
• git log pour la fenêtre si le repo est accessible (signal le plus élevé quand disponible).

Tout appariement est une hypothèse à confirmer dans le playbook (généralement via breakdown sur $feature/<flag_key>, app_version, ou utm_source).

Étape 3 — Exécuter le playbook

Ouvre le playbook pour le kind de l'Étape 1 et suis ses étapes numérotées. Apporte l'enregistrement de 2.1 et tout candidat de 2.3 dans celui-ci.

Étape 4 — Contre-vérification

Choisis un segment que la cause suspectée ne devrait pas avoir affecté et réexécute là-dedans. Stable dans le contrôle = hypothèse forte ; a aussi bougé = élargis l'enquête. Saute quand 2.2 a déjà expliqué le mouvement.

Étape 5 — Rédiger les conclusions

Utilise le format ci-dessous. Offre de sauvegarder des graphiques clés via posthog:insight-create. Si une cause est trouvée et aucune annotation ne la marque, offre posthog:annotation-create. Vois common-causes.md pour la taxonomie des causes.

# Investigation: <métrique>

**Anomalie**: <baseline> → <valeur actuelle> (<delta>) à partir de <date>

## Cause probable

<une phrase>

**Confiance**: faible | moyen | élevé — <raison d'une ligne>

**Preuve**

- <résultat de requête>
- <drapeau / expérience / annotation / commit si applicable>

## Causes possibles (exclues)

- <hypothèse>: <pourquoi>

## Segment affecté

- <propriétés partagées des utilisateurs/événements affectés>

## Lacunes données

- <contrôles ignorés et pourquoi>

## Suivis suggérés

- <action concrète suivante>
- <offre de sauvegarder le graphique / créer une annotation>

Confiance règle générale :

• élevé — plusieurs signaux indépendants corroborent (p. ex. un segment isole le delta et un drapeau/version s'aligne et une erreur ou annotation correspond).
• moyen — un signal corroborant, ou correspondance de motif forte sans contre-vérification.
• faible — le motif correspond à une cause connue mais sans corroboration, ou les données excluent seulement les choses.

Lie les insights et dashboards inline : [Nom](/insights/short_id).

Fichiers de référence

• Playbooks : trend, box-plot, funnel, retention, stickiness, lifecycle, paths
• shared-patterns.md — recettes utilisées dans les playbooks
• common-causes.md — taxonomie des causes avec requêtes de confirmation