amplitude/builder-skills

Monitor de Experimentos & Gerador de Relatórios

Escaneie experimentos ativos e recém-concluídos, destaque o que precisa de atenção e relate sobre os que são importantes.

Esta é uma skill de monitoramento — mantenha a saída acessível para não especialistas. Evite jargões estatísticos (sem p-valores, sem análise de poder). Para análise aprofundada de um experimento específico, use a skill analyze-experiments.

---

CRÍTICO: Gerenciando Tamanhos de Resposta

1. get_experiments: máximo 3-5 IDs por chamada. Filtre usando resultados de search ANTES de buscar.
2. Respostas de query_experiment são grandes. Extraia apenas objetos summary e flags de validade. Ignore timeseries, xValues, arrays volumosos.
3. Resolução de nomes de métricas: search NÃO corresponde a IDs de métricas em queries. Pesquise com entityTypes: ["METRIC"], queries vazio, limitPerQuery: 50, escopo no projeto. Corresponda IDs dos resultados.

---

Estrutura do Relatório

O relatório tem duas partes:

1. Resumo & Ações (topo) — Uma tabela + itens de ação. Alguém deve ser capaz de ler apenas isso e entender o quadro completo.
2. Detalhes (fundo) — Análises aprofundadas de experimentos que precisam de atenção, resumos de decisões recentes, frases curtas para experimentos em monitoramento e uma lista de experimentos que precisam de configuração.

NÃO duplique informações entre a tabela de resumo e os detalhes. A tabela de resumo é a fonte única da verdade para o estado do portfólio. Os detalhes expandem experimentos específicos.

---

Instruções

Passo 1: Contexto & Descoberta

1. Chame Amplitude:get_context. Se houver múltiplos projetos, pergunte qual monitorar.
2. Pesquise por experimentos:

Amplitude:search({
  entityTypes: ["EXPERIMENT"],
  appIds: [projectId],
  queries: [],
  sortOrder: "lastModified",
  sortDirection: "DESC",
  limitPerQuery: 50
})

3. Regras de filtragem — inclua experimentos que são:
   • Em execução e não estagnados: Qualquer experimento em estado de execução que NÃO esteja marcado como estagnado. Experimentos estagnados ficaram ociosos e devem ser excluídos.
   • Recentemente decididos: Experimentos concluídos que têm uma decisão registrada E foram modificados nos últimos 14 dias. Vale a pena revisá-los para confirmar a decisão ou compartilhar aprendizados.
4. Exclua: Rascunhos, experimentos desativados e experimentos estagnados.

---

Passo 2: Buscar Metadados, Nomes de Métricas e Resultados Primários

1. Chame Amplitude:get_experiments em lotes de 3-5 IDs (apenas o conjunto filtrado do Passo 1).
2. Extraia: estado, datas/duração, variantes, IDs de métricas (primárias onde recommendation=true), decisão, proprietário.
3. Aplique as regras de filtragem do Passo 1 novamente usando os metadados detalhados (alguns campos, como status de estagnado ou decisão, podem estar disponíveis apenas aqui).
4. Resolva nomes de métricas via Amplitude:search({ entityTypes: ["METRIC"], appIds: [projectId], queries: [], limitPerQuery: 50 }). Construa mapeamento { id: nome }.
5. Para experimentos que têm métricas configuradas, chame Amplitude:query_experiment({ id: "<id>" }) (sem metricIds) para obter resultados de métricas primárias e flags de qualidade de dados. Esses dados alimentam tanto a tabela de resumo quanto as análises aprofundadas.

CRÍTICO: Nunca mostre IDs de métricas brutas ao usuário. Se um nome de métrica não puder ser resolvido, descreva-o pelo seu papel (ex.: "métrica primária", "métrica de proteção") — NÃO exiba strings como "rrgtky08" ou "Metric gvgb5efj". IDs de métricas são identificadores internos que não significam nada para um leitor humano.

---

Passo 3: Resumo & Ações

Este é o topo do relatório. Deve ser autocontido — alguém lendo apenas esta sessão obtém o quadro completo.

Tabela de resumo

## Monitor de Experimentos: [Nome do Projeto]
Data: [Hoje] | Projeto: [Nome] ([ID])

| Experimento | Estado | Duração | Elevação | Veredito |
|-------------|--------|---------|----------|----------|

Definições das colunas:

• Experimento — Nome legível (NÃO uma URL, NÃO um ID)
• Estado — Executando ou Concluído
• Duração — Dias desde o início do experimento
• Elevação — Elevação relativa da métrica primária, se disponível; "—" se não houver dados. Para multivariante, mostre intervalo (ex.: "-17% a -20%")
• Veredito — O que fazer (veja vocabulário abaixo)

Vocabulário de vereditos:

