ropimen/claude-skill-kpi-calculator

Calculadora de KPI

Convierte uno o más archivos CSV/TSV más una instrucción breve en un conjunto verificado de KPIs, cada uno con valor, unidad, ecuación, significado y etiqueta de base. No hay una lista fija de campos: los KPIs se diseñan para lo que los datos y la instrucción describan. Los documentos, informes o resultados anteriores adjuntos junto a los datos contribuyen con sus KPIs, aplicados a los datos del usuario con su procedencia.

<skill_dir> a continuación significa la carpeta que contiene este archivo. Ejecuta los scripts como python <skill_dir>/scripts/<nombre>.py desde la carpeta de trabajo (ver "Dónde van los resultados"), pasando los archivos de datos por ruta absoluta.

Si no se encuentra python (o abre la Microsoft Store), usa py -3 en Windows o python3 en cualquier otro lugar en todos los comandos siguientes. Compruébalo una vez al principio con python --version.

Reglas estrictas

1. Cada número proviene del código ejecutado sobre los archivos. Nunca estimes, redondees a ojo ni indiques un valor en prosa que no esté en results.json.
2. Los KPIs excluidos nunca se calculan y nunca aparecen en ningún lugar excepto en la línea única "Excluido a su solicitud".
3. Cada suposición se declara en "Lo que entendí" (patrón, roles, unidades, interpolación, zona horaria, orden día/mes, valores predeterminados utilizados).
4. A lo sumo una pregunta por ejecución, y solo cuando una suposición incorrecta cambiaría los resultados (ver references/role-mapping.md, "Cuándo preguntar"). De lo contrario, indica la lectura tomada y continúa.
5. Cada KPI es una especificación en kpi_specs.json construida a partir de primitivas. Cada uno está etiquetado como basis: established (estándar en el campo) o derived (construido desde primeros principios).
6. Los ratios sobre períodos son ratios de sumas, no medias de ratios, a menos que el KPI se defina de otra manera.
7. El tiempo irregular es tiempo real. Nunca cuentes las filas como pasos de tiempo; integra y promedia sobre las marcas de tiempo con la interpolación de cada columna.
8. Los fallos de validación se revisan una vez (notas de análisis → mapeo → especificación), luego se informan con la advertencia, nunca se ocultan.
9. El conocimiento del campo reside solo en Markdown. Nunca agregues lógica específica del campo a los scripts.
10. Los valores de las referencias son citas. Los números informados en documentos o resultados anteriores van solo al reference.reported de una especificación; nunca son entradas para un cálculo y nunca se presentan como el resultado del usuario.

Dónde van los resultados

Decide esto en el paso 1 y regístralo en request.json → output_dir.

Situación	Carpeta de trabajo (todos los archivos JSON, directorio de trabajo de scripts)	Entregables
El usuario nombra una carpeta ("guarda los resultados en D:/reports/line3")	esa carpeta (crearla)	misma carpeta
Aplicaciones Claude (claude.ai / chat de escritorio, existe /mnt/user-data/outputs/)	el directorio actual	copiar en /mnt/user-data/outputs/: aparecen como archivos descargables
Claude Code, sin carpeta nombrada	kpi_output/ en el directorio actual	misma carpeta

Los entregables son report.md, kpi_results.csv, kpi_run.py y, cuando se produzcan, kpi_chart.png, kpi_adhoc.py y un paquete de campo ofrecido. Los archivos de trabajo (request.json, profile.json, mapping.json, kpi_specs.json, results.json) permanecen en la carpeta de trabajo para auditoría y se comparten solo si se solicita.

Entrega los entregables al usuario para que pueda guardarlos en cualquier lugar:

• Aplicaciones Claude: además de los archivos descargables, muestra el informe terminado como un artefacto de documento Markdown, para que pueda leerse, copiarse o descargarse por sí mismo.
• Claude Code: enumera cada entregable como un enlace a su ruta. Cuando el anfitrión ofrezca una herramienta para enviar archivos al usuario (por ejemplo, tarjetas de archivo en la aplicación de escritorio), envía también los entregables a través de ella.
• Nunca escribas fuera de la carpeta de trabajo y la ubicación de los entregables a menos que el usuario lo solicite.

