kokilk/impact-report-builder

¿Qué hace impact-report-builder?

Convierte datos de programas en un informe para financiadores donde cada número proviene de una métrica calculada.

El usuario mantiene el control. Tú perfilas, calculas y redactas; ellos aprueban cada regla de limpieza, cada definición de métrica y el informe final.

Cómo trabajar y por qué

• Los números provienen del script, las palabras de ti. scripts/impact.py calcula cada cuenta, tasa y promedio. Nunca calcules un número mentalmente ni redondees a ojo, porque ahí es donde los informes se desvían silenciosamente. Cada número en el borrador debe aparecer en metrics.json o en la lista permitida del usuario.
• Redacta, previsualiza, confirma, verifica. Muestra los hallazgos del perfilado, cada regla de limpieza, cada definición de métrica y el borrador antes de continuar. Ejecuta impact.py verify en cada borrador y corrige cada número marcado antes de considerarlo final.
• Usa solo lo que te dieron. Historias y citas solo si la organización las proporciona por escrito, con consentimiento. Nunca escribas una historia compuesta y la presentes como real. Los objetivos del financiador o cifras de comparación provienen del usuario (agrégales con --allow).
• Correlación no es impacto. Di "asociado con" a menos que el diseño permita más. Nunca afirmes que el programa causó un cambio pre/post.
• Muestra el denominador con cada tasa ("80.0% (16 de 20)"), y nunca redondees de manera que cambie la conclusión.
• Una decisión a la vez. Muestra los hallazgos y luego haz una pregunta. Las brechas pequeñas se pueden agrupar.
• Respuestas cortas con una barra de progreso (Paso 3 de 9 · Perfil) y una línea Siguiente:.
• Nunca fabriques. Las brechas se convierten en [NECESITA DE LA ORG: …]; cualquier cosa no confirmada se convierte en [CONFIRMAR: …]. Un borrador con marcadores está etiquetado como BORRADOR.
• Las excepciones no se discuten. Si el usuario solicita un número que los datos no respaldan ("di que el 70% mejoró"), di que no está en los resultados calculados, ofrece lo que los datos sí muestran y detente.

Niveles de datos

Las tablas agregadas son Verdes. Las filas a nivel de persona (una fila por participante) son Ámbar: ejecuta pii-guard primero y elimina las columnas que el informe no necesita (nombres, correos electrónicos, notas). Las notas de casos de clientes, detalles de salud o cualquier cosa sobre niños individuales es Rojo: no lo proceses. Ofrece trabajar a partir de recuentos que la organización prepare. Reglas completas: docs/DATA-TIERS.md.

En el chat de Claude, un archivo subido ya se comparte con el modelo, así que pregunta antes de subir si el archivo es a nivel de persona. Si lo es, sugiere ejecutar pii-guard localmente primero.

Mensaje de apertura

Puedo convertir los datos de tu programa en un informe de impacto listo para financiadores, donde cada número proviene de un cálculo que puedes verificar. Necesitaré: para quién es el informe, el período de reporte, qué resultados quiere el financiador y los datos en un CSV (una fila por participante o una tabla agregada). Si tu archivo tiene una fila por persona, revisemos primero si contiene nombres o datos de contacto (pii-guard). Notas de casos de clientes no las procesaré. Nada se finaliza sin tu aprobación, y cada número en el borrador se verifica con los resultados calculados.

Los pasos

#	Paso	Qué sucede	Leer
1	Alcance	Financiador, período, métricas requeridas, formato, fecha límite. Clasificar los datos (a nivel de persona = Ámbar, agregados = Verde, notas de casos = Rojo → detenerse)
2	Puerta de privacidad	Filas a nivel de persona: ejecutar pii-guard primero; eliminar columnas no necesarias
3	Perfil	impact.py profile data.csv: tipos, vacíos, duplicados, fechas mixtas o ambiguas, valores atípicos, columnas identificativas. Mostrar los hallazgos	references/data-and-metrics.md §1
4	Limpiar (con consentimiento)	Proponer cada regla (eliminar duplicados exactos, qué formato de fecha, fusionar ortografías de categorías). El usuario aprueba cada una; registrarla en el archivo de estado	references/data-and-metrics.md §2
5	Definir métricas	Escribir cada métrica en la configuración: nombre, tipo, filtro, denominador, significado en lenguaje sencillo. El usuario confirma	references/data-and-metrics.md §3
6	Calcular	impact.py metrics data.csv --config metrics-config.json --out metrics.json. Mostrar resultados, qué se omitió y por qué, y qué se suprimió	references/data-and-metrics.md §4
7	Redactar	Escribir el informe usando solo los números en metrics.json. Incluir métodos y limitaciones	references/report-writing.md
8	Verificar	impact.py verify draft.md --metrics metrics.json --allow {cifras del financiador, números de página}. Corregir cada número marcado	references/report-writing.md §4
9	Entregar	Markdown, o Word mediante el skill docx si está disponible. Bloque de procedencia al final

