Audit de la santé de l'entrepôt de données

Cette skill produit un audit au niveau du projet de la pipeline d'entrepôt de données. Utilisez-la quand l'utilisateur veut un résumé de tout ce qui est cassé, pas une analyse approfondie d'une seule synchronisation. L'analyse approfondie des défaillances individuelles est diagnosing-failed-warehouse-syncs ; cette skill est l'analyse qui leur dit où chercher en premier.

Quand utiliser cette skill

• "Qu'est-ce qui est cassé dans mon entrepôt ?" / "Fais-moi un contrôle de santé"
• "Audit ma pipeline de données"
• L'utilisateur est nouveau dans un projet et veut savoir ce qu'il a hérité
• Révision hebdomadaire ou mensuelle de la santé de la pipeline
• Les tableaux de bord sont périmés et l'utilisateur n'est pas sûr de quelle source en est responsable

Outils disponibles

L'endpoint data-health-issues agrège déjà les matérialisations, les schémas de synchronisation, les sources, les destinations d'export batch et les transformations — c'est le chemin le plus rapide vers un résumé. Utilisez les endpoints de liste quand vous avez besoin de plus de contexte que le résumé (comptages de lignes, éléments non défaillants, détails au niveau du schéma).

Ce qui compte comme un "problème"

L'endpoint data-health retourne des éléments de cinq catégories :

Chaque entrée inclut id, name, type, status, error, failed_at, url, et (pour les syncs/sources) source_type.

Notez que l'endpoint data-health rapporte seulement les défaillances actives. Il ne signale pas :

• Les schémas mis en pause par l'utilisateur (should_sync = false)
• Les vues non matérialisées avec erreurs (seules les vues matérialisées sont rapportées)
• Les schémas qui sont lents ou périmés mais techniquement Completed
• Les problèmes de webhook sur les schémas sync_type: "webhook". Le filet de sécurité sync bulk peut réussir alors que le canal de push webhook est silencieusement cassé (désenregistré, désactivé du côté distant, défaut de vérification de signature). Ces problèmes ne remontent pas dans data-health-issues — vérifiez par source avec webhook-info-retrieve.

Si l'utilisateur pose des questions sur la péremption ou les éléments inutilisés, allez au-delà de cet endpoint — voir Étape 4.

Flux de travail

Étape 1 — Extraction unique

Appelez data-warehouse-data-health-issues-retrieve. Cela retourne tous les éléments actuellement en défaillance en une seule requête.

Si la réponse est vide, dites à l'utilisateur que sa pipeline est saine et arrêtez-vous. N'inventez pas de problèmes.

Étape 2 — Grouper et prioriser

Groupez les problèmes par type et triez dans chaque groupe par sévérité :