Para volver a ejecutar kpi_run.py más tarde, colócalo en una carpeta junto con los archivos de entrada.

Scripts primero, ad hoc solo como recurso

Ejecuta siempre los scripts a continuación. Escribe tu propio código pandas solo cuando:

• un script termine con un error que no puedas corregir modificando profile.json, mapping.json o las especificaciones (por ejemplo, un archivo profile_csv.py no puede analizar), o
• un KPI necesite una operación que ninguna primitiva o expresión cubra (check_spec.py informe unknown_op).

Entonces:

1. Coloca el código en kpi_adhoc.py en el directorio de trabajo, carga los datos con la configuración de análisis en profile.json (o scripts/lib/io.py load), y mantenlo ejecutable por sí mismo.
2. Agrega cada KPI ad hoc a results.json → kpis con cada campo de schemas/results.schema.json y "computed_by": "ad_hoc", después de que run_specs.py haya escrito el archivo. Nunca cambies valores que el motor haya calculado.
3. El informe marca esos KPIs con † y apunta a kpi_adhoc.py.

Nunca uses eval/exec en cadenas derivadas del usuario o de datos, incluso ad hoc.

Flujo de trabajo

Ejecuta los ocho pasos en orden. Lee un archivo de referencia solo cuando su paso lo necesite.

Paso 1 [Claude] Analizar la solicitud → request.json

Lee references/request-parsing.md. Extrae field, mode, focus, include, exclude, custom, params, max_kpis, output_dir.

• Referencias (documentos, informes, estándares, resultados anteriores) adjuntos o nombrados en el prompt: lee references/reference-documents.md, distínguelos de los archivos de datos, lee cada uno en su totalidad y registra sus KPIs en request.json → references (id, nombre, definición, ecuación, ubicación, valores informados). Solo los archivos de datos van al paso 2.

• Entrada de Excel: convierte cada hoja a su propio CSV primero (pandas.read_excel(sheet_name=None)), nómbralos <libro>__<hoja>.csv.

• Un KPI tanto incluido como excluido → esta es la única pregunta de la ejecución. No calcules nada para ese KPI hasta que se responda.

Paso 2 [script] Cargar y perfilar → profile.json

python <skill_dir>/scripts/profile_csv.py ARCHIVO [ARCHIVO ...] --out profile.json

Revisa el tipo, indicio de unidad y notas de análisis de cada columna. Si una columna que debería ser numérica resulta ser text, mira sus muestras y corrige el análisis antes de continuar.

Paso 3 [script] Detectar tiempo y patrón de colección → profile.json (sección de tiempo)

python <skill_dir>/scripts/detect_time.py --profile profile.json [--tz <tz IANA>] --out profile.json

Lee references/collection-patterns.md. El script propone un patrón con evidence y otros candidates plausibles, más entity_column (cuando las marcas de tiempo se repiten en una columna de agrupación), frequency (alias de pandas como D, B, h, MS), gaps, duplicates y tz. Confirma o anula el patrón y la entidad usando la descripción del usuario. Si ambiguous_dayfirst es verdadero, indica la suposición (o pregunta, si ambas lecturas cambian los valores de KPI y no hay otra pregunta pendiente). Pasa --tz cuando el usuario nombre la zona horaria de las marcas de tiempo locales sin zona.

Paso 4 [Claude] Mapear roles de columnas → mapping.json

Lee references/role-mapping.md. Asigna a cada columna un rol, cantidad física, unidad e interpolación; registra entidad, pares, uniones, remodelación, remuestreo y parámetros. Los encabezados en cualquier idioma se leen por significado; mantén los nombres originales.

