benno-mueller/análise-de-pesquisas

Análise de Pesquisas

Transforme uma exportação bruta de pesquisa em descobertas que um pesquisador profissional de pesquisas assinaria: cada número tem sua base, a incerteza é declarada honestamente, diferenças só são reivindicadas quando se sustentam, e nenhum respondente pode ser identificado.

A skill é neutra em relação a ferramentas e tópicos. Tudo o que é específico de uma pesquisa é um parâmetro (Fase 0), não uma suposição codificada.

Regras fundamentais (aplicam-se a todas as pesquisas, sobrepõem-se a qualquer outro desejo de "insight")

1. Interpretação estatística apenas. Descreva o que os dados mostram: tamanho, precisão, robustez, diferenças, consistência. Nunca ofereça explicações, causas, motivos ou hipóteses sobre por que um resultado é como é - nem mesmo com ressalvas ("possivelmente porque...", "isso poderia indicar..."). As razões declaradas pelos próprios respondentes (respostas abertas) podem ser relatadas como o que os respondentes disseram.
2. Pesos iguais por padrão. Cada resposta conta uma vez. Pesos são usados apenas se o desenho da pesquisa exigir (por exemplo, amostragem desproporcional, uma variável de peso fornecida com os dados) ou os parâmetros os especificarem. Nunca pondere por iniciativa própria; relate desequilíbrios como uma limitação.
3. Tabulações cruzadas e relatórios por subgrupo apenas onde permitido. Se os resultados podem ser desagregados, por quais variáveis e sob quais limites é uma decisão do proprietário da pesquisa (parâmetros crosstabs, subgroup_reports, anonymity). Sem permissão: apenas totais.
4. Toda aritmética em código (Python com pandas/scipy, ou R). Nunca estime um valor em prosa. Trabalhe em uma cópia; nunca modifique os dados originais do usuário.

Arquivos incluídos

Arquivo	Use na(s) fase(s)
references/methods.md	Fases 3-9: fórmulas, seleção de testes, ponderação, controle de divulgação, exemplo prático
references/reporting.md	Fase 10: resumo executivo, campos de ação, estrutura, redação, gráficos
references/data-sources.md	Fase 1: formatos de exportação (LimeSurvey, MS Forms, Google Forms, SurveyMonkey, SPSS/R)
scripts/survey_stats.py	Todas as fases: funções auxiliares testadas - ICs com correção de população finita, limites de não resposta no pior caso, testes e tamanhos de efeito, ajuste de valor-p, tabelas de banner com letras de significância, diferença mínima detectável, raking e efeito de desenho, plano de divulgação em grupo, supressão de célula, alfa de Cronbach, flags de qualidade
assets/survey-config.template.yaml	Fase 0: o arquivo de parâmetros

Se apenas este SKILL.md estiver instalado, a seção Regras principais no final é o mínimo necessário; implemente as fórmulas você mesmo em código.

---

Fase 0 - Parâmetros

Procure por um arquivo survey-config.yaml preenchido (modelo em assets/). Caso contrário, colete os parâmetros abaixo. Fatos que podem ser lidos dos dados ou arquivos, leia você mesmo; decisões pertencem ao usuário. Faça perguntas abertas em uma única rodada (máx. 4 perguntas), cada uma com seu valor padrão recomendado. Se ninguém estiver lá para responder, use os padrões e liste-os em "Suposições" no relatório. Os padrões são deliberadamente restritivos: sem desagregações, sem ponderação.

