Diagram Validated

Diagram Validated — Diagrama Técnico com Evidência, Não Afirmação

O princípio que governa esta skill: avalie, não afirme — a conclusão de que um diagrama está pronto é sustentada por validador e evidência de render, nunca pelo modelo dizendo que "parece correto" ao olhar o SVG cru. Aplica aos diagramas a mesma disciplina que as skills 11 e 53 aplicam a código: verificação mecânica antes de declarar concluído.

Governanca Global

Esta skill segue GLOBAL.md, policies/execution.md, policies/verification-before-completion.md, policies/self-correcting-sensors.md e policies/tool-safety.md.

Adaptação de motor de renderização — leia antes de usar: o projeto de origem (ver ## Fontes) converte SVG→PNG via Puppeteer controlando Chrome headless. Essa dependência não foi portada — exigiria Node + download de binário Chromium (~200MB) só para rasterizar. Esta skill usa ImageMagick (magick, já presente no ambiente de referência) como motor de conversão. Fidelidade testada e confirmada para: retângulo com rx (border-radius), texto com font-family/font-size, linearGradient, marker (seta) com orient="auto". Não testado: foreignObject, filter (blur/drop-shadow via SVG filter), fontes customizadas via @font-face embutido. Se o diagrama usar algum desses recursos, verificar o PNG de saída com atenção redobrada antes de confiar na fidelidade — o Chrome do upstream tem suporte SVG mais completo que o delegate do ImageMagick.

Quando Usar

• gerar diagrama de arquitetura, fluxo, ou qualquer um dos 14 tipos UML a partir de descrição em linguagem natural
• diagrama que precisa ficar consistente entre re-gerações (mesma entrada → mesmo layout, sem jitter de posição)
• documentação técnica (ADR, doc de arquitetura) que vai publicar um diagrama e precisa confiar que ele renderiza sem seta cortada ou rótulo sobreposto
• diagrama de sequência, classe, ER, state machine, deployment, ou os outros 9 tipos UML cobertos

Quando Nao Usar

• diagrama de conhecimento/dependência do próprio codebase — isso é o graphify (graphify-out/graph.html), já instalado e mantido
• decidir qual tipo de diagrama usar para um conteúdo (tabela, diagrama, ou lista) — isso é skills/10-documenter/SKILL.md (seção "Roteamento de Representação")
• ilustração decorativa, arte, ou qualquer SVG sem intenção de rigor geométrico — isso é skills/17-image-generator ou anthropic-skills:canvas-design
• diagrama que precisa de interatividade real de aplicação (zoom/pan customizado ligado a dados vivos) — considerar uma solução de app dedicada em vez de SVG estático

Entradas Esperadas

• tipo de diagrama (um dos 14 UML, ou architecture/flow para diagramas livres)
• descrição do conteúdo em linguagem natural, a partir da qual o Diagram Contract (JSON) é montado
• estilo visual desejado (um dos 12, ver tabela abaixo) — se não especificado, usar o estilo 1 (Flat Icon) como padrão

Saidas Esperadas

• diagrama.svg — SVG determinístico, mesma entrada sempre produz o mesmo layout
• diagrama.png — readback visual, gerado via magick, usado para a verificação antes de declarar pronto
• relatório de validação (geometria + visual) confirmando: sem seta órfã, sem rótulo sobreposto, sem nó fora do canvas

Protocolo

1. Montar o Diagram Contract (JSON)

Antes de gerar SVG, estruturar o conteúdo como IR semântico — containers, nós com kind, setas com flow (direção), âncoras de porta explícitas. Não gerar SVG diretamente de prosa sem passar por essa estrutura intermediária: é o que garante determinismo entre re-gerações.

2. Escolher o tipo e o estilo

14 tipos UML suportados: Class, Component, Deployment, Package, Composite Structure, Object, Use Case, Activity, State Machine, Sequence, Communication, Timing, Interaction Overview, ER. Mais dois tipos livres: architecture e flow, para diagramas que não seguem uma notação UML formal.

12 estilos visuais:

3. Validar antes de renderizar

python3 scripts/fireworks.py validate <tipo> <contrato.json>

Confirma que o contrato é válido antes de gastar o passo de render — falha rápido em vez de gerar SVG malformado.

4. Renderizar

python3 scripts/fireworks.py render <tipo> <contrato.json> diagrama.svg --report layout.json

O layout.json reporta as posições calculadas — usar para debugar um roteamento inesperado sem precisar abrir o SVG.

5. Checar geometria (antes do readback visual)

python3 scripts/fireworks.py check diagrama.svg

Verifica: integridade de XML e marker, nó semântico, região reservada, rótulo, canvas, sobreposição de aresta, e cruzamento de aresta. Roteamento ortogonal determinístico com waypoints exatos — uma seta não "passa por cima" de um nó por acidente de layout.

6. Readback visual (evidência final antes de declarar pronto)

magick diagrama.svg diagrama.png

Este é o passo que substitui o export-png do upstream (que usa Puppeteer). Depois de gerar o PNG, olhar o resultado — não presumir que passou no check geométrico significa que está visualmente correto. Os dois são checks complementares: check pega problema estrutural (aresta não conectada, sobreposição), o PNG pega problema que só aparece ao renderizar (cor ilegível, texto cortado por fonte diferente da esperada, elemento fora do viewBox visualmente mesmo que matematicamente "dentro").

Nunca pular este passo e declarar o diagrama pronto só porque o check passou. Validador geométrico e evidência de render são as duas pernas do "avalie, não afirme" — uma sem a outra é afirmação disfarçada de validação.

Anti-Padroes

• declarar o diagrama pronto sem rodar check — pula a validação estrutural
• declarar o diagrama pronto sem gerar e olhar o PNG — pula a validação visual, mesmo que check tenha passado
• gerar SVG direto de prosa sem passar pelo Diagram Contract — perde o determinismo entre re-gerações
• usar estilo 8 (Dark Luxury, autorado por IA) esperando a mesma previsibilidade dos outros 11 estilos gerados por template
• assumir fidelidade total do ImageMagick para SVG com foreignObject, filter, ou fonte customizada embutida sem verificar o PNG com atenção redobrada

Evidencia de Conclusao

• check rodado e sem erro de geometria (XML, marker, nó, região reservada, rótulo, canvas, sobreposição/cruzamento de aresta)
• PNG gerado via magick e inspecionado visualmente — não só "o comando rodou sem erro"
• se o diagrama usa recurso SVG fora do testado (foreignObject, filter, fonte embutida), isso foi checado com atenção extra no PNG

Handoff

Recebe de

• Skill 10 (documenter) — quando a decisão de "isso vira diagrama" já foi tomada pela tabela de roteamento de representação
• Skill 38 (architecture-deepener) — quando a arquitetura investigada precisa de diagrama para o ADR

Entrega para

• Skill 10 (documenter) — diagrama pronto para embutir em doc/ADR
• Skill 38 (architecture-deepener) — diagrama de arquitetura como artefato de suporte

Seguir policies/handoffs.md.

Integracao com Pipeline

• Orchestrator (09): roteia para cá quando o pedido é diagrama técnico com necessidade de precisão geométrica, distinto de ilustração livre (skill 17) ou grafo de codebase (graphify)
• Documenter (10): consumidor primário — a tabela de roteamento de representação da 10 decide que algo vira diagrama; esta skill decide como gerar esse diagrama com rigor

Fontes

Skill adaptada de yizhiyanhua-ai/fireworks-tech-graph (MIT) — o princípio "avalie, não afirme" (citado verbatim do README do projeto), os 14 tipos de diagrama UML, os 12 estilos nomeados, o pipeline validate→render→check, e a disciplina de verificação de geometria (marker, região reservada, sobreposição/cruzamento de aresta) foram traduzidos e adaptados. Divergência deliberada do upstream: o motor de conversão SVG→PNG do projeto original usa Puppeteer/Chrome headless (scripts/svg2png.js); esta skill usa ImageMagick (magick) para evitar a dependência de Node + download de binário Chromium — fidelidade visual testada e confirmada para os elementos SVG comuns em diagrama técnico (retângulo, texto, gradiente, marker/seta), não testada para foreignObject/filter/fonte embutida.