aelena/bpmnemonic

O que bpmnemonic faz?

bpmnemonic — BPMN + mnemônico. Transforme um diagrama de processo em um documento legível, pesquisável e versionável. Porque ninguém abre um arquivo .bpmn no editor às 2 da manhã, mas todo mundo lê markdown.

Por que isso existe

Arquivos BPMN capturam semântica rica — atores, decisões, caminhos de exceção, fluxos de dados, trocas de mensagens — mas apenas se você tiver um visualizador aberto. No momento em que você precisa:

• discutir o processo em uma revisão de PR,
• enviar requisitos para um contratante,
• integrar um novo engenheiro,
• ou alimentar o processo para um modelo de linguagem,

…o diagrama se torna um empecilho. Você precisa de prosa. Você precisa que ela corresponda exatamente ao diagrama. E não quer escrevê-la manualmente toda vez que o diagrama mudar.

Este skill codifica a tradução da estrutura BPMN para um de dois formatos markdown:

• specs.md — uma especificação técnica para engenheiros. Passos numerados, fluxos exaustivos, contratos de dados, critérios de aceitação.
• prd.md — um documento de requisitos de produto para stakeholders. Declaração do problema, atores, jornada do usuário, métricas de sucesso, escopo.

Ambos são derivados do mesmo diagrama. Eles diferem em público-alvo, vocabulário e quais elementos BPMN são enfatizados.

Invocação

Gatilho	Comportamento
/bpmnemonic ou /bpmn-to-spec ou /flow-to-doc	Padrão — analisa o arquivo, pergunta qual formato gerar e gera
/bpmnemonic spec [caminho]	Gera specs.md a partir do arquivo BPMN
/bpmnemonic prd [caminho]	Gera prd.md a partir do arquivo BPMN
/bpmnemonic both [caminho]	Gera ambos os documentos
/bpmnemonic analyze [caminho]	Executa scripts/analyze-bpmn.sh e relata contagem de elementos + complexidade
Linguagem natural: "converta este BPMN para uma spec", "crie um PRD a partir deste diagrama", "documente este fluxo de trabalho"	Mesmo comportamento

Parar / desabilitar

Não é baseado em sessão. Um disparo por arquivo.

O manual de tradução (5 etapas)

Etapa 1: Analisar e inventariar

Leia o arquivo .bpmn (é apenas XML). Construa um inventário:

• Processo nome, id e qualquer documentação
• Participantes (bpmn:participant) — tornam-se "atores" ou "sistemas externos"
• Raias (bpmn:lane dentro de bpmn:laneSet) — tornam-se "papéis" ou "responsabilidades"
• Tarefas (bpmn:task, bpmn:userTask, bpmn:serviceTask, bpmn:sendTask, bpmn:receiveTask, bpmn:scriptTask, bpmn:businessRuleTask, bpmn:manualTask) — tornam-se passos numerados
• Eventos (bpmn:startEvent, bpmn:endEvent, bpmn:intermediateThrowEvent, bpmn:intermediateCatchEvent, bpmn:boundaryEvent) — gatilhos, terminações, capturas de erro, timeouts
• Gateways (bpmn:exclusiveGateway, bpmn:parallelGateway, bpmn:inclusiveGateway, bpmn:eventBasedGateway) — pontos de ramificação
• Fluxos de sequência (bpmn:sequenceFlow) — as setas
• Fluxos de mensagem (bpmn:messageFlow) — comunicação entre pools, pontos de integração
• Objetos de dados (bpmn:dataObject, bpmn:dataObjectReference) — documentos, registros, payloads
• Subprocessos (bpmn:subProcess, bpmn:callActivity) — complexidade aninhada

Se scripts/analyze-bpmn.sh for executado, ele produz este inventário automaticamente.

Etapa 2: Construir a narrativa linear (o caminho feliz)

Percorra os fluxos de sequência de cada evento inicial até cada evento final, escolhendo o caminho que não desvia em nenhum gateway (ou seja, o caminho mais provável de sucesso). Este é o "caminho feliz" — será a espinha dorsal tanto da spec quanto do PRD.

Formate-o como passos numerados. Cada passo nomeia o ator (da raia) e a ação (do nome da tarefa).

Etapa 3: Ramificar (fluxos alternativos)