Veredito	Quando usar
Enviar	Primária significativamente positiva, proteções limpas, qualidade de dados boa
Iterar	Sinal positivo, mas regressão em proteção ou preocupação de qualidade
Monitorar	Em execução, ainda não significativo, nada a fazer
Abandonar	Primária significativamente negativa, ou problemas críticos de qualidade de dados
Decidido: Enviar	Recentemente concluído, time decidiu enviar
Decidido: Não enviar	Recentemente concluído, time decidiu não enviar
Corrigir config	Erro de consulta, evento de exposição quebrado ou tráfego severamente desbalanceado
Precisa de métricas	Executando sem métricas — não é possível avaliar
N/A	Implantação de pesquisa/nudge, não é um experimento de funcionalidade

Itens de ação (imediatamente após a tabela)

**Agir agora:**
- [Experimento] — [ação específica com nome do proprietário]

**Continuar monitorando:**
- [Experimento] — [status breve + quando verificar novamente]

**Precisa de configuração:**
- [Experimento] — [o que está faltando + nome do proprietário]

Cada experimento da tabela deve aparecer em exatamente uma categoria de ação. Se não houver experimentos em uma categoria, omita essa categoria.

---

Passo 4: Detalhes

Abaixo do resumo, forneça detalhes adicionais organizados em seções. Cada experimento aparece em exatamente UMA seção — sem duplicação.

4a: Análises Aprofundadas (experimentos que precisam de atenção)

Análise aprofundada de experimentos com vereditos Enviar, Iterar ou Abandonar (até 3). Esses têm resultados significativos que merecem exame.

Para cada um, produza o relatório completo em uma única passagem:

---
## [Nome do Experimento]
[Estado] | [Duração]d | Controle: [N] / Tratamento: [N] | [Link para o experimento]

Qualidade dos dados (primeiro — antes dos resultados):

Verifique a qualidade dos dados ANTES de relatar os resultados das métricas. Se houver problemas críticos, o leitor precisa desse contexto antes de interpretar quaisquer números.

Se tudo passar, uma linha: "Todas as verificações de qualidade de dados passam." Então prossiga para a métrica primária.

Se problemas forem encontrados, relate antes da métrica primária:

### Qualidade dos Dados: [N problemas encontrados]

SRM (Sample Ratio Mismatch):

• Use o campo srmDetected da resposta da API
• Se srmDetected: true: sempre relate primeiro e proeminentemente
• Relate: divisão real vs. divisão esperada com percentuais específicos

Mudanças na alocação de tráfego:

• Compare os pesos atuais das variantes com a distribuição de exposição cumulativa
• Se não coincidirem (ex.: pesos atuais são 100/0/0, mas cumulativo é 15/70/15), a alocação foi alterada no meio do experimento
• Sinalize isso proeminentemente — significa que algumas variantes podem não estar mais recebendo novo tráfego

Tamanho da amostra:

• <100 por variante: Sinalize como insuficiente — muito cedo para quaisquer conclusões
• 100–1.000 por variante: Sinais direcionais apenas, não o suficiente para decisões confiantes
• 1.000+: Adequado para análise

Flags de validade — relate apenas falhas:

Flag	O que significa quando falha	Gravidade
isVariancePositive = false	Dados da métrica são inválidos — testes estatísticos não podem ser executados	Crítica
isConfidenceIntervalNotFlipped = false	Erro de cálculo nos resultados — não confie nos números	Crítica
isMeanValid = false	Valores da métrica estão quebrados (NaN/infinito) — não é possível analisar	Crítica
statsAssumptionsMetForWholeExperiment = false	Premissas estatísticas não são atendidas — resultados podem ser não confiáveis	Alta
hasSuspiciousUplift = true	Efeito incomumente grande — pode ser um erro de medição, não uma mudança real	Alta
isPointEstimateInsideConfidenceInterval = false	Inconsistência matemática interna — resultados podem estar errados	Alta
isStandardErrorLargeEnough = false	Muito ruído para obter estimativas confiáveis	Média

Se SRM for detectado ou uma flag Crítica falhar:

⚠️ Os resultados abaixo devem ser interpretados com cautela devido a [problema].

Métrica Primária:

### [Nome da Métrica]: [Veredito em linguagem simples]

| Variante | Valor | Elevação | IC 95% |
|----------|-------|----------|--------|
| Controle | [X] | — | — |
| Tratamento | [Y] | [+Z%] | [A% a B%] |

[Uma frase de interpretação em linguagem simples.]

Regras de enquadramento:

• NÃO inclua p-valores. Não especialistas não sabem o que significam.
• Use "não significativo" em vez de "sem efeito". Pode haver um efeito — o experimento simplesmente não consegue detectá-lo com este tamanho amostral.
• Comece com o que aconteceu em linguagem simples.

Palavras de veredito:

• Significativamente positivo — IC inteiramente acima de zero, elevação positiva
• Significativamente negativo — IC inteiramente abaixo de zero, elevação negativa
• Não significativo — IC inclui zero; não podemos dizer com confiança que há uma diferença real ainda
• Tendência positiva/negativa — Sinal direcional, mas IC inclui zero; vale a pena monitorar

Adicione uma frase sobre significância prática apenas se a elevação for muito pequena (<2%) ou muito grande (>20%).

Proteções e Métricas Secundárias:

Chame Amplitude:query_experiment({ id: "<id>", metricIds: [...] }).

