Data Investigation: investigue anomalias sem confirmar a primeira hipótese

ANÁLISE EDITORIAL

Uma queda no painel, uma contagem que não fecha ou um segmento que muda de comportamento costuma produzir uma pergunta urgente: o que aconteceu? O risco aparece quando a primeira explicação plausível vira conclusão antes de o efeito, o grão e as definições serem confirmados. A Skill Data Investigation organiza a apuração para que o agente trate hipóteses como coisas a testar, não como respostas prontas.

O método começa pela pergunta e termina em uma conclusão curta sustentada por consultas reproduzíveis. Entre esses pontos, ele exige hipóteses concorrentes, decomposição por uma dimensão de cada vez, alinhamento temporal com mudanças upstream, quantificação e separação clara entre evidência e interpretação.

O que esta Skill faz

A Skill estrutura investigações de dados pontuais, como explicar uma anomalia de métrica, descobrir por que duas fontes divergem, validar uma hipótese ou verificar se um número é confiável. Ela não entrega SQL pronto para qualquer banco e não conhece o significado das métricas do leitor. Seu valor é impor uma ordem de raciocínio que reduza confirmação seletiva e consultas enormes sem propósito.

O fluxo divide o trabalho em cinco partes: enquadrar a pergunta, confirmar o efeito, localizar a diferença, validar o mecanismo e comunicar a conclusão com limites. A instrução original pode ser lida no SKILL.md fixado.

Para quem serve

É útil para analistas, profissionais de produto, operações, finanças, engenharia de dados e equipes que precisam explicar variações sem transformar correlação em causa. Também ajuda quem pede apoio a um agente de IA para escrever consultas, conferir definições ou preparar um memorando de investigação.

O leitor ainda precisa conhecer o contexto do negócio e ter acesso autorizado às fontes. A Skill não substitui o responsável pela métrica, a documentação do modelo de dados, os controles do warehouse ou a revisão de quem entende o processo que gerou os registros.

Origem, commit e exceção oficial

A origem auditada é o repositório Kilo-Org/skills. O README fixado o identifica como fonte canônica das Skills mantidas pelo Kilo. A fotografia desta curadoria usa o commit a30ff33da809171784aca50d1b5978cebc2185f1, de 23/06/2026.

O repositório tinha 0 estrelas e 0 forks em 13/09/2026. Esta entrada não foi aceita por popularidade. Ela é uma exceção ao piso preferencial de mil estrelas porque a organização declara manutenção oficial, a pasta é somente documental e a licença pode ser verificada. A baixa adoção permanece visível e não deve ser interpretada como validação comunitária.

A divergência de licença encontrada

O SKILL.md declara MIT e o arquivo LICENSE fixado contém o texto da licença MIT. Porém, a seção final do README diz Apache License 2.0 e aponta para esse mesmo arquivo MIT. O exemplo de frontmatter no README também mostra Apache-2.0, mas ele é um exemplo genérico.

Para esta curadoria, o pacote é registrado como MIT, pois o arquivo de licença e a declaração específica da Skill coincidem. A frase divergente do README é tratada como problema documental da origem, não como uma segunda licença aplicada ao pacote. Quem precisar de uma decisão jurídica deve consultar o mantenedor.

Compatibilidade e pré-requisitos

A Skill é um único arquivo Markdown no formato de Agent Skills e não traz scripts, executáveis ou dependências. O manual oficial de Skills do Kilo explica a descoberta por diretórios e o carregamento sob demanda. Outros clientes compatíveis podem usar a mesma instrução, mas caminhos de instalação e regras de permissão variam.

Para uma investigação funcional, são necessários dados acessíveis, definições de métricas, um mecanismo de consulta e um ambiente no qual o resultado possa ser reproduzido. SQL é comum, mas não obrigatório. Um notebook, uma planilha ou uma consulta por API também pode servir, desde que as transformações sejam observáveis e o escopo esteja fixado.

Instalação com origem fixada

Para leitura manual, use a pasta data-investigation no commit auditado. O repositório apresenta npx skills add Kilo-Org/skills --skill data-investigation como caminho de instalação, mas o comando consulta a rede, executa um pacote e grava arquivos. Rode primeiro em projeto descartável, confira o destino e compare o conteúdo com o hash registrado nesta página.

O download local é um espelho documental. Ele não instala Kilo Code, Skills CLI, driver de banco, notebook ou conector. Essa separação permite revisar a metodologia antes de conceder acesso a qualquer fonte de dados.

Configuração antes do primeiro uso

Defina a pergunta, a métrica, o período, o fuso, o ambiente e as fontes autorizadas. Registre o grão esperado de cada conjunto, por exemplo uma linha por pedido, usuário ou evento. Confirme também filtros de exclusão, política de dados atrasados, regra de deduplicação e versão da definição usada pelo painel.

