---
name: artifact-diagrams
description: Criar diagramas para artefatos e planejamentos SDD em Mermaid e Excalidraw quando arquitetura, fluxos, estados, contratos, dependências, riscos ou checkpoints ficam mais claros visualmente. Use em Idea, PRD, Tech Spec, Tasks, Refinement, Review, Memory, handoff técnico, planejamento de fluxo ou explicação de pipeline.
---

# Diagramas de Artefato SDD

## Objetivo

Criar diagramas que argumentam visualmente. O desenho deve mostrar relação, causalidade, decisão, transformação ou fluxo que o texto sozinho não deixa óbvio.

## Escolha do formato

- Mermaid: padrão para docs versionados, PRD, Tech Spec, Tasks, Review e handoffs técnicos.
- Excalidraw: use em planejamento quando houver fluxo exploratório, workshop, mapa espacial, arquitetura com muitos agrupamentos, jornada de usuário, dependências entre times ou necessidade de arquivo editável.
- diagram-design: use como companion HTML/SVG editorial em `docs/<slug-da-orquestracao>/assets/diagrams/` quando o usuário pedir visual polido ou quando `diagrams.visual` estiver configurado para isso. Não substitui Mermaid/Excalidraw no Markdown.
- Use ambos quando o planejamento precisar de colaboração visual e o artefato Markdown precisar continuar versionável: Mermaid resume o fluxo no documento, Excalidraw preserva o canvas editável em `assets/`.
- Tabela: use quando o conteúdo é comparação densa e não tem fluxo real.

## Processo

1. Defina a pergunta que o diagrama responde.
2. Leia o artefato de origem e, em Tech Spec/Review, confirme nomes reais em código, contratos, rotas, eventos e schemas.
3. Escolha o padrão visual mínimo:
   - Jornada: ações do usuário, estados e alternativas.
   - Sequence: chamadas entre atores/sistemas.
   - State machine: estados, eventos e transições.
   - Data flow: origem, transformação, persistência e consumo.
   - Architecture map: módulos, boundaries, integrações e ownership.
   - Dependency map: tasks, bloqueios e paralelismo.
   - Checkpoint timeline: gates, evidências e decisões humanas.
4. Em planejamento, decida se o resultado precisa de Mermaid, Excalidraw, companion `diagram-design` ou uma combinação.
5. Use nomes reais quando existirem: endpoint, evento, arquivo, tabela, fila, feature flag ou comando.
6. Inclua legenda curta com fonte, escopo e limitações.

## Contrato por etapa

- Idea: `## Diagramas` é recomendada quando jornada, decisão, estado, relação entre personas/casos de uso ou fluxo exploratório ficarem mais claros visualmente, mas não deve bloquear ideias simples.
- PRD: todo PRD materializado deve ter `## Diagramas`. Inclua ao menos um Mermaid para jornada principal, fluxo de decisão, estados de produto ou relação entre personas/casos de uso quando houver fluxo real. Se nenhum diagrama melhorar entendimento, mantenha a seção com `Não aplicável` e uma justificativa curta.
- Tech Spec: toda Tech Spec materializada deve ter `## Diagramas`. Inclua Mermaid para arquitetura, sequence de chamada crítica, state machine, data flow ou mapa de contratos. Use nomes reais confirmados no codebase quando existirem.
- Tasks: use Mermaid em `## Dependências` ou `## Ordem sugerida` quando houver bloqueios, paralelismo ou sequência não trivial. Cada task que venha de um diagrama deve referenciar o diagrama, nó, fluxo ou estado que implementa.
- Refinement/Review: use Mermaid ou Excalidraw apenas quando isso ajudar o checkpoint humano a decidir.

## Boas práticas Mermaid

- Use IDs técnicos simples e ASCII (`A`, `API`, `StateReady`), mas preserve labels humanos em PT-BR com acentos dentro de aspas.
- Prefira diagramas pequenos e legíveis. Se passar de 12 nós ou 20 arestas, divida por fluxo ou use Excalidraw.
- Nomeie setas com eventos, comandos, regras ou payloads reais quando isso reduzir ambiguidade.
- Não misture objetivo de produto e detalhe técnico no mesmo diagrama; PRD mostra comportamento/valor, Tech Spec mostra implementação/contratos.
- Sempre inclua fonte e limitação quando o diagrama depende de premissa ainda não verificada.

## Mermaid base

Fluxo:

```mermaid
flowchart TD
  A["Origem"] --> B{"Decisão"}
  B -->|Aprovado| C["Próxima etapa"]
  B -->|Ajustes| D["Retorna com feedback"]
```

Sequence:

```mermaid
sequenceDiagram
  participant U as Usuário
  participant A as Aplicação
  participant API as API
  U->>A: ação
  A->>API: request real
  API-->>A: resposta real
```

Estados:

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Approved: checkpoint aprovado
  Draft --> NeedsChanges: pedir ajustes
  Approved --> [*]
```

## Excalidraw

Ao gerar `.excalidraw`, salve em `docs/<slug-da-orquestracao>/assets/<nome>.excalidraw` quando houver artifact store. Construa por seções, use cores semânticas, labels livres quando bastarem e artefatos de evidência para dados reais, trechos de payload, eventos ou comandos. Renderize e revise visualmente se houver ferramenta disponível; se não houver, valide JSON/estrutura e registre que a revisão visual precisa de screenshot ou ferramenta externa.

Em Markdown, referencie o canvas por caminho relativo ao artifact store. O arquivo `.excalidraw` é o canvas editável; o Mermaid no `.md` continua sendo o resumo versionável e revisável em diff.

Use nomes previsíveis:

- `planning-flow.excalidraw`: fluxo de planejamento ou jornada.
- `technical-architecture.excalidraw`: mapa de arquitetura.
- `state-machine.excalidraw`: estados e transições.
- `task-dependencies.excalidraw`: dependências entre tasks.
- `checkpoint-timeline.excalidraw`: gates humanos e evidências.

## diagram-design

Use a skill `diagram-design` para gerar um arquivo HTML/SVG self-contained quando o usuário pedir um visual editorial, quando a documentação precisar de companion visual para leitura, ou quando a configuração `diagrams.visual` permitir geração automática. Salve o resultado em `docs/<slug-da-orquestracao>/assets/diagrams/<stage>-<nome>.html` ou `.svg`.

Depois de gerar ou receber o arquivo visual, anexe-o com:

```bash
sdd diagram attach --name "<nome-da-orquestracao>" --stage idea|prd|techspec --file <arquivo.html|svg|excalidraw> --title "<título>" --source "<artefato ou contexto>"
```

O companion é derivado visual. O contrato revisável em diff continua sendo Mermaid/Excalidraw no Markdown ou uma justificativa explícita de `Não aplicável`.

## Saída recomendada para PRD/Tech Spec

````md
## Diagramas
**Pergunta respondida:** <pergunta>
**Fonte:** <artefato/código/link>
**Escopo:** <o que cobre>
**Limitações:** <não verificado | fora de escopo>

### <nome do diagrama>

```mermaid
...
```

**Excalidraw:** docs/<slug-da-orquestracao>/assets/<nome>.excalidraw
**Visual companion:** docs/<slug-da-orquestracao>/assets/diagrams/<nome>.html
````

## Regras

- Não use diagrama como decoração.
- Não fabrique endpoint, evento, entidade, tabela ou estado.
- Não faça grade de caixas idênticas quando o conteúdo tem hierarquia, sequência ou causalidade.
- Se o diagrama não ensina algo novo, remova-o ou substitua por matriz.
