Backend

Détection — Au début de chaque invocation, avant d'accomplir une action, déterminez quel backend utiliser :

1. Si l'utilisateur a passé --backend pup n'importe où dans son invocation → utilisez le mode pup immédiatement, peu importe la présence des outils MCP. Ignorez les étapes 2–4.
2. Vérifiez si les outils MCP sont présents dans votre liste d'outils active. Le signal canonique est la présence de mcp__datadog-llmo-mcp__get_llmobs_experiment_summary dans vos outils disponibles.
3. Si les outils MCP sont présents → utilisez le mode MCP partout. Appelez les outils MCP exactement comme nommés dans les sections de workflow de cette skill.
4. Si les outils MCP sont absents → vérifiez si pup est exécutable : lancez pup --version via Bash. Une réponse JSON contenant "version" confirme que pup est disponible.
5. Si pup répond → utilisez le mode pup partout. Traduisez chaque appel d'outil MCP en son équivalent pup en utilisant l'appendice Référence des outils au bas de ce fichier.
6. Si aucun n'est disponible → arrêtez-vous et dites à l'utilisateur :

   « Neither the Datadog MCP server nor the pup CLI is available. Connect the MCP server (claude mcp add --scope user --transport http datadog-llmo-mcp 'https://mcp.datadoghq.com/api/unstable/mcp-server/mcp?toolsets=llmobs') or install pup. »

--backend pup est accepté n'importe où dans les arguments d'invocation et est supprimé avant de passer les arguments restants à la logique de la skill.

Règles d'invocation pup :

• Invoquez via Bash : pup llm-obs <subcommand> [flags]
• pup produit toujours du JSON. Analysez directement — aucun unwrapping de bloc de contenu (contrairement aux résultats MCP, qui peuvent envelopper du JSON dans [{"type": "text", "text": "<json>"}]).
• Si pup retourne une erreur d'authentification, dites à l'utilisateur de lancer pup auth login et arrêtez-vous.
• Parallélisation : émettez plusieurs appels d'outil Bash dans un seul message (une commande pup par appel).

Marquage d'intention : À chaque appel d'outil MCP, préfixez telemetry.intent avec skill:llm-obs-experiment-analyzer — suivi d'une description de la raison pour laquelle l'outil est appelé.

Analyseur d'expériences unifié

Analyse une ou deux expériences LLM. Supporte quatre modes selon les entrées :

Usage

/llm-obs-experiment-analyzer <experiment_id_1> [experiment_id_2] [question text] [--output agent|file|notebook]

Arguments : $ARGUMENTS

Outils disponibles

Phase 0 — Résolution du mode et de la sortie

Analysez $ARGUMENTS :

1. Extrayez une ou deux chaînes au format UUID comme IDs d'expérience (première = baseline/primaire, deuxième = candidate).
2. Extrayez l'indicateur --output agent|file|notebook s'il est présent.
3. Le texte restant (après les IDs et les indicateurs) est la question, le cas échéant.

Détermination du mode :

• 2 IDs + question → Comparative Q&A
• 2 IDs, pas de question → Comparative Exploratory
• 1 ID + question → Single Q&A
• 1 ID, pas de question → Single Exploratory

Détermination du mode de sortie :

Si --output a été fourni dans les arguments, utilisez ce mode et ignorez les questions.

Sinon, posez deux appels AskUserQuestion séquentiels séparés avant de continuer — jamais combinés en un seul appel :

1. Type d'analyse : Si aucun texte de question n'a été fourni dans les arguments, demandez si l'utilisateur veut une analyse exploratoire ou a une question spécifique. Ignorez cet appel uniquement si l'intention de l'utilisateur est déjà claire d'après le contexte (par exemple, il a tapé une question aux côtés des IDs).
2. Destination de sortie : Si --output n'a pas été spécifié, demandez où livrer le rapport (chat, fichier ou notebook Datadog). Posez toujours cette question comme un appel autonome distinct.

Modes de sortie :