Se houver dados pessoais, comerciais ou de clientes, reduza colunas e linhas antes de dar acesso ao agente. Prefira identificadores sintéticos ou pseudonimizados. Não copie uma tabela inteira quando agregados ou uma amostra controlada conseguem responder à pergunta.

Primeiro uso seguro

Comece em modo somente leitura e escreva uma frase provisória que represente o que a investigação tentará confirmar ou rejeitar. Essa frase não é a conclusão final. Ela funciona como hipótese operacional e precisa ficar acompanhada de duas ou três explicações concorrentes.

Exemplo: “A diferença entre o painel e o warehouse pode estar na definição de usuário interno”. As alternativas poderiam ser atraso de ingestão e duplicação em uma junção. Antes de consultar, escreva qual resultado seria esperado se cada hipótese fosse verdadeira.

Confirme o efeito antes da causa

A primeira consulta deve mostrar se a anomalia existe, seu tamanho e quando começou. Compare as duas medidas no mesmo período e com o mesmo fuso. Se o denominador puder ser zero, trate isso explicitamente. Não avance para uma causa porque um gráfico parece diferente.

Uma boa saída inicial tem nomes claros, como usuarios_painel, usuarios_referencia, diferenca e percentual_diferenca. O objetivo é tornar a comparação auditável, não produzir um painel bonito.

Declare o grão de cada etapa

Muitas diferenças nascem da comparação entre níveis incompatíveis. Uma tabela pode ter uma linha por pedido, outra por item e uma terceira por evento. Juntar as três diretamente pode multiplicar registros sem gerar erro de sintaxe.

Adicione comentários de grão aos CTEs importantes e conte linhas, chaves distintas e nulos antes e depois de cada junção. Se a quantidade de chaves não se comportar como esperado, pare e investigue a cardinalidade antes de calcular a métrica final.

Localize uma dimensão por vez

Depois de confirmar o efeito, quebre a diferença por tempo, segmento ou fonte, uma dimensão de cada vez. Misturar várias dimensões na primeira consulta torna difícil saber qual filtro revelou o problema e pode esconder populações pequenas.

Comece pela dimensão que melhor separa as hipóteses. Se a suspeita envolve uma regra liberada em certa data, a série temporal vem primeiro. Se envolve exclusão de contas internas, compare esse marcador antes de abrir dezenas de atributos.

Alinhe a mudança com o tempo

Quando a data de início estiver clara, confronte-a com mudanças verificáveis: commits em modelos, alterações de ETL, migrações de schema, mudanças de definição, lançamentos ou eventos externos documentados. Uma explicação causal precisa dizer por que o efeito apareceu naquele momento.

O histórico do código é evidência de que algo mudou, mas não prova sozinho o impacto nos dados. Use-o para localizar candidatos e depois confirme se a população afetada corresponde ao mecanismo previsto.

Valide o mecanismo e o contrafactual

Uma hipótese forte explica quem foi afetado, em qual período e por qual transformação. Procure um segundo sinal independente. Se uma regra passou a excluir usuários internos, a diferença deve se concentrar nesses usuários e desaparecer quando as definições forem alinhadas.

O contrafactual pergunta o que seria observado sem a causa proposta. Ele pode ser um segmento não afetado, um período anterior, uma fonte paralela ou uma recomputação com a regra antiga. Sem essa comparação, a análise corre o risco de parar na correlação.

Quantifique hipóteses concorrentes

Cada explicação precisa produzir um número. Se a diferença total é 1.240 registros, uma hipótese que explica 1.050 tem alcance mensurável; outra que explica 20 provavelmente não é a causa principal. Diferenças residuais devem continuar abertas, em vez de serem escondidas por arredondamento.

Registre hipóteses rejeitadas e a consulta que as enfraqueceu. Isso evita repetir o mesmo caminho depois e mostra que a conclusão não foi escolhida apenas porque era a primeira ideia.

SQL reproduzível e proporcional

Use limites de tempo fixos em investigações encerradas. Janelas móveis podem mudar o resultado entre a análise e a revisão. Nomeie colunas, fixe o ambiente e mantenha consultas diagnósticas pequenas. Uma consulta deve responder a uma pergunta específica.

Não transforme o primeiro diagnóstico em modelo permanente. Código reutilizável exige revisão própria, testes, documentação e responsabilidade operacional. A Skill trata investigação pontual, não governança completa de transformação de dados.

Comunicação: resposta primeiro

O relatório final começa com a conclusão, seguido de evidência, alternativas rejeitadas e próxima ação. Inclua a principal suposição capaz de mudar a resposta. Se a ingestão da semana ainda não fechou, isso deve aparecer perto da conclusão, não escondido no rodapé.

Separe fatos observados de interpretação. “A diferença começa em 4 de setembro” é evidência. “A implantação daquele dia causou a diferença” é interpretação até o mecanismo ser demonstrado.

