Data Validate

data-validate — Validar Análise Antes de Compartilhar

Revisar uma análise quanto à precisão, metodologia e possíveis vieses antes de compartilhar com stakeholders. Gera uma avaliação de confiança e sugestões de melhoria.

Uso

/data-validate <análise para revisar>

A análise pode ser:

• Um documento ou relatório na conversa
• Um arquivo (markdown, notebook, planilha)
• Queries SQL e seus resultados
• Gráficos e seus dados subjacentes
• Uma descrição de metodologia e achados

Fluxo de Trabalho

1. Revisar Metodologia e Premissas

Examinar:

• Formulação da questão: A análise está respondendo à pergunta certa? A questão pode ser interpretada de forma diferente?
• Seleção de dados: As tabelas/datasets corretos estão sendo usados? O intervalo de tempo é apropriado?
• Definição de população: A população da análise está corretamente definida? Há exclusões não intencionais?
• Definições de métricas: As métricas são definidas de forma clara e consistente? Correspondem a como os stakeholders as entendem?
• Baseline e comparação: A comparação é justa? Períodos de tempo, tamanhos de cohort e contextos são comparáveis?

2. Executar o Checklist de QA Pré-Entrega

Percorrer o checklist abaixo — qualidade dos dados, cálculo, razoabilidade e verificações de apresentação.

3. Verificar Armadilhas Analíticas Comuns

Revisar sistematicamente contra o catálogo detalhado de armadilhas abaixo (join explosivo, viés de sobrevivência, comparação de período incompleto, denominador variável, média de médias, desalinhamento de fuso horário, viés de seleção).

4. Verificar Cálculos e Agregações

Onde possível, fazer spot-checks:

• Recalcular alguns números-chave de forma independente
• Verificar se os subtotais somam corretamente aos totais
• Confirmar que os percentuais somam a ~100% onde esperado
• Validar que comparações AaA/MaM usam os períodos base corretos
• Verificar se os filtros são aplicados de forma consistente em todas as métricas

Aplicar as técnicas de verificação de sanidade de resultados abaixo.

5. Avaliar Visualizações

Se a análise inclui gráficos:

• Os eixos começam em valores apropriados (zero para gráficos de barras)?
• As escalas são consistentes entre gráficos de comparação?
• Os títulos dos gráficos descrevem com precisão o que é mostrado?
• A visualização poderia enganar um leitor rápido?
• Há eixos truncados, intervalos inconsistentes, ou efeitos 3D que distorcem a percepção?

6. Avaliar Narrativa e Conclusões

Revisar se:

• As conclusões são suportadas pelos dados mostrados
• Explicações alternativas são reconhecidas
• A incerteza é comunicada adequadamente
• As recomendações seguem logicamente dos achados
• O nível de confiança corresponde à força das evidências

7. Sugerir Melhorias

Fornecer sugestões específicas e acionáveis:

• Análises adicionais que fortaleceriam as conclusões
• Ressalvas ou limitações que devem ser anotadas
• Melhores visualizações ou enquadramentos para pontos-chave
• Contexto ausente que os stakeholders iriam querer

8. Gerar Avaliação de Confiança

Classificar a análise em uma escala de 3 níveis:

Pronta para compartilhar — A análise é metodologicamente sólida, cálculos verificados, ressalvas anotadas. Sugestões menores de melhoria mas nada bloqueando.

Compartilhar com ressalvas anotadas — A análise é majoritariamente correta mas tem limitações ou premissas específicas que devem ser comunicadas aos stakeholders. Listar as ressalvas obrigatórias.

Precisa de revisão — Encontrou erros específicos, problemas metodológicos, ou análises faltantes que devem ser abordados antes de compartilhar. Listar as mudanças necessárias com ordem de prioridade.

Formato de Saída

## Relatório de Validação

### Avaliação Geral: [Pronta para compartilhar | Compartilhar com ressalvas | Precisa de revisão]

### Revisão de Metodologia
[Achados sobre abordagem, seleção de dados, definições]

### Problemas Encontrados
1. [Severidade: Alta/Média/Baixa] [Descrição do problema e impacto]
2. ...