Luego escribe mapping.json → sensitivity: una variante por cada juicio que razonablemente podría haber sido de otra manera (interpolación, una clase de estado ambigua, orden día/mes, tiempo de inactividad planificado, una unidad o parámetro asumido). El motor vuelve a ejecutar cada KPI bajo cada variante e informa un rango bajo-alto, para que el usuario vea qué números dependen de qué suposiciones. Las reglas y el formato de parche están en references/role-mapping.md, "Variantes de sensibilidad".

Paso 5 [Claude] Diseñar y seleccionar KPIs → kpi_specs.json

Lee references/kpi-discovery.md (método) y references/kpi-spec.md (formato, primitivas, gramática). Si references/fields/ tiene un paquete que coincida con el campo, léelo también; informa pero nunca limita.

Orden de selección: requeridos (include) y custom primero → KPIs de references (especificación source: reference con un bloque reference, ver references/reference-documents.md) → nunca exclude → por relevancia a focus, establecidos antes que derivados, sin casi duplicados → limita las selecciones propias de Claude a max_kpis (predeterminado 12). Los KPIs requeridos, personalizados y de referencia nunca se eliminan; un KPI de referencia que los datos no puedan soportar no recibe especificación y se enumera bajo "No calculado automáticamente".

Luego verifica las especificaciones:

python <skill_dir>/scripts/check_spec.py --profile profile.json --mapping mapping.json --specs kpi_specs.json \
       --request request.json

Salida 0 = ok. Salida 1 = errores como JSON en stdout: corrige la especificación o el mapeo y vuelve a ejecutar. Las unidades desconocidas vuelven como advertencias: si una cambia los resultados, puede ser la pregunta de la ejecución.

Pasos 6–7 [script] Calcular y validar → results.json, kpi_run.py

python <skill_dir>/scripts/run_specs.py --profile profile.json --mapping mapping.json --specs kpi_specs.json \
       --request request.json --out results.json --script-out kpi_run.py

Cada especificación se ejecuta por grupo (entidad) más un valor general según su regla overall. Una especificación o grupo fallido se convierte en not_computed con su motivo; la ejecución continúa. El resumen de stdout enumera cada advertencia validation:.

La misma ejecución también:

• vuelve a ejecutar todos los KPIs una vez por variante de sensibilidad y almacena sensitivity: {low, high, variants} en cada KPI;
• compara cada KPI con los valores que informan sus referencias, convertidos a la unidad del KPI (comparison: diferencia, diferencia relativa, mejor/peor por dirección, si el valor informado está dentro del rango de sensibilidad);
• escribe data_health: por columna numérica mapeada, proporción faltante, racha constante más larga, valores atípicos robustos y valores imposibles (conteos negativos, % por encima de 100, por debajo de cero absoluto), más cobertura de tiempo para series regulares.

Si algún KPI lleva una advertencia de validación: vuelve a verificar las notas de análisis (paso 2), el mapeo (paso 4) y la especificación (paso 5) una vez, vuelve a ejecutar desde el paso más temprano que cambiaste, luego informa con la advertencia si aún falla.

Después de la ejecución, puedes editar results.json solo para agregar un texto enable a las entradas not_computed (siempre para KPIs de referencias y include) (qué datos o parámetro harían calculable el KPI) y, según el recurso anterior, registros de KPI ad hoc. kpi_run.py incrusta los hash de las entradas, el perfil, el mapeo, las especificaciones y el código de la habilidad; reproduce results.json (como results_rerun.json) sin la habilidad.

Paso 8 [script + Claude] Informe → report.md, kpi_results.csv, gráfico opcional

python <skill_dir>/scripts/report.py --results results.json --request request.json \
       --mapping mapping.json --profile profile.json \
       --out-md report.md --out-csv kpi_results.csv [--chart kpi_chart.png]

Pasa --chart solo cuando el enfoque involucre cambio a lo largo del tiempo y exista una columna de tiempo; grafica hasta dos KPIs con valores per_period (dale a esos KPIs un ámbito per_period). El script se niega a ejecutarse si un KPI excluido está en results.json.

