# Overlay narrativo — a decisão nomeada por tela

## Conteúdo

- 1. Overlay não é `mensagem:` — são duas coisas diferentes
- 2. De onde o overlay sai — origem, não invenção
- 3. A regra: nomeia uma decisão, não descreve o gráfico
- 4. Densidade: um overlay por tela, não por widget
- 5. O filtro anti-blandness — procedimento verificável
- 6. Vocabulário de bandeira vermelha (pré-filtro mecânico)
- 7. Exemplo de par completo (domínio de compras/suprimentos)

Leia ANTES de escrever qualquer overlay. Se você chegou aqui para preencher
o texto de uma tela de mockup, pare e rode o §5 contra o que escreveu antes
de renderizar — é a parte que faz este arquivo valer alguma coisa.

Gráfico bonito é commodity. Power BI, Qlik, Looker — todos entregam gráfico
bem desenhado de graça. O que nenhum deles entrega de fábrica é a **leitura**:
o que aquele número específico significa para a decisão daquele cliente
específico. É isso que a `lumo-mockup` vende, e é isso que o overlay
carrega. Na analogia do apartamento planejado que dá nome à skill: os móveis
não são sombreamento, borda ou degradê (isso qualquer render de alta
fidelidade tem) — os móveis são o **problema que a peça resolve**. O
overlay é o móvel.

## 1. Overlay não é `mensagem:` — são duas coisas diferentes

A ficha de widget (`wireframe-kit.md`) já carrega um campo de texto —
`mensagem:`, "a conclusão que o widget sustenta" (formato IBCS/SAY, tipo
"Loja Sul puxa a queda do mês"). É tentador achar que o overlay é só isso
promovido de tamanho de fonte. **Não é.** São dois objetos diferentes, com
dono, escopo e obrigatoriedade diferentes:

| | `mensagem:` (ficha de widget) | overlay narrativo (esta referência) |
|---|---|---|
| Escopo | 1 por widget | 1 por TELA (dashboard inteiro) |
| Conteúdo | conclusão factual que **aquele** widget sozinho sustenta | a decisão de negócio que a tela inteira habilita |
| Quem escreve | `lumo-scope`, no corpo da ficha (`dashboards/*.md`) | `lumo-mockup`, ao montar o wireframe (§2) |
| Obrigatoriedade | obrigatório só quando `publico: executivo` | sempre, em toda tela renderizada |
| Onde mora | dentro do YAML da ficha, campo irmão de `relacao`/`encoding` | elemento de texto da própria página do mockup, fora do corpo de qualquer widget |