### Spot-Checks de Cálculo
- [Métrica]: [Verificado / Discrepância encontrada]
- ...

### Revisão de Visualização
[Quaisquer problemas com gráficos ou apresentação visual]

### Melhorias Sugeridas
1. [Melhoria e por que é importante]
2. ...

### Ressalvas Obrigatórias para Stakeholders
- [Ressalva que deve ser comunicada]
- ...

Checklist de QA Pré-Entrega

Percorrer este checklist antes de compartilhar qualquer análise com stakeholders.

Verificações de Qualidade dos Dados

• Verificação de fonte: Confirmado quais tabelas/fontes de dados foram usadas. São as corretas para esta pergunta?
• Atualidade: Os dados são atuais o suficiente para a análise. A data "referente a" foi anotada.
• Completude: Sem lacunas inesperadas em séries temporais ou segmentos faltantes.
• Tratamento de nulos: Taxas de nulo verificadas em colunas-chave. Nulos são tratados adequadamente (excluídos, imputados ou sinalizados).
• Deduplicação: Confirmado que não há dupla contagem por joins ruins ou registros fonte duplicados.
• Verificação de filtros: Todas as cláusulas WHERE e filtros estão corretos. Sem exclusões não intencionais.
• Fuso horário: Timestamps estão alinhados (UTC no banco → BRT na exibição). Conversão aplicada corretamente.

Verificações de Cálculo

• Lógica de agregação: GROUP BY inclui todas as colunas não-agregadas. Nível de agregação corresponde ao grain da análise.
• Corretude do denominador: Cálculos de taxa e percentual usam o denominador correto. Os denominadores são não-zero.
• Alinhamento de datas: As comparações usam o mesmo comprimento de período de tempo. Períodos parciais são excluídos ou anotados.
• Corretude de joins: Os tipos de JOIN são apropriados (INNER vs LEFT). Joins many-to-many não inflaram contagens.
• Definições de métricas: As métricas correspondem a como os stakeholders as definem. Quaisquer desvios são anotados.
• Subtotais somam: As partes somam ao todo onde esperado. Se não somam, explicar por quê (ex: sobreposição).

Verificações de Razoabilidade

• Magnitude: Os números estão em um intervalo plausível. A receita não é negativa. Os percentuais estão entre 0-100%.
• Continuidade de tendência: Sem saltos ou quedas inexplicados em séries temporais.
• Referência cruzada: Os números-chave correspondem a outras fontes conhecidas (dashboards Stripe, relatórios do Omie, figuras anteriores).
• Ordem de magnitude: O MRR total está na ordem de grandeza certa. As contagens de instâncias correspondem às figuras conhecidas do Licensing.
• Casos extremos: O que acontece nos limites? Segmentos vazios, períodos sem atividade, novas entidades.

Verificações de Apresentação

• Precisão dos gráficos: Gráficos de barras começam em zero. Os eixos são rotulados. As escalas são consistentes entre painéis.
• Formatação de números: Precisão apropriada. Formatação consistente de moeda (R$ para BRL, $ para USD). Separadores de milhares onde necessário.
• Clareza dos títulos: Títulos enunciam o insight, não apenas a métrica. Intervalos de datas são especificados.
• Transparência de ressalvas: Limitações e premissas conhecidas são declaradas explicitamente.
• Reprodutibilidade: Outra pessoa poderia recriar esta análise a partir da documentação fornecida.

Armadilhas Comuns de Análise de Dados

Join Explosivo

O problema: Um join many-to-many silenciosamente multiplica linhas, inflando contagens e somas.

Como detectar:

-- Verificar contagem de linhas antes e depois do join
SELECT COUNT(*) FROM instancias;  -- 1.000
SELECT COUNT(*) FROM instancias i JOIN eventos e ON i.id = e.instancia_id;  -- 3.500 (problemático!)

-- Sempre usar DISTINCT para contar entidades através de joins
SELECT COUNT(DISTINCT i.id) FROM instancias i JOIN eventos e ON i.id = e.instancia_id;

Como prevenir:

• Sempre verificar contagens de linhas após joins
• Se as contagens aumentam, investigar o relacionamento do join (é realmente 1:1 ou 1:N?)
• Usar COUNT(DISTINCT id_entidade) em vez de COUNT(*) ao contar entidades através de joins

Viés de Sobrevivência

O problema: Analisar apenas entidades que existem hoje, ignorando as que foram deletadas, fizeram churn, ou falharam.

Exemplos para o workspace:

• Analisar comportamento de usuários "ativos" ignora os que cancelaram
• Ver "instâncias usando nossa plataforma" ignora as que avaliaram e saíram
• Estudar propriedades de outcomes "bem-sucedidos" sem os "malsucedidos"

Como prevenir: Perguntar "Quem NÃO está neste dataset?" antes de tirar conclusões.

Comparação de Período Incompleto

O problema: Comparar um período parcial com um período completo.

Exemplos:

• "MRR de janeiro é R$ 500K vs. dezembro R$ 800K" — mas janeiro não terminou ainda
• "Novas instâncias desta semana estão abaixo" — verificado na quarta-feira, comparando com uma semana anterior completa

Como prevenir: Sempre filtrar para períodos completos, ou comparar mesmo-dia-do-mês / mesmo-número-de-dias.

Denominador Variável

O problema: O denominador muda entre períodos, tornando as taxas incomparáveis.

Exemplos:

• Taxa de conversão melhora porque mudou como contar usuários "elegíveis"
• Taxa de churn muda porque a definição de "ativo" foi atualizada

Como prevenir: Usar definições consistentes em todos os períodos comparados. Anotar quaisquer mudanças de definição.

Média de Médias

O problema: Fazer a média de médias pré-calculadas dá resultados errados quando os tamanhos dos grupos diferem.

Exemplo:

• Plano Pro: 100 clientes, MRR médio R$ 200
• Plano Enterprise: 10 clientes, MRR médio R$ 1.000
• Errado: Média das médias = (R$ 200 + R$ 1.000) / 2 = R$ 600
• Correto: Média ponderada = (100×R$ 200 + 10×R$ 1.000) / 110 = R$ 272,73

Como prevenir: Sempre agregar a partir dos dados brutos. Nunca fazer média de médias pré-agregadas.

Desalinhamento de Fuso Horário

O problema: Diferentes fontes de dados usam fusos horários diferentes, causando desalinhamento.

Exemplos no workspace:

• Timestamps de eventos em UTC vs. datas na exibição em BRT
• Rollups diários que usam diferentes horários de corte
• Stripe reporta em UTC; exibição ao Davidson deve ser em BRT

Como prevenir: Padronizar todos os timestamps em um único fuso horário (UTC para armazenamento, BRT para exibição). Documentar o fuso horário usado.

-- Converter UTC para BRT corretamente no PostgreSQL
SELECT
    criado_em AT TIME ZONE 'UTC' AT TIME ZONE 'America/Sao_Paulo' AS criado_em_brt
FROM eventos;

-- Truncar por dia em BRT
DATE_TRUNC('day', criado_em AT TIME ZONE 'UTC' AT TIME ZONE 'America/Sao_Paulo')

Viés de Seleção na Segmentação

O problema: Os segmentos são definidos pelo outcome que está sendo medido, criando lógica circular.

Exemplos:

• "Usuários que completaram o onboarding têm maior retenção" — obviamente, eles se auto-selecionaram
• "Instâncias power users geram mais tráfego" — elas se tornaram power users POR gerar mais tráfego

Como prevenir: Definir segmentos com base em características pré-tratamento, não em outcomes.

Outras Armadilhas Estatísticas

• Paradoxo de Simpson: Tendência se inverte quando dados são agregados vs. segmentados
• Correlação apresentada como causalidade sem evidências de suporte
• Tamanhos de amostra pequenos levando a conclusões não confiáveis
• Outliers afetando desproporcionalmente médias (medianas deveriam ser usadas?)
• Testes múltiplos / cherry-picking de resultados significativos
• Viés de look-ahead: Usar informações futuras para explicar eventos passados
• Intervalos de tempo selecionados a dedo que favorecem uma narrativa particular

Verificação de Sanidade de Resultados

