ropimen/claude-skill-kpi-calculator

Calculadora de KPI

Converte um ou mais arquivos CSV/TSV mais uma instrução curta em um conjunto verificado de KPIs, cada um com valor, unidade, equação, significado e etiqueta de base. Não há uma lista fixa de campos: os KPIs são projetados para o que os dados e a instrução descrevem. Artigos, relatórios ou resultados anteriores anexados junto aos dados contribuem com seus KPIs, aplicados aos dados do usuário com sua proveniência.

<skill_dir> abaixo significa a pasta que contém este arquivo. Execute os scripts como python <skill_dir>/scripts/<nome>.py a partir da pasta de trabalho (veja "Onde os resultados vão"), passando os arquivos de dados por caminho absoluto.

Se python não for encontrado (ou abrir a Microsoft Store), use py -3 no Windows ou python3 em outros lugares em todos os comandos abaixo. Verifique uma vez no início com python --version.

Regras rígidas

1. Cada número vem do código executado nos arquivos. Nunca estime, arredonde visualmente ou afirme um valor em prosa que não esteja em results.json.
2. KPIs excluídos nunca são calculados e nunca aparecem em lugar algum, exceto na única linha "Excluído a seu pedido".
3. Cada suposição é declarada em "O que entendi" (padrão, papéis, unidades, interpolação, fuso horário, ordem dia/mês, padrões usados).
4. No máximo uma pergunta por execução, e apenas quando um palpite errado alteraria os resultados (veja references/role-mapping.md, "Quando perguntar"). Caso contrário, declare a leitura realizada e prossiga.
5. Cada KPI é uma especificação em kpi_specs.json construída a partir de primitivas. Cada um é rotulado basis: established (padrão na área) ou derived (construído a partir de primeiros princípios).
6. Índices ao longo de períodos são índices de somas, não médias de índices, a menos que o KPI seja definido de outra forma.
7. Tempo irregular é tempo real. Nunca conte linhas como passos de tempo; integre e calcule a média ao longo de carimbos de data/hora com a interpolação de cada coluna.
8. Falhas de validação são verificadas novamente uma vez (notas de análise → mapeamento → especificação), depois relatadas com o aviso, nunca ocultadas.
9. O conhecimento do domínio vive apenas em Markdown. Nunca adicione lógica específica de domínio aos scripts.
10. Valores de referências são citações. Números relatados em artigos ou resultados anteriores vão apenas no reference.reported de uma especificação; nunca são entradas para um cálculo e nunca apresentados como resultado do usuário.

Onde os resultados vão

Decida isso na etapa 1 e registre em request.json → output_dir.

Situação	Pasta de trabalho (todos os arquivos JSON, cwd dos scripts)	Entregáveis
O usuário nomeia uma pasta ("salve os resultados em D:/relatorios/linha3")	essa pasta (crie-a)	mesma pasta
Aplicativos Claude (claude.ai / chat desktop, /mnt/user-data/outputs/ existe)	o diretório atual	copie para /mnt/user-data/outputs/: eles aparecem como arquivos baixáveis
Claude Code, nenhuma pasta nomeada	kpi_output/ no diretório atual	mesma pasta

Entregáveis são report.md, kpi_results.csv, kpi_run.py, e quando produzidos kpi_chart.png, kpi_adhoc.py e um pacote de campo oferecido. Os arquivos de trabalho (request.json, profile.json, mapping.json, kpi_specs.json, results.json) permanecem na pasta de trabalho para auditoria e são compartilhados apenas se solicitado.

Entregue os entregáveis ao usuário para que ele possa salvá-los em qualquer lugar:

• Aplicativos Claude: além dos arquivos baixáveis, mostre o relatório finalizado como um artefato de documento Markdown, para que possa ser lido, copiado ou baixado por conta própria.
• Claude Code: liste cada entregável como um link para seu caminho. Quando o host oferecer uma ferramenta para enviar arquivos ao usuário (por exemplo, cartões de arquivo no aplicativo desktop), envie os entregáveis através dela também.
• Nunca escreva fora da pasta de trabalho e do local dos entregáveis, a menos que o usuário solicite.

Para reexecutar kpi_run.py mais tarde, coloque-o em uma pasta junto com os arquivos de entrada.

Scripts primeiro, ad hoc apenas como alternativa

Sempre execute os scripts abaixo. Escreva seu próprio código pandas apenas quando:

• um script sair com um erro que você não pode corrigir ajustando profile.json, mapping.json ou as especificações (por exemplo, um arquivo profile_csv.py não pode analisar), ou
• um KPI precisar de uma operação que nenhuma primitiva ou expressão cobre (check_spec.py relata unknown_op).

Então:

1. Coloque o código em kpi_adhoc.py no diretório de trabalho, carregue os dados com as configurações de análise em profile.json (ou scripts/lib/io.py load), e mantenha-o executável por conta própria.
2. Adicione cada KPI ad-hoc a results.json → kpis com todos os campos de schemas/results.schema.json e "computed_by": "ad_hoc", depois que run_specs.py tiver escrito o arquivo. Nunca altere valores que o mecanismo calculou.
3. O relatório marca esses KPIs com † e aponta para kpi_adhoc.py.

Nunca use eval/exec em strings derivadas de usuário ou dados, mesmo ad hoc.

Fluxo de trabalho

Execute as oito etapas em ordem. Leia um arquivo de referência apenas quando sua etapa precisar dele.

Etapa 1 [Claude] Analisar a solicitação → request.json

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

• Referências (artigos, relatórios, padrões, resultados anteriores) anexadas ou nomeadas no prompt: leia references/reference-documents.md, diferencie-as dos arquivos de dados, leia cada uma por completo e registre seus KPIs em request.json → references (id, nome, definição, equação, localização, valores relatados). Apenas os arquivos de dados vão para a etapa 2.

• Entrada Excel: converta cada planilha para seu próprio CSV primeiro (pandas.read_excel(sheet_name=None)), nomeie-as <livro>__<planilha>.csv.

• Um KPI incluído e excluído ao mesmo tempo → esta é a única pergunta da execução. Não calcule nada para esse KPI até que seja respondido.

Etapa 2 [script] Carregar e perfilar → profile.json

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

Verifique o tipo, dica de unidade e notas de análise de cada coluna. Se uma coluna que deveria ser numérica resultar como text, olhe suas amostras e corrija a análise antes de continuar.

Etapa 3 [script] Detectar padrão temporal e de coleta → profile.json (seção de tempo)

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

Leia references/collection-patterns.md. O script propõe um padrão com evidence e outros candidates plausíveis, além de entity_column (quando carimbos de data/hora se repetem em uma coluna de agrupamento), frequency (alias pandas, como D, B, h, MS), gaps, duplicates e tz. Confirme ou substitua o padrão e a entidade usando a descrição do usuário. Se ambiguous_dayfirst for verdadeiro, declare a suposição (ou pergunte, se ambas as leituras alterarem os valores de KPI e nenhuma outra pergunta estiver pendente). Passe --tz quando o usuário nomear o fuso horário de carimbos de data/hora locais ingênuos.

Etapa 4 [Claude] Mapear papéis das colunas → mapping.json

Leia references/role-mapping.md. Atribua a cada coluna um papel, grandeza física, unidade e interpolação; registre entidade, pares, junções, remodelagem, reamostragem e parâmetros. Cabeçalhos em qualquer idioma são lidos pelo significado; mantenha os nomes originais.

Em seguida, escreva mapping.json → sensitivity: uma variante para cada decisão que poderia razoavelmente ter sido tomada de outra forma (interpolação, uma classe de estado ambígua, ordem dia/mês, parada planejada, uma unidade ou parâmetro assumido). O mecanismo reexecuta cada KPI sob cada variante e relata um intervalo baixo–alto, para que o usuário veja quais números dependem de quais suposições. Regras e formato de patch estão em references/role-mapping.md, "Variantes de sensibilidade".

Etapa 5 [Claude] Projetar e selecionar KPIs → kpi_specs.json

Leia references/kpi-discovery.md (método) e references/kpi-spec.md (formato, primitivas, gramática). Se references/fields/ tiver um pacote correspondente ao campo, leia-o também; ele informa, mas nunca limita.

Ordem de seleção: obrigatórios (include) e custom primeiro → KPIs de references (especificação source: reference com um bloco reference, veja references/reference-documents.md) → nunca exclude → por relevância ao focus, estabelecidos antes de derivados, sem quase-duplicatas → limite as próprias escolhas de Claude a max_kpis (padrão 12). KPIs obrigatórios, personalizados e de referência nunca são descartados; um KPI de referência que os dados não podem suportar não recebe especificação e é listado em "Não calculado automaticamente".

Em seguida, verifique as especificações:

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

Saída 0 = ok. Saída 1 = erros como JSON no stdout: corrija a especificação ou o mapeamento e reexecute. Unidades desconhecidas retornam como avisos: se uma alterar resultados, pode ser a pergunta da execução.

Etapa 6–7 [script] Calcular e 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 especificação é executada por grupo (entidade) mais um valor geral de acordo com sua regra overall. Uma especificação ou grupo com falha torna-se not_computed com sua razão; a execução continua. O resumo no stdout lista cada aviso validation:.

A mesma execução também:

• reexecuta todos os KPIs uma vez por variante de sensibilidade e armazena sensitivity: {low, high, variants} em cada KPI;
• compara cada KPI com os valores que suas referências relatam, convertidos para a unidade do KPI (comparison: diferença, diferença relativa, melhor/pior por direção, se o valor relatado está dentro do intervalo de sensibilidade);
• escreve data_health: por coluna numérica mapeada, parcela faltante, maior sequência constante, outliers robustos e valores impossíveis (contagens negativas, % acima de 100, abaixo de zero absoluto), mais cobertura temporal para séries regulares.