Um jeito rápido de não confundir os dois: `mensagem:` responde "o que este
gráfico específico está dizendo?" — ainda é uma leitura de dado, ainda pode
ser genérica por natureza se o widget for simples ("receita caiu 3% no
mês"). O overlay responde "e daí — o que eu faço com isso?". Uma tela pode
ter seis `mensagem:` corretas e factuais e ainda assim não ter overlay
nenhum, porque nenhuma delas nomeou uma decisão. O overlay é o que costura
as `mensagem:` da tela numa única implicação acionável — nunca a concatenação
das seis, nunca a repetição da mais chamativa; é sempre um nível editorial
acima delas.

## 2. De onde o overlay sai — origem, não invenção

O overlay não nasce de uma pergunta em aberto para o renderizador
("o que eu acho que é interessante aqui?"). Ele sai de dois campos que a
`lumo-scope` já escreveu em `dashboards/<dash>.md` **antes** de qualquer
widget ser desenhado (schema completo em
`lumo-scope:references/documento-template.md`, que esta skill só lê —
nunca edita):

```yaml
pergunta: "<a UMA pergunta que o dashboard responde>"
decisoes_que_suporta: [<top-3 decisões do usuário>]
```

`pergunta:` é o enquadramento — o que a tela existe para responder.
`decisoes_que_suporta:` é a lista curta de decisões reais de negócio que a
resposta habilita. O overlay é a fusão dos dois num enunciado único: qual,
entre as decisões listadas, esta combinação específica de widgets torna
visível — e por quê o cliente não enxerga isso hoje sem a tela. Quando a
tela tiver mais de uma decisão em `decisoes_que_suporta:`, o overlay escolhe
a de maior prioridade para **esta** tela, não tenta caber as três numa frase
só (isso reintroduz a densidade que o §4 proíbe).

Isso é a mesma disciplina de "a ficha vincula, não a figura"
(`forma-sem-magnitude.md` §6): o overlay não pode afirmar uma decisão que
não estava em `decisoes_que_suporta:` — se a leitura dos widgets sugere uma
decisão nova que a ficha não previu, isso é lacuna de escopo (volta para a
`lumo-scope` registrar, não vira texto solto no render). O renderizador
frasea; não decide o que é decisão de negócio do cliente.

## 3. A regra: nomeia uma decisão, não descreve o gráfico

- **Fraco:** *"este gráfico mostra compras por fornecedor"* — descreve o
  óbvio, o que o cliente já vê olhando os eixos.
- **Forte:** *"três fornecedores concentram a maior parte da compra — é aqui
  que renegociação de preço tem alavancagem, e é isso que você não enxerga
  hoje no ERP"*.

A diferença estrutural entre os dois, para reconhecer o padrão sem depender
de gosto: o texto fraco tem sujeito = o gráfico ("este gráfico"), verbo de
exibição ("mostra") e objeto = a própria codificação visual reafirmada em
palavras (categoria no eixo × métrica). Ele é literalmente a legenda dos
eixos, traduzida de volta para prosa — zero informação nova sobre o negócio
do cliente. O texto forte nunca tem o gráfico como sujeito: o sujeito é a
situação do negócio ("três fornecedores concentram..."), e a frase carrega
uma implicação — "é aqui que X tem alavancagem" — que só faz sentido para
quem sabe o que renegociação de fornecedor custa e vale **neste** setor.
É esse segundo passo, do dado para a implicação, que exige entender o
negócio do cliente — e é exatamente esse passo que Power BI e Qlik não
entregam de fábrica.

O overlay respeita a mesma fronteira de `forma-sem-magnitude.md`: "três
fornecedores concentram a maior parte" é forma (contagem, concentração
relativa), não magnitude — nenhum percentual real, nenhum nome de fornecedor
real entra na frase. Overlay que vaza um número ou nome plausível quebra as
duas regras ao mesmo tempo (blandness E magnitude), não é dispensa de uma
pela outra.

## 4. Densidade: um overlay por tela, não por widget

"Explicar o porquê de cada coisa" e "não parecer feito por engenheiros"
competem por padrão: anotação densa — um bloco de texto explicando cada
widget — é a assinatura visual de documento técnico, exatamente o registro
que esta skill existe para não produzir (`wireframe-kit.md` já rejeita a
estética "caixa cinza com ícone" pelo mesmo motivo). Uma decisão por tela é
pouco texto e muito valor; uma explicação por widget é muito texto e pouco
valor, e ainda assim consegue ser bland, porque a tentação natural de
preencher seis caixas de texto é recair em descrição.

Isso não elimina a trilha de anotação numerada (①②) que `wireframe-kit.md`
já define no `.wf-annot` lateral — aquela trilha documenta decisão de
encoding (`datalabels: sim`, "clique filtra os widgets seguintes") e
continua existindo widget a widget. O overlay é um elemento **novo e
distinto**, de tela inteira, que não substitui a trilha nem vira mais uma
linha dela — é o único lugar da tela que fala de decisão de negócio em vez
de decisão de design. Onde exatamente ele se encaixa no HTML (posição,
classe CSS) é decisão de composição de `wireframe-kit.md`, não desta
referência; o que este arquivo garante é que existe exatamente UM, nunca um
por widget, e que ele nunca é confundido com o banner de dados ilustrativos
(esse é aviso de conformidade, o overlay é conteúdo comercial).

## 5. O filtro anti-blandness — procedimento verificável

**Regra dura:** se o texto do overlay funcionaria, sem alterar uma palavra,
para outro cliente de outro setor, ele está errado e não pode ser
renderizado. Blandness é o modo de falha default de narrativa automatizada
— e narrativa genérica em cima de gráfico bonito é **pior** que nenhuma
narrativa: sinaliza template, e o cliente sente.

Isto não é "não seja genérico" solto — é um teste de saída, roda-se contra
o texto já escrito, antes de renderizar. Qualquer "sim" abaixo reprova o
overlay; volte ao §2 e reescreva a partir de `pergunta:` +
`decisoes_que_suporta:`, não poliu a mesma frase.

