beno-mueller/encuesta-analisis

Análisis de Encuestas

Convierte una exportación de encuesta en bruto en hallazgos que un investigador profesional de encuestas firmaría: cada número tiene su base, la incertidumbre se declara honestamente, las diferencias solo se reclaman cuando se sostienen, y ningún encuestado puede ser identificado.

La habilidad es independiente de herramientas y temas. Todo lo específico de una encuesta es un parámetro (Fase 0), no una suposición codificada.

Reglas fundamentales (aplican a cada encuesta, anulan cualquier otro deseo de "conocimiento")

1. Solo interpretación estadística. Describe lo que muestran los datos: tamaño, precisión, robustez, diferencias, consistencia. Nunca ofrezcas explicaciones, causas, motivos o hipótesis sobre por qué un resultado es como es — ni siquiera matizadas ("posiblemente porque...", "esto podría indicar..."). Las razones declaradas por los propios encuestados (respuestas abiertas) pueden informarse como lo que los encuestados dijeron.
2. Pesos iguales por defecto. Cada respuesta cuenta una vez. Los pesos se usan solo si el diseño de la encuesta lo requiere (por ejemplo, muestreo desproporcionado, una variable de peso entregada con los datos) o los parámetros lo especifican. Nunca ponderes por iniciativa propia; en su lugar, informa los desequilibrios como una limitación.
3. Tablas cruzadas e informes de subgrupos solo donde esté permitido. Si los resultados pueden desglosarse, por qué variables y bajo qué límites es una decisión del propietario de la encuesta (parámetros crosstabs, subgroup_reports, anonymity). Sin permiso: solo totales.
4. Toda la aritmética en código (Python con pandas/scipy, o R). Nunca estimes una cifra en prosa. Trabaja sobre una copia; nunca modifiques los datos originales del usuario.

Archivos incluidos

Archivo	Úsalo en
references/methods.md	Fases 3-9: fórmulas, selección de pruebas, ponderación, control de divulgación, ejemplo práctico
references/reporting.md	Fase 10: resumen ejecutivo, campos de acción, estructura, redacción, gráficos
references/data-sources.md	Fase 1: formatos de exportación (LimeSurvey, MS Forms, Google Forms, SurveyMonkey, SPSS/R)
scripts/survey_stats.py	Todas las fases: ayudantes probados: IC con corrección por población finita, límites de no respuesta en el peor caso, pruebas y tamaños del efecto, ajuste de valor p, tablas con letras de significancia, diferencia mínima detectable, raking y efecto de diseño, plan de divulgación de grupos, supresión de celdas, alfa de Cronbach, indicadores de calidad
assets/survey-config.template.yaml	Fase 0: el archivo de parámetros

Si solo está instalado este SKILL.md, la sección Reglas principales al final es el mínimo que necesitas; implementa las fórmulas tú mismo en código.

---

Fase 0 - Parámetros

Busca un archivo survey-config.yaml completo (plantilla en assets/). De lo contrario, recopila los parámetros a continuación. Los hechos que se pueden leer de los datos o archivos, léelos tú mismo; las decisiones pertenecen al usuario. Haz preguntas abiertas en una sola ronda (máx. 4 preguntas), cada una con tu valor predeterminado recomendado. Si no hay nadie para responder, usa los valores predeterminados y enuméralos bajo "Supuestos" en el informe. Los valores predeterminados son deliberadamente restrictivos: sin desgloses, sin ponderación.

Parámetro	Significado	Fuente	Valor predeterminado
population.definition	A quién se dirige la encuesta	preguntar	- (obligatorio)
population.size_N	Tamaño de la población objetivo	preguntar	null = desconocida/muy grande
population.design	census, simple_random, stratified, quota, self_selected	preguntar	self_selected (el más conservador)
population.known_margins	Conteos de población conocidos por característica	preguntar/archivos	ninguno
fieldwork.invited / completes / partials / ineligible	Conteos de resultados	datos + preguntar	completes = registros con fecha de envío
purpose	describe, compare_groups, test_hypotheses, track_waves, benchmark	preguntar	describe
hypotheses	Comparaciones estadísticas preespecificadas (confirmatorias)	preguntar	ninguna -> todas las comparaciones exploratorias
crosstabs.mode	none, specified (variables listadas), banner (tabla completa)	preguntar	none
crosstabs.variables	Variables de desglose que pueden usarse	preguntar	[]
crosstabs.forbidden_combinations	Pares de variables que nunca deben cruzarse	preguntar	todas las combinaciones de dos variables demográficas
subgroup_reports.enabled	Informes separados por unidad (sitio, departamento, ...)	preguntar	false
subgroup_reports.unit_variable / min_n / min_response_rate / compare_to_total	Límites para informes de unidad	preguntar	- / anonymity.min_group_n / ninguno / true
anonymity.min_group_n	Mínimo de encuestados para cualquier grupo reportado	preguntar/acuerdo	5
anonymity.min_cell_n	Suprimir celdas con 0 < conteo < valor	preguntar/acuerdo	null (desactivado)
weighting.mode	none, design (variable de peso en datos), raking	diseño de encuesta/parámetros	none
weighting.variable / margins / trim	Detalles para design / raking	parámetros	- / - / [0.3, 3]
analysis.confidence_level / alpha / power		valor predeterminado	0.95 / 0.05 / 0.80
analysis.multiple_testing	holm, bh, none	valor predeterminado	holm confirmatorio, bh banner/exploratorio
analysis.dont_know / dont_know_codes	Tratamiento de "no sabe / no contesta"	valor predeterminado	excluido de la base, reportado por separado
analysis.likert_top_box	Categorías contadas como acuerdo	valor predeterminado	2 en escalas de 4-6 pt, 3 en escalas de 7+ pt
analysis.item_polarity	Qué polo de cada ítem es favorable	libro de códigos + preguntar	de las etiquetas
analysis.quality_rules	Ratio de velocidad, mínimo de ítems para respuesta en línea recta	valor predeterminado	0.4 x mediana; 5 ítems
open_text.quotes	none, paraphrase, anonymized_verbatim	preguntar	paraphrase
recommendations.mode	none, action_fields, action_fields_with_measures	preguntar	action_fields
recommendations.measures	Medidas proporcionadas por el usuario para asignar a los hallazgos	preguntar	[]
benchmarks	Olas anteriores / estudios externos con redacción idéntica	preguntar	ninguno
output.audience / format / language		preguntar/conversación	lay / valor predeterminado del entorno / idioma del usuario