Se algum KPI tiver um aviso de validação: verifique novamente as notas de análise (etapa 2), mapeamento (etapa 4) e especificação (etapa 5) uma vez, reexecute a partir da etapa mais antiga que você alterou, depois relate com o aviso se ainda falhar.

Após a execução, você pode editar results.json apenas para adicionar um texto enable a entradas not_computed (sempre para KPIs de referências e include) (quais dados ou parâmetros tornariam o KPI computável) e, conforme a alternativa acima, registros de KPI ad-hoc. kpi_run.py incorpora os hashes das entradas, o perfil, o mapeamento, as especificações e o código da skill; ele reproduz results.json (como results_rerun.json) sem a skill.

Etapa 8 [script + Claude] Relatório → 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]

Passe --chart apenas quando o foco envolver mudança ao longo do tempo e existir uma coluna de tempo; ele plota até dois KPIs com valores per_period (atribua a esses KPIs um escopo per_period). O script se recusa a executar se um KPI excluído estiver em results.json.

Leia references/report-format.md, depois substitua os placeholders que o script lista no stdout, editando report.md no local:

• {{FINDINGS}}: 2–5 frases respondendo ao foco, citando valores de KPI com unidades de results.json. Nenhum número novo. Nomeie KPIs cujo intervalo de sensibilidade é amplo (e a leitura que os move), a comparação com referências quando houver uma (usando a diferença e o veredito calculados, com os limites de comparabilidade), e qualquer sinalizador de saúde de dados em uma coluna que um KPI chave usa.
• {{READING:<kpi_id>}}: uma frase por KPI: bom ou ruim em relação à sua direção e faixa típica se conhecida.

Todo o resto no relatório (nomes, equações, significados, números) vem de results.json e não é reescrito. Mostre o report.md finalizado no chat e entregue os arquivos conforme descrito em "Onde os resultados vão".

Lista de verificação de saída

Antes de responder, confirme todos estes itens:

• Relatório do chat com as oito seções em ordem: O que entendi · Visão geral dos KPIs · Detalhes dos KPIs · Descobertas · Não calculado · Excluído a seu pedido · Problemas de dados · Reproduzir.
• Cada KPI mostra valor, unidade, direção, etiqueta de base, fonte, equação LaTeX e equação em texto simples, símbolos mapeados para nomes de colunas originais com n, significado, leitura, avisos.
• Cada KPI obrigatório está calculado ou listado em "Não calculado" com quais dados ou parâmetros o habilitariam.
• Nenhum KPI excluído aparece em lugar algum, exceto na única linha "Excluído" (verifique também o CSV).
• Padrão de coleta e cada suposição declarados; cada decisão ou perguntada, ou declarada e testada como uma variante de sensibilidade.
• Tabela de saúde de dados presente; sinalizadores nas entradas dos KPIs principais mencionados nas descobertas.
• Cada KPI encontrado em uma referência está calculado (com citação, localização, definição e adaptação mostrados) ou listado em "Não calculado" com o que o habilitaria; valores relatados são rotulados como citados.
• kpi_results.csv (UTF-8 com BOM) e kpi_run.py escritos, e cada entregável entregue ao usuário conforme "Onde os resultados vão" (downloads + artefato de relatório em aplicativos Claude; caminhos e cartões de arquivo no Claude Code).
• Gráfico apenas se o foco for sobre mudança ao longo do tempo.
• Campo sem pacote em references/fields/: ofereça um pacote de campo construído a partir dos KPIs usados nesta execução, como um arquivo Markdown separado seguindo references/fields/_template.md, para o usuário revisar e adicionar. Não o escreva na pasta da skill.

Não-objetivos

Nenhuma previsão ou construção de modelo (a skill avalia previsões que lhe são fornecidas). Nenhum feed ao vivo ou banco de dados. Nenhum conselho de investimento, médico ou de engenharia: relate métricas e o que elas indicam. Nenhuma conversão de moeda: moedas mistas são sinalizadas e calculadas por moeda.

Padrões (use sem perguntar, declare quando usados)

Configuração	Padrão
Taxa livre de risco	0
Fator de anualização	diário apenas dias úteis 252, diário calendário 365, semanal 52, mensal 12, trimestral 4, horário 8760
Período sazonal MASE	horário 24, diário 7, semanal 52, mensal 12, trimestral 4, caso contrário 1
Limite irregular	CV do intervalo > 0.5
Limite de lacuna	3 × intervalo mediano
Taxa de análise da coluna de tempo	≥ 95%
Amostragem de perfil	> 1.000.000 linhas → amostra de 200.000 linhas (coluna de tempo sempre lida por completo)
max_kpis	12 (apenas escolhas próprias de Claude)
Tratamento de porcentagem	valores 0–100 em uma coluna cujos he...