Concentre-se em capturar regressões, não em narrar cada métrica.

Se não houver regressões significativas: "Todas as proteções e métricas secundárias estão limpas — nenhuma regressão significativa detectada."

Se regressões significativas forem encontradas:

- **[Nome da Métrica]:** Regressão significativa ([−X%], IC: [A% a B%]) — [uma frase sobre o impacto]

Se grandes regressões direcionais (>20% de elevação relativa) que ainda não são significativas:

- **[Nome da Métrica]:** Não significativo, mas direcionalmente negativo ([−X%]) — vale a pena monitorar

Pequenas mudanças direcionais que não são significativas devem ser omitidas. Se 5+ métricas, observe que comparações múltiplas aumentam a chance de falsos positivos.

Feedback (apenas se a primária for significativa):

Chame Amplitude:get_feedback_insights com palavras-chave relacionadas ao experimento. Relate 2-3 temas em uma linha cada. Se não houver feedback relevante, pule a seção.

Veredito:

### Veredito: [ENVIAR / ITERAR / MONITORAR / ABANDONAR]
1. [Descoberta da métrica primária — uma frase]
2. [Status de qualidade/proteções — uma frase]
3. [O que fazer a seguir — uma frase]

Matriz de decisão (referência interna, não produza em saída):

Sinal	Enviar	Iterar	Monitorar	Abandonar
Primária	Significativamente positivo + prático	Significativamente positivo, mas regressão em proteção	Ainda não significativo, ainda executando	Significativamente negativo
Qualidade	Todos passam	Flags menores	Todos passam ou dados insuficientes	SRM ou flags críticas
Proteções	Limpas	1 regressão precisa ser corrigida	Limpas ou dados insuficientes	Regressão significativa em métrica crítica
Estado do experimento	Concluído	Concluído	Executando	Concluído ou executando

4b: Experimentos em Execução (monitoramento, nenhuma ação necessária)

Para experimentos com veredito Monitorar, forneça um status de uma linha cada:

---
### Experimentos em Execução

**[Nome]** — Executando [X]d, Controle: [N] / Tratamento: [N]. [Status da métrica primária — ex.: "tendência positiva (+3,3%) mas ainda não significativa"]. Qualidade dos dados limpa. [Link]

**[Nome]** — Executando [X]d, Controle: [N] / Tratamento: [N]. Muito cedo para conclusões — [motivo, ex.: "tamanhos amostrais estão na faixa de 100-1.000"]. [Link]

Mantenha-os concisos — uma linha por experimento. Inclua o link no final para quem quiser verificar no Amplitude.

4c: Recentemente Decididos (resumos breves)

Para experimentos com veredito Decidido: Enviar ou Decidido: Não enviar:

---
### Recentemente Decididos

- **[Nome]** — [Enviado/Desfeito] em [data] após [X] dias. [Uma frase sobre resultado ou justificativa]. [Link]

Se o experimento foi enviado sem métricas ou sem significância estatística, observe isso brevemente.

4d: Precisa de Configuração

Para experimentos com veredito Corrigir config, Precisa de métricas ou N/A:

---
### Precisa de Configuração

- **[Nome]** — [Descrição do problema]. Proprietário: [proprietário].
- **[Nome]** — Implantação de pesquisa/nudge, não é um experimento de funcionalidade. Nenhuma análise necessária.

Cada experimento aparece em exatamente uma seção de detalhes. NÃO liste um experimento tanto na tabela de resumo/ações QUANTO em uma seção de detalhes com a mesma informação — a seção de detalhes expande o item de ação, não o repete.

---

Casos Extremos

• Nenhum experimento: Relate claramente, sugira verificar outros projetos
• Nenhum dado (<24h): Observe que o experimento acabou de começar, verifique novamente em 7 dias
• SRM detectado: Lidere com isso na qualidade dos dados — pode invalidar todo o resto
• 10+ experimentos: Tabela de resumo para todos, análise aprofundada dos 3 primeiros, ofereça-se para analisar mais
• Resposta muito grande / salva em disco: Extraia apenas summary + flags de validade
• Nenhuma métrica configurada: Liste na seção "Precisa de Configuração", não faça análise aprofundada
• Todos os experimentos estão estagnados: Relate que não há experimentos ativos para monitorar
• Erro de consulta de query_experiment: Relate o erro claramente com o nome do proprietário do experimento. Sinalize como "Corrigir config" no resumo. Causas comuns: propriedade de evento de exposição quebrada, chave de experimento mal configurada.
• Alocação de tráfego alterada no meio do experimento: Sinalize na qualidade dos dados. Compare pesos atuais com a distribuição de exposição cumulativa. Observe quais variantes não estão mais recebendo tráfego.
• Experimentos de pesquisa/nudge (NPS, etc.): Observe no resumo como N/A. Nenhuma análise necessária — pule análise aprofundada.
• Tráfego severamente desbalanceado (ex.: 5%/95% ou 0%/100%): Sinalize como "Corrigir config" — não é possível executar um experimento válido sem um grupo de controle significativo. Observe na seção de configuração com o proprietário.