La Fase 0 termina con un breve resumen de parámetros que el usuario puede corregir.

Fase 1 - Ingesta y libro de códigos

Lee references/data-sources.md para la exportación en cuestión. Luego:

1. Carga los datos; elimina los identificadores directos inmediatamente (IP, correo electrónico, nombre, token, URL de referencia, marcas de tiempo exactas si no son necesarias) y di que lo hiciste.
2. Construye un libro de códigos: variable, texto de la pregunta, tipo (opción única, opción múltiple, Likert k-puntos, numérico, texto abierto, fila de matriz, metadatos), etiquetas de valores, dirección de la escala y polaridad, ítems invertidos, códigos de valores perdidos/"no sabe", condición de filtro (a quién se mostró la pregunta).
3. Toma la dirección de la escala y los ítems invertidos de las etiquetas, nunca de suposiciones. Si faltan etiquetas, pregunta.
4. Recodifica en un archivo de análisis; mantén la asignación en el registro.

Fase 2 - Limpieza de datos

Señala, documenta y solo entonces decide. Nunca elimines en silencio.

• Completos vs. parciales; define la muestra de análisis (predeterminado: completos; parciales solo para los ítems que respondieron, si el usuario está de acuerdo). Abandono por página.
• Duplicados (mismo token, o vectores de respuesta idénticos con marcas de tiempo casi idénticas).
• Velocistas: duración total < ratio x mediana. Respondedores en línea recta en matrices de

  = min_items ítems. Excluye solo después de mostrar al usuario el conteo y el patrón; nunca excluyas con una sola bandera cuando n es pequeño.

• No respuesta de ítem por ítem; señala > 10 %.
• Valores fuera de rango, violaciones de filtro, combinaciones imposibles.

Salida: un registro de limpieza de datos (verificación, conteo, decisión, razón).

Fase 3 - Marco de inferencia y ponderación

Lee references/methods.md, secciones 1 y 7. El diseño decide qué afirmaciones de incertidumbre son legítimas:

Situación	Qué informar
Censo o casi censo de una población pequeña y conocida (n/N > 5 %)	IC con corrección por población finita (FPC) más límites de no respuesta en el peor caso para cifras clave. Formula los resultados como "entre los encuestados" a menos que las verificaciones de no respuesta respalden la generalización.
Muestra probabilística	IC estándar (FPC si n/N > 5 %); pesos de diseño si el diseño tiene probabilidades de selección desiguales.
Autoseleccionado / enlace abierto / conveniencia	Sin inferencia poblacional. Compartidos descriptivamente; los IC, si se muestran, solo como "precisión estadística", con una advertencia explícita.

La ponderación sigue solo weighting.mode (regla fundamental 2). Si se usan pesos: informa las cifras clave ponderadas y no ponderadas una al lado de la otra, el efecto de diseño Kish y la n efectiva (kish_deff, effective_n), y usa la n efectiva para los IC y las pruebas.

Fase 4 - Distribuciones de todas las respuestas

• Cada ítem, cada figura con su base (n) después de filtros y exclusiones.
• Opción única: conteos y proporciones; IC (Wilson, con FPC si corresponde) para cifras clave.
• Likert: distribución completa primero, luego top-box / bottom-box con IC, mediana. Media +/- DE solo como suplemento, y solo para ítems de >= 5 puntos o escalas de múltiples ítems.
• Opción múltiple: proporción de encuestados por opción; los totales superan el 100 %.
• Numérico: mediana y RIC primero, luego media/DE; verifica valores atípicos.
• Redondeo: porcentaje entero cuando n < 200. Los totales pueden no sumar el 100 % - dilo una vez.
• Cifras clave vs. 50 % (u otro valor de referencia) solo teniendo en cuenta mdd_one_proportion: una proporción dentro del IC del 50 % es "aproximadamente la mitad".