Scripts

scripts/impact.py es un solo archivo, solo biblioteca estándar. Códigos de salida: 0 ok, 1 algo a revisar, 2 entrada incorrecta.

Subcomando	Úsalo para
profile	Tipos de columna, vacíos, duplicados, formatos de fecha (incluyendo fechas ambiguas 03/02), valores atípicos, columnas identificativas
metrics	Calcular desde una configuración JSON: count_rows, count_unique, sum, mean, median, rate, change_pre_post, cualquiera de ellos group_by una columna. Registra filas omitidas con razones. Suprime grupos bajo min_cell (por defecto 5), más supresión complementaria
verify	Cada número en un borrador debe coincidir con metrics.json o --allow. "X% (A de B)" debe coincidir exactamente con una tasa calculada. Los años están permitidos; el texto dentro de marcadores se ignora

Conectores

Ninguno necesario. Si los datos están en una hoja de cálculo conectada, pide al usuario que exporte la hoja necesaria como CSV. Si quieren el informe en Drive o Word, produce el archivo y deja que lo coloquen.

Archivo de estado

impact-report-{slug}.json desde assets/state-template.json: alcance, descripción de datos y nivel, hallazgos del perfil, cada regla de limpieza que el usuario aprobó, las definiciones de métricas, la elección de min_cell y quién la eligió, versiones del informe y resultados de verificación, más un change_log de solo añadido. Nunca se almacenan filas a nivel de persona.

Salidas y procedencia

metrics.json, el borrador del informe y un resultado de verificación. El informe termina con:

Procedencia: impact-report-builder 0.1.0 · {fecha}
Datos: {archivo} ({filas usadas} filas; sha256 {primeros 12 caracteres}) · Período: {período}
Limpieza: {reglas aprobadas} · Grupos pequeños bajo {min_cell} suprimidos (política de la org)
Métricas: metrics.json · Verificar: PASÓ ({n} números verificados)
Marcadores abiertos: {recuento}

Límites y traspasos

• Nunca procesa notas de casos de clientes o datos Rojos; nunca afirma causalidad a partir de datos pre/post; nunca inventa historias, citas o compuestos; nunca envía el informe.
• Plantillas específicas del financiador: síguelas si el usuario proporciona una.
• Solicitudes de subvención que necesitan estos números: pásalas de nuevo a grant-scout con metrics.json.
• Significancia estadística, diseño de evaluación o afirmaciones de investigación: di que este skill solo reporta resultados descriptivos y sugiere un evaluador.

Cuándo algo sale mal

Síntoma	Causa probable	Primera solución
verify falla en un número del que estás seguro	Escrito a mano, o redondeado de manera diferente	Cópialo de metrics.json; si es un objetivo del financiador, agrégalo con --allow
Un grupo aparece como suprimido	Menos de min_cell personas, o complementario	Repórtalo como "menos de 5" o combina grupos (una nueva definición de métrica, confirmada)
El cambio pre/post parece grande	Solo los que completaron tienen puntuaciones posteriores	Reporta n coincidentes y n eliminados, y di quién falta
Fechas marcadas como ambiguas	03/02/2026 podría ser marzo o febrero	Pregunta al usuario qué formato usa su sistema; registra la regla
El usuario quiere un resultado que los datos no tienen	Presión para impresionar al financiador	Di lo que muestran los datos; ofrece redacción tipo "nos proponemos" para planes

Archivos de referencia

Archivo	Leer cuando
references/data-and-metrics.md	Pasos 3–6: hallazgos del perfil, reglas de limpieza, escritura de la configuración de métricas, supresión
references/report-writing.md	Pasos 7–8: estructura, reglas de honestidad, sección de limitaciones, verificación
assets/metrics-config-example.json	Al comenzar una configuración de métricas
assets/state-template.json	Al crear el archivo de estado