1. Sources en erreur d'abord. Une défaillance de source cascade — chaque schéma sous elle est effectivement mort jusqu'à ce que la source se reconnecte. Corrigez ceux-ci en premier.
2. Schémas de synchronisation ensuite, dans cet ordre :
   • Les entrées status: "billing_limit" (problème de facturation, non technique — signallez et acheminée vers la facturation)
   • Failed sur les tables très utilisées (l'utilisateur demande / vérifiez les comptages de lignes via schemas-list si nécessaire)
   • Failed sur les tables moins utilisées
3. Vues matérialisées. Généralement indépendantes des sources — une défaillance de vue est un problème HogQL ou de données dans la vue elle-même.
4. Destinations d'export batch. Affectent les données sortant de PostHog — importants mais généralement pas bloquants pour les lectures.
5. Transformations. Affectent l'ingestion. Signalez séparément puisque ce sont des problèmes HogFunction, pas des syncs d'entrepôt.

Étape 3 — Présenter l'audit

Rendez un rapport priorisé. Ne videz pas le JSON brut — tableau lisible par humain par catégorie :

## Santé de l'entrepôt de données — 7 problèmes

### 🔴 Sources (1)
- Stripe — authentification échouée (défaillance il y a 2h)
  → `diagnosing-failed-warehouse-syncs` sur cette source

### 🟠 Schémas de synchronisation (3)
- postgres_prod.orders (Défaillance il y a 6h) — la colonne « updated_at » n'existe pas
- postgres_prod.invoices (Défaillance il y a 6h) — la colonne « updated_at » n'existe pas
- hubspot.contacts (BillingLimitReached) — quota de l'équipe dépassé

### 🟠 Vues matérialisées (2)
- monthly_revenue — vue défaillance (erreur de syntaxe dans HogQL)
- active_users_30d — vue défaillance (référence de table manquante)

### 🟡 Destinations (1)
- Export S3 « daily-events » (FAILED_RETRYABLE 3 exécutions d'affilée)

Ordre recommandé :
1. Auth Stripe (tout ce qui est dessous est mort)
2. Dérive de schéma sur postgres_prod.orders / invoices — l'amont semble avoir renommé une colonne
3. Limite de facturation sur hubspot
4. Vues matérialisées (indépendantes — peuvent être traitées à tout moment)

Le format exact est moins important que : priorisé, groupé, actionnable, et indiquant la bonne skill suivante.

Étape 4 — Aller au-delà des défaillances actives (si demandé)

Si l'utilisateur veut plus que juste "ce qui brûle" — p. ex. "qu'est-ce d'autre je devrais regarder ?" — contre-vérifiez :

Schémas périmés mais « Completed » : Appelez external-data-schemas-list et cherchez les schémas avec last_synced_at ancien relatif à leur sync_frequency. Un schéma en 1hour de fréquence qui a synchronisé pour la dernière fois il y a 3 jours est effectivement cassé même si le statut dit Completed.

Vues matérialisées inutilisées : Appelez view-list. Les vues matérialisées consomment du stockage et du calcul à chaque exécution. Si certaines sont marquées matérialisées mais n'ont pas été interrogées récemment, signalez-les — territoire de cleaning-up-stale-warehouse-views (pas encore implémenté, mais les données sont disponibles).

Sources sans activité de synchronisation : Sources où chaque schéma a should_sync: false ou status = Paused. Celles-ci ont été configurées puis abandonnées — candidates pour le nettoyage via external-data-sources-destroy.

Webhooks cassés sur les schémas de type webhook : Itérez les sources qui ont tout schéma avec sync_type: "webhook" (visible via external-data-schemas-list). Pour chacune, appelez external-data-sources-webhook-info-retrieve({source_id}) :

• exists: false tandis qu'un schéma est sync_type: "webhook" → webhook n'a jamais été enregistré, ou a été supprimé. Le canal de push est mort ; seul le fallback en bulk ingère.
• external_status.error présent → le service distant rapporte un problème (permission révoquée, endpoint supprimé sur leur tableau de bord).
• external_status.status pas "enabled" → le distant a désactivé l'endpoint (souvent après des défaillances de livraison répétées).

Rapportez ceux-ci séparément de l'audit primaire — ils sont une forme différente de problème que les autres catégories, et la correction est une skill différente (diagnosing-failed-warehouse-syncs scénario I, ou setting-up-a-data-warehouse-source étape 5.5).

Ne lancez ces vérifications supplémentaires que si l'utilisateur demande explicitement un audit plus large — elles impliquent plus d'appels d'outils et d'heuristiques.

Étape 5 — Proposer l'étape suivante

Terminez l'audit par un passage clair :

• "Tu veux que j'approfondisse la défaillance Stripe ?" → passage à diagnosing-failed-warehouse-syncs
• "Tu veux que je corrige la dérive de schéma sur orders ?" → passage à tuning-incremental-sync-config
• "Tu veux désactiver les schémas limités par facturation ?" → one-click via external-data-schemas-partial-update

Ne commencez jamais à appliquer des corrections de manière autonome depuis un audit — le rôle de l'audit est de rapporter et recommander, pas de remédier. Toute correction doit être confirmée explicitement avant exécution.

Exemple d'interaction

Utilisateur : « Vérifie la santé de notre entrepôt de données »

Agent :
- data-warehouse-data-health-issues-retrieve → 4 éléments
   [{type: "source", name: "Stripe", error: "401 Unauthorized", ...},
    {type: "external_data_sync", name: "postgres_prod.orders",
     error: "column \"updated_at\" does not exist", ...},
    {type: "materialized_view", name: "monthly_revenue",
     error: "syntax error at or near \"FORM\"", ...},
    {type: "destination", name: "S3 daily-events", error: "AccessDenied", ...}]

- Rapport :
  « Trouvé 4 problèmes dans votre entrepôt de données :

   🔴 Sources (1)
   - Stripe — défaillance d'authentification il y a 2h (401). Les 8 tables sous elle sont actuellement mortes.

   🟠 Schémas de synchronisation (1)
   - postgres_prod.orders — la colonne `updated_at` a été supprimée du côté source,
     la synchronisation incrémentale ne la trouve pas.

   🟠 Vues matérialisées (1)
   - monthly_revenue — erreur de syntaxe HogQL ('FORM' au lieu de 'FROM').

   🟡 Destinations (1)
   - Export S3 'daily-events' — accès refusé à l'écriture.

   Suggère de corriger dans cet ordre :
   1. Identifiants Stripe (débloque tout ce qui est dessous)
   2. Dérive du champ incrémental orders
   3. Typo monthly_revenue
   4. Permissions S3

   Tu veux que je commence par Stripe ? »

Notes importantes

• L'audit est en lecture seule. N'appelez jamais des outils destructifs depuis le flux d'audit. Passez aux skills de diagnostic/tuning — qui à leur tour confirment avant d'agir.
• Vide = sain. Ne remplissez pas un audit vide avec des problèmes hypothétiques. « Aucun problème trouvé » est une bonne réponse.
• Les défaillances de source cascadent. Quand vous rapportez une source en erreur, mentionnez aussi quels schémas sous elle sont affectés (ou le seront, une fois qu'ils essayeront de se synchroniser à nouveau). L'utilisateur doit comprendre le rayon d'impact.
• Les limites de facturation ne sont pas des problèmes techniques. Signalez-les mais orientez vers la discussion facturation / quota, pas vers une action de récupération.
• Les problèmes de transformation sont séparés. Les HogFunctions ne sont pas des syncs d'entrepôt — ils apparaissent dans l'audit parce qu'ils font partie de la pipeline plus large, mais ils vivent du côté ingestion posthog. Acheminez ceux-là vers des skills de pipeline plutôt que d'essayer de corriger ici.
• data-health-issues ne montre que les défaillances actives. Pour la péremption, les vues inutilisées, ou les sources abandonnées, vous devez contre-vérifier les endpoints de liste. Faites cela seulement quand l'utilisateur demande explicitement un audit plus approfondi.
• La santé du webhook est séparée de la santé du schéma. L'endpoint data-health ne connaît pas l'état du webhook. Quand la demande d'un utilisateur mentionne « temps réel », « webhook Stripe », ou « pourquoi les données sont retardées de heures sur une source webhook », allez directement à webhook-info-retrieve plutôt que d'inférer à partir du statut du schéma.