1. Agent (par défaut) : Affichez le rapport complet dans la conversation.
2. Fichier : Avant de commencer, proposez un chemin : evals/reports/YYYY-MM-DD-<experiment-slug>-analysis.md Présentez-le à l'utilisateur et laissez-le confirmer ou ajuster. Puis continuez.
3. Notebook : Utilisez mcp__datadog-mcp-core__create_datadog_notebook à la fin. En mode pup, utilisez pup notebooks create --title "TITLE" --file /tmp/nb_cells.json à la place (voir Référence des outils). Si ni MCP ni pup n'est disponible, produisez ces instructions de configuration au lieu d'échouer :

   To enable Datadog notebook export, add the MCP server:
     claude mcp add --transport http datadog-mcp https://mcp.datadoghq.com/api/unstable/mcp-server
   See: https://docs.datadoghq.com/bits_ai/mcp_server/setup/

   Puis demandez : « Would you like to fall back to file or agent output instead? » Voir Phase 5 pour les détails complets de l'appel notebook.

Après résolution du mode et de la sortie, passez à la Phase 1. Il y aura une interaction AskUserQuestion supplémentaire à la Phase 1.5 avant le début de l'analyse approfondie.

Phase 1 — Orientation

Comparative : Appelez get_llmobs_experiment_summary pour les deux expériences. Produisez une comparaison côte à côte :

• Échelle : nombre total d'échantillons et nombre d'erreurs pour chacun
• Métriques : quelles métriques existent dans chacun ; lesquelles sont partagées
• Dimensions : quelles dimensions existent dans chacun ; lesquelles sont partagées
• Drapeaux d'alerte immédiats (erreurs présentes, métriques manquantes, données clairsemées)
• Améliorations ou régressions évidentes visibles au niveau du résumé

Quand error_count > 0, appelez get_llmobs_experiment_dimension_values pour error_type et rapportez la répartition par classe d'exception (par exemple « 2 erreurs : asyncio.exceptions.cancellederror »). Les erreurs signifient que l'exécuteur a levé une exception non gérée — aucun score d'évaluation n'a été produit pour ces échantillons. Ne rapportez pas de pourcentage ; rapportez le nombre et le(s) type(s).

Single : Appelez get_llmobs_experiment_summary pour l'expérience. Déterminez :

• Nombre total d'échantillons et nombre d'erreurs (avec répartition par error_type si non-zéro)
• Métriques disponibles regroupées par metric_type tel que retourné par le résumé (score, boolean, categorical). N'inférez pas de groupes sémantiques ou de catégories à partir de patterns ou de préfixes de noms de label — la chaîne de label n'est pas un signal fiable pour ce qu'une métrique mesure.
• Classifiez chaque métrique en utilisant les statistiques déjà retournées par le résumé (mean, min, max). N'inférez pas la signification de la métrique à partir des noms ou préfixes de label. Utilisez les classifications définies dans la Phase 1.5 quand vous référencez les métriques dans tout le rapport.
• Dimensions disponibles pour la segmentation
• Drapeaux d'alerte immédiats

Phase 1.5 — Sélection des métriques

Après avoir complété la Phase 1, exécutez les trois étapes suivantes avant tout AskUserQuestion.