Lee references/report-format.md, luego reemplaza los marcadores de posición que el script enumera en stdout, editando report.md en el lugar:

• {{FINDINGS}}: 2–5 oraciones respondiendo al enfoque, citando valores de KPI con unidades de results.json. Sin números nuevos. Nombra los KPIs cuyo rango de sensibilidad sea amplio (y la lectura que los mueve), la comparación con referencias cuando la haya (usando la diferencia calculada y el veredicto, con los límites de comparabilidad), y cualquier bandera de salud de datos en una columna que use un KPI clave.
• {{READING:<kpi_id>}}: una oración por KPI: bueno o malo en relación con su dirección y rango típico si se conoce.

Todo lo demás en el informe (nombres, ecuaciones, significados, números) proviene de results.json y no se reescribe. Muestra el report.md terminado en el chat y entrega los archivos como se describe en "Dónde van los resultados".

Lista de verificación de salida

Antes de responder, confirma todo lo siguiente:

• Informe de chat con las ocho secciones en orden: Lo que entendí · Resumen de KPIs · Detalles de KPIs · Hallazgos · No calculados · Excluidos a su solicitud · Problemas de datos · Reproducir.
• Cada KPI muestra valor, unidad, dirección, etiqueta de base, fuente, ecuación LaTeX y ecuación en texto plano, símbolos mapeados a nombres de columna originales con n, significado, lectura, advertencias.
• Cada KPI requerido está calculado o listado bajo "No calculado" con qué datos o parámetro lo habilitarían.
• Ningún KPI excluido aparece en ningún lugar excepto en la línea "Excluido" (verifica también el CSV).
• Patrón de colección y cada suposición declarados; cada juicio, o preguntado, o declarado y probado como una variante de sensibilidad.
• Tabla de salud de datos presente; banderas en las entradas de KPIs clave mencionadas en los hallazgos.
• Cada KPI encontrado en una referencia está calculado (con cita, ubicación, definición y adaptación mostradas) o listado bajo "No calculado" con qué lo habilitaría; los valores informados están etiquetados como citados.
• kpi_results.csv (UTF-8 con BOM) y kpi_run.py escritos, y cada entregable entregado al usuario según "Dónde van los resultados" (descargas + artefacto de informe en aplicaciones Claude; rutas y tarjetas de archivo en Claude Code).
• Gráfico solo si el enfoque trata sobre cambio a lo largo del tiempo.
• Campo sin paquete en references/fields/: ofrece un paquete de campo construido a partir de los KPIs utilizados en esta ejecución, como un archivo Markdown separado siguiendo references/fields/_template.md, para que el usuario lo revise y agregue. No lo escribas en la carpeta de la habilidad.

No objetivos

Sin pronósticos ni construcción de modelos (la habilidad evalúa predicciones que se le dan). Sin fuentes en vivo ni bases de datos. Sin consejos de inversión, médicos ni de ingeniería: informa métricas y lo que indican. Sin conversión de moneda: las monedas mixtas se señalan y calculan por moneda.

Valores predeterminados (usar sin preguntar, indicar cuando se usen)

Configuración	Predeterminado
Tasa libre de riesgo	0
Factor de anualización	solo días laborables diario 252, calendario diario 365, semanal 52, mensual 12, trimestral 4, por hora 8760
Período estacional MASE	por hora 24, diario 7, semanal 52, mensual 12, trimestral 4, de lo contrario 1
Umbral irregular	CV del intervalo > 0.5
Umbral de brecha	3 × mediana del intervalo
Tasa de análisis de columna de tiempo	≥ 95%
Muestreo de perfil	> 1,000,000 filas → muestra de 200,000 filas (la columna de tiempo siempre se lee completa)
max_kpis	12 (solo selecciones propias de Claude)
Manejo de porcentajes	valores 0–100 en una columna que sugiere...

… [truncado para traducción]