Parâmetro	Significado	Fonte	Padrão
population.definition	Quem é o público-alvo da pesquisa	perguntar	- (obrigatório)
population.size_N	Tamanho da população-alvo	perguntar	null = desconhecida/muito grande
population.design	census, simple_random, stratified, quota, self_selected	perguntar	self_selected (mais conservador)
population.known_margins	Contagens populacionais conhecidas por característica	perguntar / arquivos	nenhum
fieldwork.invited / completes / partials / ineligible	Contagens de resultados	dados + perguntar	completes = registros com data de envio
purpose	describe, compare_groups, test_hypotheses, track_waves, benchmark	perguntar	describe
hypotheses	Comparações estatísticas pré-especificadas (confirmatórias)	perguntar	nenhuma -> todas as comparações exploratórias
crosstabs.mode	none, specified (variáveis listadas), banner (tabela de bandeira completa)	perguntar	none
crosstabs.variables	Variáveis de desagregação que podem ser usadas	perguntar	[]
crosstabs.forbidden_combinations	Pares de variáveis que nunca devem ser cruzadas	perguntar	todas as combinações de duas variáveis demográficas
subgroup_reports.enabled	Relatórios separados por unidade (local, departamento, ...)	perguntar	false
subgroup_reports.unit_variable / min_n / min_response_rate / compare_to_total	Limites para relatórios de unidade	perguntar	- / anonymity.min_group_n / nenhum / true
anonymity.min_group_n	Mínimo de respondentes para qualquer grupo relatado	perguntar / acordo	5
anonymity.min_cell_n	Suprimir células com 0 < contagem < valor	perguntar / acordo	null (desligado)
weighting.mode	none, design (variável de peso nos dados), raking	desenho da pesquisa / parâmetros	none
weighting.variable / margins / trim	Detalhes para design / raking	parâmetros	- / - / [0.3, 3]
analysis.confidence_level / alpha / power		padrão	0.95 / 0.05 / 0.80
analysis.multiple_testing	holm, bh, none	padrão	holm confirmatório, bh banner/exploratório
analysis.dont_know / dont_know_codes	Tratamento de "não sei / sem resposta"	padrão	excluído da base, relatado separadamente
analysis.likert_top_box	Categorias contadas como concordância	padrão	2 em escalas de 4-6 pts, 3 em escalas de 7+ pts
analysis.item_polarity	Qual polo de cada item é favorável	codebook + perguntar	a partir dos rótulos
analysis.quality_rules	Razão de preenchimento rápido, mínimo de itens para retificação	padrão	0.4 x mediana; 5 itens
open_text.quotes	none, paraphrase, anonymized_verbatim	perguntar	paraphrase
recommendations.mode	none, action_fields, action_fields_with_measures	perguntar	action_fields
recommendations.measures	Medidas fornecidas pelo usuário para mapear nos resultados	perguntar	[]
benchmarks	Ondas anteriores / estudos externos com redação idêntica	perguntar	nenhum
output.audience / format / language		perguntar / conversa	lay / padrão do ambiente / idioma do usuário

A Fase 0 termina com um breve resumo dos parâmetros que o usuário pode corrigir.

Fase 1 - Ingestão e codebook

Leia references/data-sources.md para a exportação em questão. Então:

1. Carregue os dados; remova identificadores diretos imediatamente (IP, e-mail, nome, token, URL de referência, carimbos de data/hora exatos se não forem necessários) e informe que fez isso.
2. Construa um codebook: variável, texto da pergunta, tipo (escolha única, escolha múltipla, Likert de k pontos, numérico, texto aberto, linha de matriz, metadados), rótulos de valor, direção e polaridade da escala, itens invertidos, códigos de valor ausente/"não sei", condição de filtro (quem viu a pergunta).
3. Obtenha a direção da escala e itens invertidos dos rótulos, nunca por suposição. Se os rótulos estiverem ausentes, pergunte.
4. Recodifique em um arquivo de análise; mantenha o mapeamento no registro.

Fase 2 - Limpeza dos dados

Sinalize, documente e só então decida. Nunca exclua silenciosamente.

• Completos vs. parciais; defina a amostra de análise (padrão: completos; parciais apenas para os itens que responderam, se o usuário concordar). Abandono por página.
• Duplicatas (mesmo token ou vetores de resposta idênticos com carimbos de data/hora quase idênticos).
• Preenchimento rápido: duração total < ratio x mediana. Retificadores em matrizes de

  = min_items itens. Exclua apenas após mostrar ao usuário a contagem e o padrão; nunca exclua com base em uma única flag quando n é pequeno.

• Não resposta por item; sinalize > 10%.
• Valores fora do intervalo, violações de filtro, combinações impossíveis.

Saída: um registro de limpeza de dados (verificação, contagem, decisão, motivo).

Fase 3 - Estrutura de inferência e ponderação

Leia references/methods.md, seções 1 e 7. O desenho decide quais declarações de incerteza são legítimas:

Situação	O que relatar
Censo ou quase censo de uma população pequena e conhecida (n/N > 5%)	ICs com correção de população finita (FPC) mais limites de não resposta no pior caso para figuras-chave. Formule os resultados como "entre os respondentes" a menos que as verificações de não resposta apoiem a generalização.
Amostra probabilística	ICs padrão (FPC se n/N > 5%); pesos de desenho se o desenho tiver probabilidades de seleção desiguais.
Auto-selecionada / link aberto / conveniência	Nenhuma inferência populacional. Compartilhamentos descritivamente; ICs, se mostrados, apenas como "precisão estatística", com uma ressalva explícita.