Fase 5 - Tablas cruzadas y significancia

Regido por crosstabs.mode. Con none, salta esta fase por completo y dilo en el cuadro de método.

1. Divulgación primero. Usa solo crosstabs.variables; nunca cruces forbidden_combinations. Ejecuta reportable_groups() para cada desglose: los grupos por debajo de anonymity.min_group_n se eliminan, más supresión secundaria cuando el resto eliminado podría derivarse del total. Aplica anonymity.min_cell_n si está configurado.
2. Potencia. Para cada desglose, calcula la diferencia mínima detectable (mdd_two_proportions, potencia del 80 %). Infórmala, para que "sin diferencia significativa" se lea correctamente ("las diferencias por debajo de x puntos no pueden detectarse").
3. Pruebas. Elige según el tipo de datos (references/methods.md, sección 3): chi-cuadrado / Fisher para categorías, Mann-Whitney / Kruskal-Wallis para ítems ordinales, Welch para puntuaciones de escala métrica. Siempre con tamaño del efecto y su etiqueta; un valor p por sí solo nunca es un hallazgo.
4. Tablas de banner (crosstabs.mode: banner): banner_table() / format_banner() para cada ítem x variable permitida: porcentajes de columna, fila base, letras de significancia (una letra marca una proporción significativamente más alta que la columna con esa letra), letras basadas en valores p ajustados dentro de la fila. La banda es exploratoria: antes de que una diferencia pase al texto, ajusta todos los valores p de la banda juntos con Benjamini-Hochberg (p_adjust sobre las tests devueltas). Las tablas de banner van al apéndice; solo las diferencias robustas (significativas después del ajuste de toda la banda y al menos un efecto pequeño) van al texto.
5. Separa los resultados confirmatorios (hipótesis hypotheses preespecificadas) de los exploratorios.
6. Una diferencia que no es significativa es "sin diferencia confiable", nunca una tendencia.

Fase 6 - Informes de subgrupos

Solo si subgroup_reports.enabled. Para cada unidad de unit_variable:

1. reportable_groups(sizes, min_n, total_published=True, invited, min_response_rate) decide qué unidades reciben un informe. La regla del resto es importante: si una unidad pequeña se retiene pero todas las demás y el total se publican, su resultado se puede calcular por sustracción — la función retiene más unidades hasta que el resto retenido sea en sí mismo >= min_n. Enumera las unidades retenidas y la razón (sin sus cifras) para el propietario de la encuesta, no en los informes publicados.
2. Cada informe de unidad usa la misma estructura que el informe principal, la base y los IC propios de la unidad (FPC con el conteo de invitados de la unidad como N), y — si compare_to_total — el total como referencia. No compares unidades entre sí a menos que crosstabs lo permita para esa variable.
3. Dentro de un informe de unidad no hay más desgloses, a menos que se permita explícitamente y todos los grupos superen los umbrales.

Fase 7 - Escalas e índices

Solo para conjuntos de ítems diseñados como una escala (o instrumentos validados). Recodifica los ítems invertidos, calcula el alfa de Cronbach (y el omega de McDonald si hay un paquete de factores disponible), correlaciones ítem-resto, alfa si se elimina. Construye una puntuación de escala solo si alfa >= .70 (>= .60 para escalas cortas de 3 ítems, con una advertencia).

Fase 8 - Respuestas abiertas

Ver references/methods.md, sección 6. Lee cada respuesta, construye un marco de código inductivo, codifica con múltiples códigos permitidos, informa los temas como "x de n encuestados mencionaron ...". Segunda pasada de codificación en >= 20 %, informa el acuerdo. Indica que la codificación fue realizada por una IA como un solo codificador. Citas solo según lo permitido por open_text.quotes, eliminando cualquier elemento identificador. Informa lo que los encuestados escribieron; no agregues tu propia explicación.

Fase 9 - No respuesta y representatividad

• Tasas de respuesta (RR1 / RR2, response_rates()), general y por grupo conocido.
• Compara la composición de los encuestados con known_margins (prueba de bondad de ajuste). Las tasas de respuesta que difieren en > 15 puntos entre grupos se informan como una limitación (y, si se permiten informes de subgrupos, cifras clave por grupo). Sin ponderación a menos que weighting.mode lo indique.
• Patrones de no respuesta de ítems; encuestados tempranos vs. tardíos si existen marcas de tiempo.
• Concluye explícitamente a quiénes se aplican los resultados y con qué límites.

Fase 10 - Interpretación, resumen ejecutivo e informe

Lee references/reporting.md.

• Interpretación = solo lectura estadística (regla fundamental 1): qué tan grande, qué tan preciso, qué tan robusto (IC, límites del peor caso), qué tan consistente entre grupos permitidos, cómo se compara con puntos de referencia de redacción idéntica.
• Resumen ejecutivo (primera página): 3-7 hallazgos clave con n e incertidumbre, luego campos de acción.
• Campos de acción (recommendations.mode): clasifica los ítems o temas por criterios estadísticos únicamente: proporción de respuestas desfavorables, robustez bajo límites del peor caso...