data-explore

name	data-explore
description	Perfila e explora um dataset para entender sua forma, qualidade e padrões. Use ao encontrar uma nova tabela ou arquivo, verificar taxas de nulo e distribuições de colunas, identificar problemas de qualidade como duplicatas ou valores suspeitos, ou decidir quais dimensões e métricas analisar. Funciona com tabelas PostgreSQL do stack Evolution (Evo CRM, Evo AI), dados do Stripe, Omie, Licensing, ou arquivos CSV/Excel carregados.
argument-hint	<nome da tabela, fonte de dados ou arquivo>

data-explore — Perfilar e Explorar um Dataset

Gera um perfil de dados abrangente para uma tabela ou arquivo carregado. Entenda a forma, qualidade e padrões dos dados antes de mergulhar na análise.

Uso

/data-explore <nome_da_tabela ou arquivo>

Fluxo de Trabalho

1. Acessar os Dados

Se a fonte de dados estiver disponível via skill ou conexão PostgreSQL:

1. Resolver o nome da tabela (tratar prefixos de schema, sugerir correspondências se ambíguo)
2. Consultar metadados da tabela: nomes de colunas, tipos, descrições se disponíveis
3. Executar queries de perfilamento contra os dados ao vivo

Se um arquivo for fornecido (CSV, Excel, Parquet, JSON):

1. Ler o arquivo e carregar no dataset de trabalho
2. Inferir tipos de colunas a partir dos dados

Se for uma fonte do workspace (Stripe, Omie, Licensing, Evo CRM):

1. Usar a skill correspondente (int-stripe, int-omie, int-licensing, int-evo-crm)
2. Extrair uma amostra representativa
3. Prosseguir com o perfilamento sobre os dados extraídos

Se nenhum dado estiver disponível:

1. Pedir ao usuário que forneça o nome de uma tabela (com fonte conectada) ou faça upload de um arquivo
2. Se descrever um schema de tabela, fornecer orientação sobre quais queries de perfilamento executar

2. Entender a Estrutura

Antes de analisar qualquer dado, entender sua estrutura:

Perguntas a nível de tabela:

• Quantas linhas e colunas?
• Qual é o grain (uma linha por quê)?
• Qual é a chave primária? É única?
• Quando os dados foram atualizados pela última vez?
• Até quando os dados retroagem?

Classificação de colunas — categorizar cada coluna como uma de:

• Identificador: Chaves únicas, chaves estrangeiras, IDs de entidade
• Dimensão: Atributos categóricos para agrupamento/filtragem (status, tipo, plano, país)
• Métrica: Valores quantitativos para medição (receita, contagem, duração, score)
• Temporal: Datas e timestamps (criado_em, atualizado_em, data_evento)
• Texto: Campos de texto livre (descrição, notas, nome)
• Booleano: Flags verdadeiro/falso
• Estrutural: JSON, arrays, estruturas aninhadas

3. Gerar Perfil de Dados

Executar as seguintes verificações de perfilamento:

Métricas a nível de tabela:

• Contagem total de linhas
• Contagem de colunas e breakdown de tipos
• Tamanho aproximado da tabela (se disponível nos metadados)
• Cobertura do intervalo de datas (min/max das colunas de data)

Todas as colunas:

• Contagem de nulos e taxa de nulos
• Contagem distinta e razão de cardinalidade (distinto / total)
• Valores mais comuns (top 5-10 com frequências)
• Valores menos comuns (bottom 5 para identificar anomalias)

Colunas numéricas (métricas):

min, max, média, mediana (p50)
desvio padrão
percentis: p1, p5, p25, p75, p95, p99
contagem de zeros
contagem de negativos (se inesperado)

Colunas string (dimensões, texto):

comprimento mínimo, máximo, médio
contagem de strings vazias
análise de padrão (valores seguem um formato?)
consistência de case (tudo maiúsculo, minúsculo, misto?)
contagem de espaços antes/depois

Colunas de data/timestamp:

data mínima, data máxima
datas nulas
datas futuras (se inesperado)
distribuição por mês/semana
lacunas na série temporal

Colunas booleanas:

contagem de verdadeiro, falso, nulo
taxa de verdadeiro

Apresentar o perfil como uma tabela de resumo limpa, agrupada por tipo de coluna (dimensões, métricas, datas, IDs).

4. Identificar Problemas de Qualidade dos Dados

Aplicar o framework de avaliação de qualidade abaixo. Sinalizar problemas potenciais:

• Altas taxas de nulo: Colunas com >5% de nulos (avisar), >20% de nulos (alertar)
• Surpresas de baixa cardinalidade: Colunas que deveriam ser de alta cardinalidade mas não são (ex: um instancia_id com apenas 50 valores distintos)
• Surpresas de alta cardinalidade: Colunas que deveriam ser categóricas mas têm muitos valores distintos
• Valores suspeitos: Valores negativos onde apenas positivos são esperados, datas futuras em dados históricos, valores claramente placeholder (ex: "N/A", "TBD", "test", "999999", "0000-00-00")
• Detecção de duplicatas: Verificar se há uma chave natural e se ela tem duplicatas
• Distorção de distribuição: Distribuições numéricas extremamente distorcidas que podem afetar médias
• Problemas de encoding: Case misto em campos categóricos, espaços em branco, formatos inconsistentes

5. Descobrir Relacionamentos e Padrões

Após perfilar colunas individuais:

• Candidatos a chave estrangeira: Colunas de ID que podem se ligar a outras tabelas
• Hierarquias: Colunas que formam caminhos naturais de drill-down (país > estado > cidade)
• Correlações: Colunas numéricas que se movem juntas
• Colunas derivadas: Colunas que parecem calculadas a partir de outras
• Colunas redundantes: Colunas com informações idênticas ou quase idênticas

6. Sugerir Dimensões e Métricas Interessantes

Com base no perfil de colunas, recomendar:

• Melhores colunas de dimensão para segmentar dados (colunas categóricas com cardinalidade razoável, 3-50 valores)
• Colunas de métrica-chave para medição (colunas numéricas com distribuições significativas)
• Colunas de tempo adequadas para análise de tendências
• Agrupamentos naturais ou hierarquias aparentes nos dados
• Chaves de join potenciais para ligar a outras tabelas

7. Recomendar Análises de Acompanhamento

Sugerir 3-5 análises específicas que o usuário poderia executar a seguir:

• "Análise de tendência em [métrica] por [coluna_temporal] agrupada por [dimensão]"
• "Aprofundamento de distribuição em [coluna_distorcida] para entender outliers"
• "Investigação de qualidade de dados em [coluna_problemática]"
• "Análise de correlação entre [métrica_a] e [métrica_b]"
• "Análise de cohort usando [coluna_data] e [coluna_status]"

Formato de Saída

## Perfil de Dados: [nome_da_tabela]

### Visão Geral
- Linhas: 2.340.891
- Colunas: 23 (8 dimensões, 6 métricas, 4 datas, 5 IDs)
- Intervalo de datas: 2021-03-15 a 2024-01-22
- Última atualização: 2024-01-22 03:45 BRT

### Detalhes das Colunas
[tabela de resumo]

### Problemas de Qualidade de Dados
[problemas sinalizados com severidade]

### Explorações Recomendadas
[lista numerada de análises de acompanhamento sugeridas]

---

Framework de Avaliação de Qualidade

Score de Completude

Avaliar cada coluna:

• Completa (>99% não-nulo): Verde
• Majoritariamente completa (95-99%): Amarelo — investigar os nulos
• Incompleta (80-95%): Laranja — entender por que e se importa
• Esparsa (<80%): Vermelho — pode não ser utilizável sem imputação

Verificações de Consistência

Procurar por:

• Inconsistência de formato de valor: Mesmo conceito representado diferentemente ("Brasil", "BR", "Brazil", "br")
• Inconsistência de tipo: Números armazenados como strings, datas em vários formatos
• Integridade referencial: Chaves estrangeiras que não correspondem a nenhum registro pai
• Violações de regras de negócio: Quantidades negativas, datas de fim antes de datas de início, percentuais > 100
• Consistência entre colunas: Status = "concluído" mas concluido_em é nulo

Indicadores de Precisão

Sinais de alerta que sugerem problemas de precisão:

• Valores placeholder: 0, -1, 999999, "N/A", "TBD", "test", "xxx"
• Valores padrão: Frequência suspeitosamente alta de um único valor
• Dados desatualizados: atualizado_em não mostra alterações recentes em um sistema ativo
• Valores impossíveis: Idades > 150, datas no futuro distante, durações negativas
• Viés de números redondos: Todos os valores terminando em 0 ou 5 (sugere estimativa, não medição)

Avaliação de Atualidade

• Quando a tabela foi atualizada pela última vez?
• Qual é a frequência esperada de atualização?
• Há uma defasagem entre o tempo do evento e o tempo de carga?
• Existem lacunas na série temporal?

Técnicas de Descoberta de Padrões

Análise de Distribuição

Para colunas numéricas, caracterizar a distribuição:

• Normal: Média e mediana próximas, formato de sino
• Assimetria à direita: Cauda longa de valores altos (comum para receita, duração de sessão)
• Assimetria à esquerda: Cauda longa de valores baixos (menos comum)
• Bimodal: Dois picos (sugere duas populações distintas)
• Lei de potência: Poucos valores muito grandes, muitos pequenos (comum para atividade de usuário)
• Uniforme: Frequência aproximadamente igual ao longo do intervalo (frequentemente sintético ou aleatório)

Padrões Temporais

Para dados de séries temporais, procurar por:

• Tendência: Movimento sustentado para cima ou para baixo
• Sazonalidade: Padrões repetitivos (semanal, mensal, trimestral, anual)
• Efeitos de dia da semana: Diferenças entre dias úteis e fins de semana
• Efeitos de feriado: Quedas ou picos em torno de feriados conhecidos (feriados brasileiros)
• Pontos de mudança: Mudanças abruptas no nível ou tendência
• Anomalias: Pontos de dados individuais que quebram o padrão

Descoberta de Segmentação

Identificar segmentos naturais por:

• Encontrar colunas categóricas com 3-20 valores distintos
• Comparar distribuições de métricas entre valores de segmento
• Procurar segmentos com comportamento significativamente diferente
• Testar se os segmentos são homogêneos ou contêm sub-segmentos

Exploração de Correlação

Entre colunas numéricas:

• Calcular matriz de correlação para todos os pares de métricas
• Sinalizar correlações fortes (|r| > 0,7) para investigação
• Nota: Correlação não implica causalidade — sinalizar isso explicitamente
• Verificar relacionamentos não lineares (ex: quadrático, logarítmico)

Documentação de Schema

Template de Documentação de Schema

Ao documentar um dataset para uso da equipe:

## Tabela: [schema.nome_da_tabela]

**Descrição**: [O que esta tabela representa]
**Grain**: [Uma linha por...]
**Chave Primária**: [coluna(s)]
**Contagem de Linhas**: [aproximada, com data]
**Frequência de Atualização**: [tempo real / hora / dia / semana]
**Responsável**: [equipe ou pessoa]

### Colunas-Chave

| Coluna | Tipo | Descrição | Valores de Exemplo | Notas |
|--------|------|-----------|-------------------|-------|
| instancia_id | UUID | Identificador único da instância | "inst_abc123" | FK para instancias.id |
| versao | STRING | Versão do Evolution API | "2.1.4", "2.2.0" | 50+ valores distintos |
| mrr | DECIMAL | Receita mensal recorrente em USD | 29.99, 149.00 | Nulo para contas free |
| criado_em | TIMESTAMP | Quando o registro foi criado | 2024-01-15 14:23:01 | UTC — converter para BRT na exibição |

### Relacionamentos
- Join com `clientes` por `cliente_id`
- Join com `planos` por `plano_id`
- Pai de `instancia_eventos` (1:N por instancia_id)

### Problemas Conhecidos
- [Listar problemas conhecidos de qualidade de dados]
- [Anotar quaisquer armadilhas para analistas]

### Padrões Comuns de Query
- [Casos de uso típicos para esta tabela]

Queries de Exploração de Schema (PostgreSQL)

-- Listar todas as tabelas no schema public
SELECT table_name, table_type
FROM information_schema.tables
WHERE table_schema = 'public'
ORDER BY table_name;

-- Detalhes das colunas (PostgreSQL)
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_name = 'minha_tabela'
ORDER BY ordinal_position;

-- Tamanhos das tabelas (PostgreSQL)
SELECT relname,
       pg_size_pretty(pg_total_relation_size(relid)) AS tamanho_total
FROM pg_catalog.pg_statio_user_tables
ORDER BY pg_total_relation_size(relid) DESC;

-- Contagens de linhas por tabela
-- Executar por tabela: SELECT COUNT(*) FROM nome_da_tabela

-- Verificar duplicatas em chave primária
SELECT chave_primaria, COUNT(*)
FROM minha_tabela
GROUP BY chave_primaria
HAVING COUNT(*) > 1;

-- Taxas de nulo por coluna (gerar dinamicamente)
SELECT
    COUNT(*) FILTER (WHERE coluna_1 IS NULL) * 100.0  ()  nulo_pct_col1,
    ()  ( coluna_2  )    ()  nulo_pct_col2
 minha_tabela;

Dicas

• Para tabelas muito grandes (100M+ linhas), queries de perfilamento usam amostragem por padrão — mencionar se precisar de contagens exatas
• Se explorando um dataset pela primeira vez, este comando fornece a visão geral antes de escrever queries específicas
• Os sinalizadores de qualidade são heurísticos — nem todo sinal é um problema real, mas cada um merece uma verificação rápida
• Sempre verificar os dados no contexto: o que faz sentido para Stripe é diferente do que faz sentido para Licensing