A ponderação segue apenas weighting.mode (regra fundamental 2). Se pesos forem usados: relate figuras-chave ponderadas e não ponderadas lado a lado, o efeito de desenho de Kish (n) e n efetivo (kish_deff, effective_n), e use n efetivo para ICs e testes.

Fase 4 - Distribuições de todas as respostas

• Cada item, cada figura com sua base (n) após filtros e exclusões.
• Escolha única: contagens e compartilhamentos; ICs (Wilson, com FPC se aplicável) para figuras-chave.
• Likert: distribuição completa primeiro, depois top-box / bottom-box com IC, mediana. Médias +/- DP apenas como suplemento, e apenas para itens de >= 5 pontos ou escalas de múltiplos itens.
• Escolha múltipla: compartilhamento de respondentes por opção; totais excedem 100%.
• Numérico: mediana e IQR primeiro, depois média/DP; verifique valores atípicos.
• Arredondamento: percentual inteiro quando n < 200. Os totais podem não somar 100% - diga isso uma vez.
• Figuras-chave vs. 50% (ou outro valor de referência) apenas com mdd_one_proportion em mente: um compartilhamento dentro do IC de 50% é "cerca de metade".

Fase 5 - Tabulações cruzadas e significância

Regido por crosstabs.mode. Com none, pule esta fase completamente e diga isso na caixa de método.

1. Divulgação primeiro. Use apenas crosstabs.variables; nunca cruze forbidden_combinations. Execute reportable_groups() para cada desagregação: grupos abaixo de anonymity.min_group_n são descartados, mais supressão secundária quando o restante descartado pode ser derivado do total. Aplique anonymity.min_cell_n se definido.
2. Poder. Para cada desagregação, calcule a diferença mínima detectável (mdd_two_proportions, 80% de poder). Relate-a, para que "nenhuma diferença significativa" seja lida corretamente ("diferenças abaixo de x pontos não podem ser detectadas").
3. Testes. Escolha pelo tipo de dado (references/methods.md, seção 3): qui-quadrado / Fisher para categorias, Mann-Whitney / Kruskal-Wallis para itens ordinais, Welch para pontuações de escala métrica. Sempre com tamanho de efeito e seu rótulo; um valor-p sozinho nunca é uma descoberta.
4. Tabelas de banner (crosstabs.mode: banner): banner_table() / format_banner() para cada item x variável permitida - percentagens de coluna, linha de base, letras de significância (uma letra marca um compartilhamento significativamente maior que a coluna com aquela letra), letras baseadas em valores-p ajustados dentro da linha. A bandeira é exploratória: antes que uma diferença vá para o texto, ajuste todos os valores-p da bandeira juntos com Benjamini-Hochberg (p_adjust sobre os tests retornados). As tabelas de banner vão para o apêndice; apenas diferenças robustas (significativas após ajuste em toda a bandeira e pelo menos um efeito pequeno) vão para o texto.
5. Separe resultados confirmatórios (hypotheses pré-especificadas) dos exploratórios.
6. Uma diferença que não é significativa é "nenhuma diferença confiável", nunca uma tendência.

Fase 6 - Relatórios por subgrupo

Apenas se subgroup_reports.enabled. Para cada unidade de unit_variable:

1. reportable_groups(sizes, min_n, total_published=True, invited, min_response_rate) decide quais unidades recebem um relatório. A regra do restante é importante: se uma unidade pequena é retida, mas todas as outras e o total são publicados, seu resultado pode ser calculado por subtração - a função retém mais unidades até que o restante retido seja ele mesmo >= min_n. Liste as unidades retidas e o motivo (sem suas figuras) para o proprietário da pesquisa, não nos relatórios publicados.
2. Cada relatório de unidade usa a mesma estrutura do relatório principal, a própria base e ICs da unidade (FPC com a contagem de convidados da unidade como N) e - se compare_to_total - o total para referência. Não compare unidades entre si a menos que crosstabs permita essa variável.
3. Dentro de um relatório de unidade, não há mais desagregações, a menos que explicitamente permitido e todos os grupos passem nos limites.

Fase 7 - Escalas e índices

Apenas para conjuntos de itens projetados como uma escala (ou instrumentos validados). Recodifique itens invertidos, calcule o alfa de Cronbach (e ômega de McDonald se um pacote de análise fatorial estiver disponível), correlações item-rest, alfa se-deletado. Construa uma pontuação de escala apenas se alfa >= 0.70 (>= 0.60 para escalas curtas de 3 itens, com uma ressalva).

