---
description: Gera ou anexa diagramas visuais ao artifact store SDD.
argument-hint: "<contexto | attach|doctor ...>"
allowed-tools: [Bash, Read, Write]
---

# SDD Diagram

Antes de rodar comandos `sdd`, resolva o CLI uma vez: use `sdd` quando `command -v sdd` encontrar o binário; no checkout fonte `sdd-layer`, use `cargo run --bin sdd --`; se ambos falharem, reporte instalação/PATH ausente com o comando exato que precisa ser reexecutado.

Use este comando quando precisar gerar, revisar ou anexar diagramas para IDEA, PRD ou Tech Spec.

Entrada:

`$ARGUMENTS`

## Fluxo obrigatório

1. Use Skill: `artifact-diagrams` para decidir o formato canônico mínimo no artefato Markdown.
2. Use Skill: `diagram-design` para gerar companion visual editorial em HTML/SVG quando o pedido exigir leitura mais polida.
3. Preserve Mermaid/Excalidraw no Markdown como contrato versionável; `diagram-design` nunca substitui o diagrama canônico do artefato.

## Gate de estilo

Antes de gerar o primeiro companion visual em um projeto, abra `references/style-guide.md` da skill `diagram-design`.

Se o style guide ainda estiver com a pele default do próprio arquivo e sem customização explícita, pause e pergunte ao usuário:

> "Este é o primeiro diagrama visual deste projeto. O style guide ainda está no default. Quer customizar antes? Opções: (a) onboarding por URL, (b) colar tokens manualmente, (c) seguir com o default por enquanto."

Se o usuário escolher:

- `(a)`: siga `references/onboarding.md`, colete cores e tipografia do site e proponha diff antes de escrever.
- `(b)`: registre os tokens em `style-guide.md` sob uma seção de customização.
- `(c)`: prossiga e registre que o default foi aceito para esta rodada.

## Coleta automática

Quando `$ARGUMENTS` for contexto livre, não desenhe por suposição. Colete o sistema alvo automaticamente:

1. Resolva a orquestração com `sdd resolve-input` ou reuse o `--name` explícito quando ele já vier na entrada.
2. Rode `sdd diagram doctor --name "<nome-da-orquestracao>"` para checar artifact store, contexto e configuração.
3. Localize e leia os artefatos fonte relevantes em `docs/<slug>/`, especialmente `01-idea.md`, `02-prd.md`, `03-techspec.md`, `04-tasks.md` e `traceability-map.yaml`.
4. Confirme nomes reais no código com busca dirigida:
   - rotas, handlers e middlewares
   - eventos, filas, cron jobs e webhooks
   - entidades, tabelas, schemas e contratos
   - serviços externos, buckets, caches e bancos
   - telas, estados, permissões e pontos de entrada do usuário
5. Para diagramas completos e detalhados, cubra:
   - componentes e boundaries
   - fluxos principais e assíncronos
   - relações entre entidades e persistências
   - workflow operacional e checkpoints humanos

## Escolha do formato

- Use Mermaid no Markdown para o resumo revisável em diff.
- Use Excalidraw quando o resultado precisar de canvas editável.
- Use `diagram-design` para o companion HTML/SVG em `docs/<slug-da-orquestracao>/assets/diagrams/`.
- Quando o panorama exceder o budget visual da skill, divida em `overview + detail` em vez de produzir um diagrama ilegível.

## Validação

Antes de concluir, valide que:

- não foi fabricado endpoint, evento, entidade, tabela, estado ou integração;
- cada relação importante está ancorada em arquivo real, artefato real ou comando real;
- o diagrama distingue fluxo síncrono, assíncrono, persistência e integração externa;
- limitações e hipóteses não verificadas foram explicitadas;
- o companion visual continua coerente com o Mermaid/Excalidraw do Markdown.

Quando houver drift entre documentação e código, priorize o código e registre a divergência no artefato.

## Saída esperada

Para geração nova:

1. Atualize ou crie a seção `## Diagramas` no artefato de IDEA, PRD ou Tech Spec.
2. Gere Mermaid/Excalidraw quando útil ao entendimento.
3. Gere companion self-contained em HTML ou SVG com `diagram-design`.
4. Salve em:

```bash
docs/<slug-da-orquestracao>/assets/diagrams/<stage>-<nome>.html
docs/<slug-da-orquestracao>/assets/diagrams/<stage>-<nome>.svg
```

5. Anexe ao artifact store:

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

6. Se houver schema para o artefato, rode `sdd validate-artifact <tipo> <arquivo.md>`.

Para `attach` e `doctor`, apenas delegue ao CLI correto sem regenerar diagramas.

## Fallback provider-neutral

Se o provider, client ou harness não conseguir gerar companion visual:

- mantenha Mermaid/Excalidraw no Markdown;
- registre a lacuna no artefato;
- não bloqueie o fluxo por ausência de HTML/SVG.

## Regra de acessibilidade

Prefira HTML com SVG inline ou SVG puro, porque são legíveis, versionáveis e podem ser revisitados por times técnicos e stakeholders. PNG é derivado opcional, não formato principal.
