Gerador de Diagramas

O que Gerador de Diagramas faz?

AÇÃO NECESSÁRIA (leia e execute imediatamente)

1. AGORA: Confirme se a tarefa atual se enquadra no escopo deste skill
2. AGORA: Leia ../tool-index.md, verifique a disponibilidade das ferramentas e os caminhos reais
3. PRÓXIMO: Se faltar ferramentas, chame o bootstrap, não adivinhe caminhos
4. AJA: Entre na primeira etapa do "fluxo de trabalho" e execute, não pare no estado de confirmação

Objetivo

Criar diagramas claros e editáveis a partir de entradas confusas ou estruturadas. Prefira primeiro a fonte textual do diagrama para que o resultado possa ser revisado, versionado e refinado. Renderize para arquivos apenas quando o usuário solicitar explicitamente uma imagem/PDF ou quando um artefato para download ajudar materialmente.

Fluxo de trabalho padrão

1. Identifique a intenção do usuário, o público-alvo e o material de origem.
2. Escolha a família de diagramas e a linguagem usando a tabela de decisão abaixo.
3. Normalize entidades, relacionamentos, rótulos, estados, ramificações e informações de tempo/ordem antes de escrever o código do diagrama.
4. Gere código-fonte de diagrama conciso e legível.
5. Valide a sintaxe mentalmente e, ao criar arquivos, execute scripts/render_diagram.py.
6. Retorne o código-fonte do diagrama mais uma breve nota sobre as suposições. Quando arquivos forem gerados, inclua links para os arquivos de saída.

Não pergunte demais por esclarecimentos. Se a solicitação for subespecificada, faça suposições razoáveis e rotule-as brevemente.

Tabela de decisão da linguagem do diagrama

Use Mermaid, a menos que outra linguagem seja claramente melhor.

O usuário quer	Prefira	Por quê
fluxo de processo, árvore de decisão, swimlane simples	Mermaid flowchart	legível e fácil de colar em Markdown
sequência de interações sistema/usuário	Mermaid sequenceDiagram ou PlantUML sequence	Mermaid para documentação; PlantUML para formalidade UML
ciclo de vida, máquina de estados, transições	Mermaid stateDiagram-v2 ou PlantUML state	sintaxe compacta de transições
esquema de banco de dados, entidades, relacionamentos	Mermaid erDiagram	notação ER portátil
modelo de classe/interface/objeto	Mermaid classDiagram ou PlantUML class	Mermaid para documentação; PlantUML para UML detalhado
cronograma de projeto	Mermaid gantt	sintaxe concisa de linha do tempo
hierarquia, ideias, anotações	Mermaid mindmap	bom padrão para mapas de ideias
jornada do cliente/produto	Mermaid journey	notação de jornada integrada
histórico do git	Mermaid gitGraph	notação git integrada
grafo de dependências, pacotes, rede grande	Graphviz DOT	melhores algoritmos de layout para grafos densos
arquitetura com camadas, clusters, limites	Mermaid flowchart com subgraphs, clusters Graphviz ou PlantUML estilo C4	escolha com base na fidelidade solicitada
fluxo ponderado/relação estilo sankey	Mermaid sankey-beta quando suportado, caso contrário SVG ou Graphviz	o suporte do Mermaid pode variar conforme o renderizador
visual personalizado onde as linguagens fonte se encaixam mal	SVG	controle preciso sobre layout e estilo

Política de saída

• Sempre forneça o código-fonte editável, a menos que o usuário peça explicitamente apenas uma imagem.
• Padrão: um único diagrama melhor. Ofereça alternativas apenas quando genuinamente útil.
• Prefira sintaxe estável e simples em vez de recursos sofisticados que podem não renderizar em versões antigas do Mermaid/PlantUML.
• Use rótulos curtos. Divida textos longos em notas fora do diagrama quando necessário.
• Evite IDs de nós ambíguos. Use IDs ASCII e rótulos legíveis.
• Preserve a terminologia do usuário, mas padronize a capitalização dentro de um diagrama.
• Para diagramas técnicos, inclua limites como cliente, serviço, banco de dados, fila, API externa e operador/usuário quando estiverem implícitos.
• Para diagramas de processo de negócio, distinga caminho feliz, pontos de decisão, falhas, tentativas e etapas manuais quando presentes.
• Para diagramas criados a partir de texto incerto, inclua uma seção Suposições após o código.

Regras de geração Mermaid

Consulte references/diagram-patterns.md para modelos compactos.

Regras gerais do Mermaid:

• Comece com a diretiva de diagrama correta, por exemplo flowchart TD, sequenceDiagram, erDiagram, gantt, mindmap ou journey.
• Para fluxogramas, use flowchart TD a menos que o usuário peça esquerda-para-direita; use flowchart LR para arquitetura e pipelines.
• Use subgraphs para swimlanes ou camadas de arquitetura. Nomeie subgraphs com rótulos legíveis.
• Mantenha os IDs dos nós estáveis e somente ASCII, por exemplo ingest_service[Serviço de Ingestão].
• Coloque entre aspas os rótulos que contêm pontuação com probabilidade de confundir o analisador sintático.
• Use losangos de decisão para ramificações: decision{Condição?}.
• Use rótulos de aresta consistentes: -- sim -->, -- não -->, -. assíncrono .-> ou == crítico ==> apenas quando significativos.
• Em diagramas de sequência, declare os participantes antes das mensagens. Use actor para humanos e participant para sistemas.
• Use blocos alt/else/end, opt/end, loop/end e par/and/end para fluxos condicionais, opcionais, repetidos e paralelos.