Verificações de Magnitude

Para qualquer número-chave na análise, verificar se passa no "teste do olfato":

Técnicas de Validação Cruzada

1. Calcular a mesma métrica de duas formas diferentes e verificar se correspondem
2. Fazer spot-check em registros individuais — escolher algumas entidades específicas e rastrear seus dados manualmente
3. Comparar com benchmarks conhecidos — comparar com dashboards publicados, relatórios financeiros, ou análises anteriores
4. Fazer engenharia reversa — se o MRR total é X, o MRR por cliente multiplicado pelo número de clientes aproxima X?
5. Verificações de limite — o que acontece ao filtrar para um único dia, um único cliente, ou uma única categoria? Esses micro-resultados fazem sentido?

Sinais de Alerta que Merecem Investigação

• Qualquer métrica que mudou mais de 50% período a período sem uma causa óbvia
• Contagens ou somas que são números redondos exatos (sugere um problema de filtro ou valor padrão)
• Taxas exatamente em 0% ou 100% (pode indicar dados incompletos)
• Resultados que confirmam perfeitamente a hipótese (a realidade geralmente é mais bagunçada)
• Valores idênticos entre períodos de tempo ou segmentos (sugere que a query está ignorando uma dimensão)

Padrões de Documentação para Reprodutibilidade

Template de Documentação de Análise

Toda análise não trivial deve incluir:

## Análise: [Título]

### Pergunta
[A pergunta específica sendo respondida]

### Fontes de Dados
- Fonte: Stripe via `int-stripe` (referente a [data])
- Fonte: Licensing via `int-licensing` (referente a [data])
- Tabela: [schema.nome_da_tabela] (referente a [data])

### Definições
- [Métrica A]: [Exatamente como é calculada]
- [Segmento X]: [Exatamente como a participação é determinada]
- [Período de tempo]: [Data de início] a [data de fim], BRT (UTC-3)

### Metodologia
1. [Passo 1 da abordagem de análise]
2. [Passo 2]
3. [Passo 3]

### Premissas e Limitações
- [Premissa 1 e por que é razoável]
- [Limitação 1 e seu impacto potencial nas conclusões]

### Principais Achados
1. [Achado 1 com evidências de suporte]
2. [Achado 2 com evidências de suporte]

### Queries SQL
[Todas as queries usadas, com comentários]

### Ressalvas
- [Coisas que o leitor deve saber antes de agir com base nisso]

Documentação de Código

Para qualquer código (SQL, Python) que possa ser reutilizado:

"""
Análise: Retenção Mensal por Cohort
Autor: Davidson Gomes
Data: 2026-04-09
Fonte de Dados: tabela de eventos, tabela de clientes
Última Validação: 2026-04-09 — resultados corresponderam ao dashboard dentro de 2%

Propósito:
    Calcular cohorts de retenção mensal de usuários com base na data da primeira assinatura.

Premissas:
    - "Ativo" significa pelo menos um evento no mês
    - Exclui contas de teste/internas (tipo_usuario != 'interno')
    - Usa timestamps UTC, exibição em BRT

Saída:
    Matriz de retenção de cohort com linhas cohort_mes e colunas meses_desde_assinatura.
    Valores são taxas de retenção (0-100%).
"""

Exemplos

/data-validate Revisar esta análise trimestral de MRR antes de eu enviar para o conselho: [análise]

/data-validate Verificar minha análise de churn — estou comparando taxas do Q4 com Q3 mas o Q4 tem uma janela de medição mais curta

/data-validate Aqui está uma query SQL e seus resultados para nosso funil de conversão do Evo CRM. A lógica parece certa? [query + resultados]

Dicas

• Rodar /data-validate antes de qualquer apresentação ou decisão de alto impacto
• Mesmo análises rápidas se beneficiam de uma verificação de sanidade — leva um minuto e pode salvar a credibilidade
• Se a validação encontrar problemas, corrigi-los e re-validar
• Compartilhar o output da validação junto com a análise para construir a confiança dos stakeholders
• Para análises derivadas de múltiplas fontes (ex: Stripe + Omie), prestar atenção especial ao alinhamento de definições entre sistemas