1. **Teste da inversão do achado.** Pegue a `mensagem:` real que sustenta o
   overlay e inverta o achado (concentrado ↔ pulverizado, subindo ↔ caindo,
   presente ↔ ausente). O overlay continua fazendo sentido, palavra por
   palavra, sem nenhum ajuste? **Sim → reprova.** Um overlay que sobrevive
   inteiro à inversão do dado nunca dependeu do dado — só do rótulo do
   gráfico, igual ao exemplo fraco do §3. Cuidado com um atalho enganoso
   aqui: trocar só os **substantivos de setor** do texto (fornecedor →
   paciente, safra → ciclo) por outro setor e a frase continuar gramatical
   **não** é reprovação por si — isso é esperado, "fornecedor" e "compra"
   são vocabulário do próprio domínio de compras/suprimentos, não sinal de
   blandness. O que reprova é o texto sobreviver **à inversão do achado**,
   não à troca de vocabulário.
2. **Teste do verbo-fantasma.** O verbo principal da frase é da família
   "mostra" / "exibe" / "apresenta" / "permite acompanhar" / "possibilita a
   visualização de" / "traz uma visão de" — verbo que descreve o que o
   **olho** faz ao ver o gráfico, não o que a **mão** faz ao decidir? **Sim
   → reprova.** (Lista de bandeira vermelha completa no §6.)
3. **Teste da decisão nomeada.** Existe, na frase, um substantivo de
   decisão/ação concreto e ligado a uma alavanca real (renegociação,
   corte, priorização, investimento, risco, gargalo, concentração perigosa,
   janela de oportunidade, ponto de atenção) — não apenas um substantivo de
   dado (evolução, comportamento, distribuição, comparação)? **Não existe
   nenhum → reprova.**
4. **Teste "isso já era óbvio olhando".** Um executivo que já está olhando o
   gráfico aprenderia algo que a codificação visual sozinha (eixo, barra,
   ordenação) não entregou, ou a frase só reafirma em palavras o que o
   próprio desenho já mostrava? **Só reafirma → reprova.**
5. **Teste da origem.** A decisão nomeada na frase aparece, em substância,
   em `decisoes_que_suporta:` da ficha do dashboard (§2)? **Não aparece →
   reprova** — isso é invenção de decisão fora da ficha, o
   defeito irmão que o §2 já cobre; mesma consequência prática: não
   renderiza, volta para a `lumo-scope`.

Um overlay só passa se sobreviver aos cinco testes. Isto não é arredondado
para "a maioria passa" — um único "sim" nos testes 1-4, ou um "não" no
teste 5, é reprovação total do texto, não um ajuste de nota.

## 6. Vocabulário de bandeira vermelha (pré-filtro mecânico)

Antes de rodar o §5 frase a frase, uma varredura rápida: se o overlay contém
qualquer um destes fragmentos (ou tradução óbvia deles), ele quase certo
falha o teste 2 e vale reescrever direto, sem nem chegar ao teste completo:

> "permite acompanhar a evolução de", "mostra os dados de", "apresenta o
> comportamento de", "exibe a comparação entre", "possibilita a
> visualização de", "traz uma visão consolidada de", "permite identificar
> tendências", "facilita o entendimento de", "oferece uma análise de"

Esta lista não é exaustiva por design — memorizar uma lista fixa é o
próprio caminho para blandness genérica disfarçada (trocar "permite
acompanhar" por sinônimo igualmente vazio ainda reprova no teste 2). Use a
lista como atalho de reconhecimento, o §5 como veredito final.

## 7. Exemplo de par completo (domínio de compras/suprimentos)

Para fixar o padrão antes de escrever o primeiro overlay de verdade — um
dashboard de compras de indústria, tela com ranking de fornecedores por
volume de compra e tendência de preço médio:

- **`pergunta:`** "Onde a área de compras tem alavancagem de negociação
  hoje?"
- **`decisoes_que_suporta:`** ["renegociar contrato com fornecedor
  concentrado", "diversificar base para reduzir dependência", "priorizar
  auditoria de preço nos itens de maior volume"]
- **Overlay fraco (reprova no teste 2 e 4):** "Este dashboard permite
  acompanhar a evolução das compras por fornecedor ao longo do tempo."
- **Overlay forte (passa nos 5 testes):** "A compra está concentrada em
  poucos fornecedores — é aí, não no preço unitário médio, que sobra
  alavancagem de negociação real."

Note que o overlay forte nomeia a primeira decisão de
`decisoes_que_suporta:` (renegociação com fornecedor concentrado),
não uma lista das três — essa é a densidade do §4 em ação.