Étape 1 — Classifiez chaque métrique en utilisant uniquement les statistiques de résumé (aucun appel d'outil supplémentaire) :

Étape 2 — Imprimez le tableau complet des métriques en chat avant de poser une question. Cela donne à l'utilisateur une visibilité complète — jamais tronquée par des limites d'options. Format :

Found N metrics. Full breakdown:

| Metric | Mean | Class |
|--------|------|-------|
| <label> | <mean> | ⚠️ Struggling |
| <label> | <mean> | Interesting |
| <label> | <mean> | Saturated |
| <label> | 1.000 | Perfect (no signal) |
| <label> | 0.000 | Always zero (disabled?) |

Signalez tout métrique always_zero avec une note — par exemple « N métriques marquent toujours 0 et semblent être des fonctionnalités désactivées ; elles seront exclues des groupements suggérés. »

Étape 3 — AskUserQuestion avec options construites entièrement à partir des classes calculées :

Générez les options dynamiquement selon ce qui est réellement présent dans les données. Ne pas inventer les noms d'options à partir de préfixes de label.

• « Struggling metrics (N) — Recommended » : affiché uniquement si N ≥ 1. Description énumère explicitement chaque label de métrique et sa moyenne (par exemple « open_answer 0.33, c_permanence 0.68 »). C'est la suggestion fondée — basée sur les taux de réussite observés, non les noms de label. S'il n'y a pas de struggling metrics, remplacez cette option par « Lowest-performing metrics (N) » couvrant les N derniers par moyenne.
• « Interesting + struggling (N) » : affiché uniquement s'il y a des métriques de classe interesting en plus des struggling. Description les énumère avec les moyennes.
• « All metrics (N) » : toujours affiché. Notez dans la description que les métriques always-zero et perfect ajoutent du bruit mais sont incluses.
• « A specific metric » : toujours affiché. Description : « Choose one from the table printed above. »

Si l'utilisateur sélectionne « A specific metric », posez un deuxième AskUserQuestion qui affiche les 4 métriques avec la plus basse moyenne en tant qu'options nommées (label = nom de métrique, description = mean: X.XX — class). Dans le texte de la question, dites explicitement : « Or type any metric name from the table above into 'Other'. » Les métriques always_zero et perfect ne doivent pas apparaître dans les 4 options (elles n'ont aucune valeur diagnostique) ; limitez les 4 aux classes struggling et interesting uniquement. Après la sélection de l'utilisateur, limitez toutes les analyses dans les Phases 2–4 à cette seule métrique.

Respect de la portée :

• Si l'utilisateur accepte « all », continuez avec toutes les métriques (y compris les constantes, mais notez leur faible valeur de signal).
• Si l'utilisateur sélectionne un groupement ou une métrique spécifique, limitez strictement toutes les analyses dans les Phases 2–4 à cette sélection. N'appelez pas get_llmobs_experiment_metric_values pour une métrique en dehors de la sélection.

Phase 2 — Découverte de signaux + Liens UI

Comparative : En utilisant uniquement les métriques sélectionnées dans la Phase 1.5 (intersectées avec les métriques partagées) et les dimensions partagées, identifiez :

• Segments où la candidate surperforme la baseline
• Segments où la candidate régresse
• Types d'erreurs présents dans l'une mais rares dans l'autre
• Changements de distribution ou lacunes de couverture
• Tradeoffs (par exemple, rappel plus élevé, précision plus basse)

Générez les liens UI de comparaison Datadog :

• URL de base : https://app.datadoghq.com/llm/experiment-comparison
• Paramètres requis : baselineExperimentId, experimentIds (candidate%2Cbaseline), tableView=all
• Optionnel (inclure si découvrable) : project, compareDatasetId, selectedEvaluation
• Priorité selectedEvaluation : métrique overall/overall_score/rubric → métrique primaire → première métrique partagée
• Générez 2–4 liens : comparaison primaire, vue de régression, vue d'étalonnage (le cas échéant), vue du pire segment (uniquement si supporté — ne pas inventer de filtres)

Single : Mesurez la performance par métrique dans toutes les dimensions pour uniquement les métriques sélectionnées dans la Phase 1.5. Identifiez :

• Segments les plus faibles (par métrique × dimension)
• Segments avec des taux de réussite surprenants
• Taux de réussite globaux et variance

Générez le lien UI d'expérience Datadog :

• https://app.datadoghq.com/llm/experiments/{experiment_id}

Phase 3 — Analyses approfondies

Exécutez automatiquement toutes les analyses approfondies nécessaires. Ne demandez pas d'approbation ou de pause. Limitez toutes les analyses approfondies strictement aux métriques sélectionnées dans la Phase 1.5 — n'appelez pas get_llmobs_experiment_metric_values pour une métrique en dehors de la sélection.

Modes Q&A : Concentrez les analyses approfondies sur ce qui est nécessaire pour répondre directement à la question. Tirez les échantillons spécifiques, segmentez par les dimensions pertinentes, inspectez les exemples.

Modes Exploratory : Enquêtez sur les signaux les plus intéressants au sens large :

• Analyse delta par segment et par classe (comparative) ou analyse des taux de réussite (single)
• Analyse du chevauchement d'erreurs vs. modes d'échec uniques
• Échantillonnage et inspection qualitative des échecs représentatifs (2–5 par problème)
• Analyse des thèmes d'erreurs clusterisés

Règles :

• Préférez d'abord les analyses bon marché et à haut signal ; ne vous arrêtez pas tôt.
• Masquez ou supprimez les PII dans toutes les sorties.
• Évitez les actions destructives.

Pour chaque événement échantillonné, générez un lien span direct : https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&sp=[{"p":{"experimentId":"{experiment_id}","spanId":"{span_id}"},"i":"experiment-details"}]&spanId={span_id}

Pour chaque segment Deep Dive, générez un lien direct pour afficher ces échantillons dans l'expérience (candidate) : https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&filter[{dimension}]={value} Si vous n'êtes pas confiant que le format d'URL de filtrage fonctionne pour cette dimension, omettez les params de filtre et liez à la racine de l'expérience à la place. Ne pas inventer les URLs de filtre.

Phase 4 — Synthèse

Comparative Exploratory :

• Victoires claires où la candidate améliore la baseline
• Régressions claires ou risques introduits par la candidate
• Zones neutres ou inchangées
• Hypothèses de cause profonde (1–4), liées à la preuve
• Recommandations priorisées : mettre en place tel quel / bloquer / gated par segment / combiner les comportements

Comparative Q&A :

• Réponse directe à la question avec un verdict clair
• Preuve à l'appui (métriques, pourcentages, exemples d'événements)
• Contexte pertinent (par exemple, mises en garde, limitations des données)

Single Exploratory :

• Évaluation globale de la performance
• Segments les plus faibles et causes profonde
• Hypothèses pour expliquer pourquoi les échecs se produisent
• Expériences suivantes recommandées

Single Q&A :

• Réponse directe à la question avec un verdict clair
• Preuve provenant des données de l'expérience

Tous les modes : commencez par un relevé de type de problème d'une ligne — par exemple « 3 agent issues, 1 evaluator/dataset issue, 1 ambiguous » — avant les conclusions détaillées. Utilisez des deltas/taux quantifiés partout où possible. Supprimez les PII.

Produisez toujours les sections ## Summary & Recommendations et ## Synthesis indépendamment de la complexité de l'expérience, du nombre de métriques qui existent, ou de la rapidité avec laquelle la réponse est évidente. Ne sautez pas le Summary parce que les conclusions sont simples ou évidentes. Ne sautez pas la Synthesis parce que vous l'avez déjà couverte dans les Deep Dives. Ces deux sections sont la sortie la plus portable de l'analyse — c'est ce qu'un lecteur rencontre en premier et en dernier.

Phase 5 — Livraison de la sortie

Agent : Présentez le rapport complet dans la conversation en utilisant le format de rapport ci-dessous.

Fichier : Écrivez le rapport dans le chemin pré-confirmé. Confirmez par : « Report saved to <path>. »

Notebook : Appelez mcp__datadog-mcp-core__create_datadog_notebook avec les paramètres suivants :

• name (par mode) : | Mode | Nom | |------|------| | Comparative Exploratory | Experiment Analysis: {baseline_short} (Baseline) vs {candidate_short} (Candidate) — YYYY-MM-DD | | Comparative Q&A | Experiment Q&A: {baseline_short} vs {candidate_short} — YYYY-MM-DD | | Single Exploratory | Experiment Analysis: {experiment_short} — YYYY-MM-DD | | Single Q&A | Experiment Q&A: {experiment_short} — YYYY-MM-DD | où short = 8 premiers caractères de l'UUID.

• cells : une cellule par section de rapport — NE METTEZ PAS le rapport entier dans une seule cellule. Structure :

  • Cellule 1 — Summary & Recommendations contenant trois sous-en-têtes ### : Experiment (lien + résumé exécutif), Key Findings (puces), Recommendations (liste numérotée) — toujours présente, toujours première, jamais sautée indépendamment de la complexité de l'expérience
  • Cellule 2 — Tableau d'orientation
  • Cellule 3 — What Changed (modes comparatifs uniquement ; omettez pour single)
  • Cellule 4 — Signals / Answer to Question
  • Cellules 5…N — une cellule par Deep Dive Finding
  • Cellule N+1 — Synthesis (relevé de problèmes, Overall Performance Assessment, Worst-Performing Segments, Root Cause Hypothesis, Recommended Next Experiments) — toujours présente, toujours avant-dernière
  • Cellule N+2 — UI Links

  Omettez le en-tête de niveau supérieur # Experiment Analysis Report de toutes les cellules — il est déjà affiché comme titre du notebook.

• time : { "live_span": "1h" }

Après la création du notebook, affichez l'URL en chat : "Report exported to notebook: <url>"

Si l'outil n'est pas disponible, suivez les instructions de secours dans la Phase 0.

Phase 6 — Suivi conversationnel

Après la livraison du rapport, ajoutez une section de suivi :

---
## Want to explore further?

Here are a few directions based on the findings:

1. [Specific question derived from actual findings — e.g., "Want me to dig deeper into why the SQL scenarios regressed in the candidate?"]
2. [Another specific follow-up — e.g., "Should I compare error patterns between the two failing clusters?"]
3. [A third option if relevant]

Do you have any other questions about this analysis?

Restez actif après le rapport. Répondez aux questions de suivi en utilisant les mêmes outils MCP, en référençant les conclusions déjà rassemblées. Ne relancez pas les analyses que vous avez déjà effectuées sauf si de nouvelles questions l'exigent.

Format du rapport

Règles de lien :

• IDs d'expérience : Partout où un UUID d'expérience complet apparaît, rendez-le comme lien Markdown vers https://app.datadoghq.com/llm/experiments/{full_uuid}.
• En-têtes de colonne du tableau comparatif : Dans le tableau d'orientation et dans tous les tableaux ultérieurs qui ont des colonnes Baseline/Candidate, enveloppez l'en-tête de colonne entier comme lien — non seulement l'ID court. Format : [Baseline \{short_id}`]({baseline_url})etCandidate `{short_id}``. Cela rend la cellule d'en-tête entière cliquable, non seulement l'ID.

# Experiment Analysis Report

> **Question:** {original question text}
> _(Q&A modes only — omit for Exploratory modes)_

## Summary & Recommendations

### Experiment

[Comparative: [`{baseline_short}`]({baseline_url}) (Baseline) vs [`{candidate_short}`]({candidate_url}) (Candidate) — [Compare]({compare_url}) — Single: [`{experiment_short}`]({experiment_url})]

[Résumé exécutif de 2–3 phrases. Commencez par « This is a **{Mode}** analysis... » où {Mode} est l'un de : Comparative Exploratory, Comparative Q&A, Single Exploratory, Single Q&A. Incluez le (les) objectif(s) d'expérience, l'échelle et le principal résultat avec des chiffres spécifiques.]

[Si le rapport utilise des valeurs de dimension opaques (par exemple, des labels de catégorie comme b1/b2/b3/bx), ajoutez une sous-sous-section `#### Dataset Categories` ici — une puce par valeur avec le nom en gras et une brève description. Omettez si toutes les valeurs de dimension sont auto-explicatives.]

### Key Findings

- **{Finding 1}** : description d'une ligne avec des chiffres (par exemple « +4.2pp on `tool_accuracy` across all segments »)
- **{Finding 2}** : description d'une ligne
- **{Finding 3}** (si présent) : description d'une ligne
[Pour modes Q&A : puce verdict d'une ligne + puce rationale d'une ligne]

### Recommendations

1. **{Recommendation 1}** : prochaine étape spécifique et actionnable liée à une conclusion
2. **{Recommendation 2}** : prochaine étape spécifique et actionnable
3. **{Recommendation 3}** (si présent) : prochaine étape spécifique et actionnable
[Omettez cette sous-section pour les modes Q&A sauf si une action claire découle de la réponse.]

## Orientation

[Tableau côte à côte pour comparatif ; tableau récapitulatif pour single. Incluez : samples, erreurs (nombre + répartition par `error_type` si non-zéro, sinon « none »), métriques, dimensions. Les IDs d'expérience dans les en-têtes de colonne doivent être des liens Markdown.]

## What Changed

[Modes comparatifs uniquement. Tableau des différences entre baseline et candidate : modèle, profil de toolset/skill, dataset, schéma d'évaluateur et toute autre différence de métadonnées détectable à partir des données de résumé. Si aucune différence n'est détectable, écrivez : « No configuration differences detected between experiments. »]

## [Signals | Answer to Question]

[Pour exploratory : tableau classé des signaux/segments avec deltas de métrique et counts d'impact.]
[Pour Q&A : réponse directe avec verdict, puis preuve à l'appui.]

## Deep Dive Findings

### [Issue/Finding Title]

**Segment** : `[dimension=value]` | **Impact** : N samples | **Severity** : metric pass rate = X% | [View samples](https://app.datadoghq.com/llm/experiments/{experiment_id}?selectedTab=overview&filter[{dimension}]={value})

**Issue type** : `Agent` — l'évaluateur est correct ; la sortie de l'agent est le problème. | `Evaluator/Dataset` — la sortie de l'agent peut être correcte ; la rubrique, les labels de vérité de base ou la logique de notation est suspecte. | `Ambiguous` — impossible de déterminer d'après les preuves disponibles si l'agent ou l'évaluateur est à blâmer ; signalez pour inspection manuelle.

**What's happening** : [observation clé de 1–2 phrases et impact sur la métrique uniquement]

**Representative examples** :
- [Span link] : [input → output → expected, ce qui s'est mal passé]

**Root cause hypothesis** : [Catégorie] : [Explication liée à la preuve]

**Recommendation** : [Prochaine étape spécifique et actionnable]

---
[Répétez pour chaque problème majeur]

## Synthesis

[Requis dans tous les modes. Vient après tous les Deep Dive Findings, avant UI Links.]

**Issue tally** : [N agent issues, N evaluator/dataset issues, N ambiguous]

### Overall Performance Assessment
[2–4 phrases sur la qualité globale : ce que l'expérience montre, si l'app/le modèle est production-ready sur cette tâche, chiffres clés.]

### Worst-Performing Segments
[Liste à puces : quelles valeurs de dimension ou conditions prédisent le plus fiablement l'échec. Inclure les valeurs de métriques.]

### Root Cause Hypothesis
[La cause profonde la plus probable sur tous les résultats. S'il y a plusieurs causes profonde indépendantes, énumérez-les classées par impact. Chaque hypothèse doit être liée à une preuve spécifique, non à des noms de label ou à un raisonnement général.]

### Recommended Next Experiments
[2–4 expériences de suivi concrètes et spécifiques. Chacune doit être actionnable : par exemple « Re-run with `max_turns=40` to test whether turn exhaustion is the primary driver, not model quality » non « Investigate turn limits further. »]

## UI Links

[Tous les liens UI Datadog générés avec labels]

Règles d'exploitation

• Ne supposez rien à propos de l'expérience (modèle, tâche, métriques, schéma, dimensions). Déduisez tout en inspectant les données.
• Fondez toutes les conclusions sur des preuves spécifiques : IDs d'événement, comptages, pourcentages.
• Montrez les mathématiques : incluez les comptages et les taux, pas seulement les affirmations qualitatives.
• Évitez les explications spéculatives non soutenues par la preuve observée.
• Masquez ou supprimez les PII dans toutes les sorties visibles par l'utilisateur.

Référence des outils

Cet appendice s'applique uniquement en mode pup. En mode MCP, utilisez les noms d'outils des sections de workflow directement.

Experiments

Notebooks

Le fichier de cellules est un tableau JSON d'objets de cellule :

[{"attributes": {"definition": {"type": "markdown", "text": "## Section\n\nContent."}}, "type": "notebook_cells"}]

• Ne montrez jamais les appels d'outils internes, les schémas ou les détails d'implémentation à l'utilisateur.