Regras de geração Graphviz DOT

Use Graphviz para diagramas de relacionamento grandes, densos ou sensíveis a layout.

• Prefira digraph G para relacionamentos direcionados e graph G para redes não direcionadas.
• Defina atributos de gráfico amigáveis ao layout no topo: rankdir=LR, nodesep, ranksep e splines=true quando útil.
• Use subgraph cluster_nome para limites e subsistemas.
• Use rótulos simples e estilo contido.
• Use rótulos de aresta apenas quando agregarem significado.
• Para muitos nós, agrupe por domínio com clusters e evite arestas de todos-para-todos com muitos cruzamentos.

Regras de geração PlantUML

Use PlantUML quando o usuário solicitar UML ou precisar de notação UML formal.

• Envolva os diagramas com @startuml e @enduml.
• Use estereótipos actor, participant, database, queue, collections ou component quando útil.
• Use package, rectangle ou node para limites de arquitetura.
• Para diagramas de classe, inclua apenas campos/métodos importantes a menos que o usuário solicite detalhamento exaustivo.
• Para diagramas de atividade, use marcadores claros de início/fim e rótulos de ramificação explícitos.

Regras de geração SVG

Use SVG apenas quando linguagens de diagrama textuais não conseguirem expressar a visualização solicitada de forma confiável.

• Mantenha o SVG simples, acessível e editável.
• Inclua <title> e rótulos de texto significativos.
• Prefira retângulos, linhas, setas e grupos em vez de caminhos complexos.
• Não incorpore fontes externas ou imagens remotas.

Renderizando arquivos

Quando o usuário solicitar PNG/SVG/PDF, crie um arquivo de origem e execute:

python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.mmd --format svg --out output.svg
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.dot --format png --out output.png
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.puml --format svg --out output.svg

<SKILL_ROOT> é o caminho real do diretório skills/ deste pacote, detectado automaticamente pelo AI.

O renderizador é intencionalmente tolerante a dependências. Ele tenta ferramentas locais comuns e relata dicas de instalação acionáveis se um renderizador estiver indisponível. Não afirme que uma imagem foi renderizada a menos que o script tenha sido concluído com sucesso e o arquivo de saída exista.

Lista de verificação de validação

Antes de finalizar:

• O tipo de diagrama corresponde à tarefa do usuário.
• O código-fonte é sintaticamente plausível para a linguagem escolhida.
• Os rótulos são curtos o suficiente para caber.
• As arestas e a ordem das mensagens refletem a entrada com precisão.
• As suposições são destacadas quando a entrada estava incompleta.
• Para arquivos gerados, a saída existe e abre ou tem tamanho diferente de zero.

Modelo de resposta comum

Use esta estrutura para a maioria das respostas de diagramas:

Abaixo está a versão editável em [linguagem]:

```[linguagem]
[código-fonte]

Suposições:

• [apenas se necessário]

Arquivo renderizado: [link] [apenas se gerado]

Para solicitações em português, responda em português.

---

## Bootstrap sob Demanda (On-Demand Bootstrap)

### Limites de automação

| Ferramenta | Pode instalar automaticamente | Método de instalação | Descrição |
|---|---|---|---|
| Mermaid CLI (mmdc) | ✓ | npm install -g @mermaid-js/mermaid-cli | Renderiza Mermaid como PNG/SVG |
| Graphviz (dot) | ✗ | Instalação manual | https://graphviz.org/download/ |
| PlantUML | ✗ | Requer Java + plantuml.jar | https://plantuml.com/download |
| Python (script de render) | ✓ | Já está no bootstrap | Dependências de `scripts/render_diagram.py` |

### Descrição

Este skill produz principalmente código-fonte de diagramas em formato textual (Mermaid/DOT/PlantUML), não necessariamente exigindo ferramentas de renderização locais. O renderizador correspondente é necessário apenas quando o usuário solicitar explicitamente a geração de arquivos PNG/SVG/PDF.

Se o renderizador não estiver disponível, `scripts/render_diagram.py` emitirá dicas de instalação em vez de um erro.

---

## Contexto de roteamento

**Entrada upstream**: `skills/SKILL.md` (controle mestre), `routing.md`
**Condições de ativação**: O usuário diz "desenhar", "fluxograma", "diagrama de arquitetura", "diagrama de ataque", "diagrama de sequência", "Mermaid", "Graphviz", "PlantUML"
**Saídas downstream**:
- Diagramas gerados podem ser incorporados em relatórios de `docs-generator/`
- Diagramas de caminho de ataque podem ser usados com relatórios de penetração de `pentest-tools/`

**Módulos relacionados no mesmo nível**: `docs-generator/` (incorporação de diagramas em relatórios)

## Auto-verificação de conclusão de tarefa (MUST passar antes de afirmar conclusão)

- [ ] Eu executei cada etapa do fluxo de trabalho (não apenas li)?
- [ ] Eu usei caminhos de ferramentas reais com base no `tool-index`?
- [ ] Eu produzi evidências reproduzíveis (comandos/scripts/capturas de tela/relatórios)?
- [ ] Eu completei e reescrevi os itens da Checklist exigidos pelas REGRAS?