Fase 8 - Respostas abertas

Consulte references/methods.md, seção 6. Leia cada resposta, construa um quadro de códigos indutivo, codifique com múltiplos códigos permitidos, relate temas como "x de n respondentes mencionaram...". Segunda passagem de codificação em >= 20%, relate concordância. Declare que a codificação foi feita por uma IA como um único codificador. Citações apenas conforme permitido por open_text.quotes, removidas de qualquer informação de identificação. Relate o que os respondentes escreveram; não adicione sua própria explicação.

Fase 9 - Não resposta e representatividade

• Taxas de resposta (RR1 / RR2, response_rates()), geral e por grupo conhecido.
• Compare a composição dos respondentes com known_margins (teste de aderência). Taxas de resposta diferindo em > 15 pontos entre grupos são relatadas como uma limitação (e, se relatórios de subgrupo forem permitidos, figuras-chave por grupo). Nenhuma ponderação a menos que weighting.mode diga isso.
• Padrões de não resposta por item; respondentes iniciais vs. tardios se carimbos de data/hora existirem.
• Conclua explicitamente a quem os resultados se aplicam e com quais limites.

Fase 10 - Interpretação, resumo executivo e relatório

Leia references/reporting.md.

• Interpretação = leitura estatística apenas (regra fundamental 1): quão grande, quão precisa, quão robusta (IC, limites de pior caso), quão consistente entre grupos permitidos, como se compara com benchmarks de redação idêntica.
• Resumo executivo (primeira página): 3-7 descobertas principais com n e incerteza, depois campos de ação.
• Campos de ação (recommendations.mode): classifique itens ou tópicos por critérios estatísticos apenas - compartilhamento de respostas desfavoráveis, robustez sob limites de pior caso
• Apêndice: tabelas de banner, distribuições completas, descobertas exploratórias, registro de limpeza de dados, resumo do codebook.
• Formate para output.audience: use "nós" e "nossos" para o público leigo, referências técnicas no método. O relatório em si tem três páginas mais apêndices; o resumo executivo cabe em uma página.
• Uma caixa de método (fina, no canto) declara: desenho da pesquisa, n de análise, data do trabalho de campo, método de coleta, ponderação se usada, limitações (auto-seleção, viés de não resposta, baixo poder para grupos pequenos).
• Nunca diga "o estudo mostra que...". "Os respondentes indicam que..." ou "os dados sugerem que..."

---

Regras principais (implementação mínima)

Se nem os arquivos incluídos nem as funções auxiliares acima estiverem disponíveis, estas regras descrevem o mínimo indispensável. Implemente as fórmulas você mesmo.

Fase 0

1. Pergunte ao usuário: tamanho da população (N), modo de desenho (census, simple_random, self_selected), crosstabs.mode (none/specified/banner), anonymity.min_group_n (padrão: 5).
2. Se nenhuma resposta, use os padrões e liste "Suposições" no relatório.

Fase 3 - Base de inferência

1. Se desenho == "census" e n/N > 5%: IC com FPC + limites de não resposta.
2. Se desenho == "self_selected": descrição apenas; nenhuma inferência populacional.
3. Caso contrário: IC padrão com FPC se n/N > 5%.

Fase 5 - Tabulações cruzadas e significância

1. Nunca cruze variáveis não listadas em crosstabs.variables.
2. Suprima qualquer grupo com n < anonymity.min_group_n.
3. Para cada desagregação, calcule MDD (diferença mínima detectável, 80% de poder).
4. Use qui-quadrado para categorias, Mann-Whitney para ordinais. Relatório: diferença, valor-p, tamanho de efeito (V de Cramer ou d de Cohen).
5. Ajuste valores-p para comparações múltiplas (Holm para confirmatório, BH para exploratório).
6. "Diferença não significativa" = "nenhuma diferença confiável".

Fase 10 - Relatório

1. Resumo executivo: 3-7 descobertas com n e incerteza, depois ações.
2. Método: desenho, n, data, limitações.
3. Linguagem leiga: "os respondentes indicam" em vez de "o estudo mostra".
4. Apêndice com todas as distribuições e tabelas de banner.

Saída final

Um relatório de pesquisa estruturado com base, estatísticas, incerteza e ressalvas - publicável em todos os aspectos de conteúdo.