Para cada gateway encontrado no caminho feliz, os outros ramos tornam-se fluxos alternativos na spec ou casos extremos no PRD. Numere-os após o fluxo principal.

Etapa 4: Capturar exceções

Eventos de boundary (bpmn:boundaryEvent) anexados a tarefas — eventos de erro, eventos de timer, eventos de escalada — tornam-se fluxos de exceção. Estes geralmente estão ausentes em PRDs, mas são cruciais em specs.

Etapa 5: Identificar comunicação entre pools

Fluxos de mensagem entre pools tornam-se pontos de integração. Na spec, são contratos de API externa. No PRD, são seções "isso depende de".

Escolhendo o formato de saída

Se o usuário não especificar, pergunte. Caso contrário, use estas heurísticas:

O diagrama possui...	Sugira
1 pool, principalmente tarefas de usuário, < 10 elementos no total	PRD — pequeno o suficiente para ser uma descrição de funcionalidade
Múltiplos pools, fluxos de mensagem, eventos de erro	specs.md — engenharia precisa do detalhe
Subprocessos ou call activities	specs.md + recomende traduzir cada subprocesso separadamente
Um gateway "tabela de decisão" (DMN)	ambos — PRD descreve a regra, spec captura a tabela
Em caso de dúvida	ambos — eles se referenciam mutuamente

Fluxo de execução (o que o Claude faz)

1. Ler o arquivo .bpmn (é XML — use a ferramenta Read, depois analise mentalmente ou via scripts/parse-bpmn.sh).
2. Inventariar os elementos conforme a Etapa 1.
3. Sugerir formato se não especificado. Obter confirmação.
4. Percorrer o caminho feliz; construir a narrativa linear.
5. Identificar fluxos alternativos (ramos de gateway), fluxos de exceção (eventos de boundary) e pontos de integração (fluxos de mensagem).
6. Renderizar o modelo escolhido de playbook/templates.md, preenchendo com conteúdo real.
7. Visualizar para o usuário antes de escrever o arquivo. Pedir confirmação.
8. Escrever em ./specs.md e/ou ./prd.md. Se um arquivo existir, fazer diff e confirmar antes de sobrescrever.

Salvaguardas de segurança

• Apenas leitura na origem. Nunca modifique o arquivo .bpmn. Apenas emita markdown.
• Preserve IDs originais. Referencie IDs de elementos BPMN como comentários no markdown gerado para que atualizações futuras possam ser referenciadas cruzadamente. (<!-- de bpmn:userTask id="UserTask_1a2b3c" -->)
• Nunca invente fluxos. Se o diagrama não mostra um caminho, não escreva um. Se algo é ambíguo, apresente como uma questão em aberto no documento, em vez de adivinhar.
• Não traduza tabelas DMN inline a menos que sejam trivialmente pequenas. Faça referência a elas, resuma a regra e recomende um documento de tabela de decisão separado.
• Sinalize nomes de elementos ausentes. Um bpmn:task id="Task_42" sem atributo name é um bug no diagrama. Apresente como [tarefa sem nome — precisa de rótulo] na saída, em vez de inventar um nome.
• Nunca sobrescreva specs.md / prd.md existentes sem visualização + confirmação. Eles podem conter adições manuais.

Arquivos neste skill

• SKILL.md — este arquivo
• playbook/elements.md — referência de elementos BPMN (o que cada tag significa)
• playbook/extraction.md — como ler um arquivo XML .bpmn: nomes de tags, atributos, rastreamento de fluxo
• playbook/templates.md — estrutura alvo para specs.md e prd.md
• playbook/pitfalls.md — erros comuns ao narrar um diagrama de processo
• examples/01-approval.md — pequeno fluxo de aprovação de despesas → ambas as saídas
• examples/02-loan.md — aplicação de empréstimo com múltiplas raias e gateways → spec
• examples/03-errors.md — atendimento de pedidos com eventos de timer/erro → spec
• scripts/analyze-bpmn.sh — conta elementos BPMN, fornece pontuação de complexidade
• scripts/parse-bpmn.sh — extrai informações estruturadas de um arquivo .bpmn (melhor esforço, usa xmlstarlet se disponível)
• README.md — instalação + início rápido