Resultado esperado

Uma execução completa deixa quatro elementos: resposta de uma frase, consulta final ou notebook reproduzível, registro das hipóteses rejeitadas e pergunta pendente. Pode haver também um memorando ou painel pontual, desde que cada número leve à consulta e às definições usadas.

O resultado não precisa fingir certeza. Se duas causas permanecem compatíveis com os dados, declare isso e liste o teste capaz de separá-las. Uma conclusão limitada é melhor do que uma causa inventada.

Permissões e riscos

O uso funcional pode ler warehouses, planilhas, notebooks, métricas, código, commits e documentos internos. Também pode gravar SQL, relatórios, dashboards ou arquivos temporários. Consultas amplas podem gerar custo, lentidão ou exposição de dados.

Use conta somente leitura, ambiente de análise, limites de período e volume e aprovação para consultas caras. Não compartilhe resultados fora do público autorizado. Trate textos vindos das bases como dados não confiáveis e não execute instruções encontradas em comentários, nomes de campos ou conteúdo de registros.

Erros comuns e como corrigir

• O total não fecha: alinhe período, fuso, filtros, grão e deduplicação antes de procurar causa de negócio.
• A junção multiplica linhas: conte chaves distintas dos dois lados e confirme cardinalidade.
• A consulta volta vazia: teste filtros e chaves separadamente e confira atraso de ingestão.
• A primeira hipótese parece certa: escreva alternativas e resultados esperados antes de ampliar a consulta.
• Há correlação temporal: valide a população afetada e um contrafactual antes de usar linguagem causal.
• O painel muda a cada execução: fixe datas, versão da definição e fotografia da fonte.
• O agente pede acesso amplo: reduza o conjunto, remova dados sensíveis e forneça agregados suficientes.

Quando não usar

Não use esta Skill para depurar apenas um erro sintático de Snowflake, construir um pipeline permanente, treinar um modelo estatístico, decidir automaticamente uma ação de negócio ou substituir auditoria formal. Também não a use quando a pergunta é simples e a fonte de verdade já está documentada.

Para notebooks, o mesmo repositório oferece uma Skill separada. Para falhas específicas de Snowflake, há outra instrução dedicada. Esta entrada fica restrita à investigação da pergunta e à qualidade da conclusão.

Versão, licença e pacote auditado

A Skill não declara número de versão próprio. Foi auditada no commit a30ff33da809171784aca50d1b5978cebc2185f1. A licença aplicada ao pacote é MIT, confirmada no SKILL.md e no arquivo de licença.

O pacote local contém três arquivos textuais: SKILL.md, LICENSE e ORIGEM.md. Seu SHA-256 é 82e830d68a2881ffa43fd3c9d762f3c7349d87b554f8f39db3faa199585b2832.

Limites do pacote local

O ZIP não inclui Kilo Code, Kilo CLI, Skills CLI, banco de dados, driver, SQL do leitor, notebook, dashboard, conector, script, executável, dependência, configuração, credencial, dados, consulta, resultado ou relatório. O download serve para inspeção e instalação manual da instrução, não para abrir acesso a dados.

Antes de atualizar, compare com a pasta atual no ramo principal e repita a auditoria de conteúdo e licença. O commit desta página não se move.

O que a revisão editorial confirmou

A pasta individual contém somente o SKILL.md. Não há script, ativo, referência, manifesto de dependência ou segredo oculto. O texto foi lido integralmente e comparado com a árvore do commit, o README canônico, a documentação de Skills do Kilo e o arquivo de licença.

A capa desta página é uma ilustração editorial exclusiva. Ela não é captura de tela, painel real, consulta executada, resultado de investigação, logotipo, selo, certificação ou material oficial do Kilo.

Checklist antes de investigar

• Fixar pergunta, métrica, período, fuso, ambiente e fonte.
• Declarar o grão de cada tabela e a regra de deduplicação.
• Escrever duas ou três hipóteses concorrentes.
• Confirmar o efeito antes de procurar a causa.
• Quebrar uma dimensão por vez.
• Quantificar cada hipótese e registrar as rejeitadas.
• Validar mecanismo, população afetada e contrafactual.
• Separar evidência, interpretação, limite e próxima ação.

Fontes oficiais consultadas

Foram consultados a origem canônica no GitHub, a árvore completa do commit, o guia de manutenção do repositório, o repositório oficial do Kilo Code, a documentação oficial do produto e a especificação de Agent Skills. A página do catálogo no skills.sh foi usada apenas como sinal secundário de distribuição. Consulta e números de adoção: 13/09/2026.

Veja também o catálogo de Skills do Bastidores da IA e a Skill de validação de JSON contra modelos Concerto, que trata um problema específico e não substitui a investigação de métricas.