# Marcadores de confiança — vocabulário vestido, por vista e por modo

## Conteúdo

- 1. As duas incógnitas, e por que a maior nunca é a magnitude
- 2. A regra dura: a etiqueta crua nunca sai daqui
- 3. Vista ≠ modo — duas dimensões independentes
- 4. Vocabulário mestre — nível de confiança × vista
- 5. Modo — o mesmo texto, dois registros, nunca dois desenhos
- 6. O caso especial: estrutura confirmada, conteúdo pendente de carga
- 7. Conexão com o placeholder — dois mecanismos, não um
- 8. Onde o marcador mora no widget
- 9. Convive com "Perguntas para o Cliente", não substitui

Leia ANTES de renderizar qualquer widget cuja ficha carregue `confianca:`
diferente de `confirmado`. Este arquivo não define a camada de confiança —
ela já existe, completa, em `lumo-scope:references/incognitas.md` (os 3
níveis, os 4 subcampos de `confirmado`, o schema de 8 campos do registro de
incógnita) e em `lumo-scope:references/documento-template.md` (a
mecânica de vista crua/vestida do bundle). Este arquivo **traduz** esse
vocabulário para o widget do mockup — nunca o redefine.

## 1. As duas incógnitas, e por que a maior nunca é a magnitude

Todo mockup carrega duas incertezas de naturezas diferentes:

- **Magnitude** — o valor do KPI, a escala do eixo. É a incerteza pequena:
  ninguém espera número real antes da assinatura (`forma-sem-magnitude.md`).
- **Existência** — o campo pode não estar no banco do cliente, ou estar mal
  preenchido, ou a regra de negócio por trás da métrica ainda não foi
  validada com ninguém. É a incerteza grande: é dela que vem retrabalho e
  over-delivery no fim do projeto — o cliente aprovou um widget que dependia
  de um campo que ninguém verificou.

A saída é **o mockup renderizar a própria camada de confiança**. Cada widget
carrega um marcador visível do que é confirmado, do que é proposta a
validar, e do que depende de verificação — nunca a etiqueta técnica crua.

| Objetivo | Como este arquivo atende |
|---|---|
| WOW na proposta | tela continua acabada, marca Horus, gráfico bem escolhido — o marcador nunca vira caixa cinza |
| Menos ruído na entrega | o cliente assinou sabendo quais widgets dependiam de verificação |
| Proteger a equipe | campo que não existe deixa de ser retrabalho e vira risco declarado e aceito |

**Sem marcadores, beleza = promessa. Com marcadores, beleza = proposta com
risco declarado.**

## 2. A regra dura: a etiqueta crua nunca sai daqui

Nenhum destes tokens — nem o nome do campo, nem o valor — pode aparecer,
literalmente, em qualquer artefato que o cliente lê (HTML de mockup, PDF,
DOCX, print de apresentação):

`confianca:` · `confirmado` · `hipótese` · `a-perguntar` · `dono:` ·
`gatilho:` · `validado_por:` · `evidencia:`

Isto vale mesmo quando o texto "soa técnico mas não é bem a palavra" — ex.:
"este campo está em nível hipótese" é tão proibido quanto o YAML cru, porque
o cliente não faz ideia do que "nível hipótese" significa dentro do
vocabulário desta skill. O teste é "um
controller/CFO que nunca leu `incognitas.md` entenderia isto sem
explicação?" — se a resposta exige explicar o jargão, a frase falhou.

`confirmado` é o único nível que nunca precisa de tradução: ele **é**
afirmação direta, sem qualificador (`documento-template.md`) — não existe
"palavra vestida para confirmado" porque não há nada para vestir.

## 3. Vista ≠ modo — duas dimensões independentes

É fácil confundir os dois porque ambos usam a palavra "termo". São eixos
diferentes, e um widget escolhe um valor em cada:

| Eixo | Pergunta que responde | Valores | O que muda |
|---|---|---|---|
| **vista** | Para quem, e com que objetivo, este artefato existe? | `comercial` \| `termo` | **posicionamento** — o ângulo de enquadramento da mesma informação |
| **modo** | Em que momento do ciclo de iteração este render está? | `rascunho` \| `termo` | **registro** — convite a corrigir vs. leitura definitiva |

- **Vista** vem da arquitetura de três vistas do bundle
  (`documento-template.md`): crua (interna, nunca sai da `lumo-mockup`),
  comercial (pré-venda, ganhar o deal) e termo (o documento que o cliente
  assina, blindar o dimensionamento). Muda **o que a frase enfatiza**.
- **Modo** vem do corolário de "uma ficha → N renderizações": o mesmo
  conteúdo, gerado no meio de uma rodada de ajuste com o analista
  (`rascunho`) ou no momento em que o artefato vai para assinatura
  (`termo`). Muda **o registro de tom da mesma frase**, nunca o conteúdo
  nem a aparência do widget — a mecânica de geração (como uma ficha vira N
  arquivos) é de `references/pipeline.md`; este arquivo só garante o texto
  certo em cada combinação.

Sim, "termo" é valor válido nos dois eixos ao mesmo tempo, e não é acidente:
o documento de termo, quando está sendo iterado antes da assinatura, é
`vista: termo` + `modo: rascunho`; quando é o PDF que o cliente assina, é
`vista: termo` + `modo: termo`. A proposta comercial segue a mesma lógica —
`vista: comercial` + `modo: rascunho` enquanto ainda se ajusta a tela,
`vista: comercial` + `modo: termo` na versão final enviada ao comprador.

**Vista crua nunca aparece aqui.** É a navegação interna do bundle YAML —
o analista lendo `dashboards/*.md` direto, ou a `lumo-cli` decidindo o que
já pode virar spec. A `lumo-mockup` só produz vestida (comercial/termo); se
alguém pedir "me mostra o YAML cru dentro do mockup", a resposta é não —
isso é o bundle, não o render.

## 4. Vocabulário mestre — nível de confiança × vista

Wording de referência, no registro `modo: termo` (definitivo — ver §5 para
a transformação de `modo: rascunho`). Adapte a métrica/dimensão real de
cada widget; o que não muda é a estrutura da frase.

| Nível cru | Vista comercial (ganhar o deal) | Vista termo (blindar o dimensionamento) |
|---|---|---|
| `confirmado` | *(sem marcador — silêncio é o marcador; ver §2)* | *(sem marcador)* |
| `hipótese` | "Proposta técnica da Horus para este indicador — validação incluída no kickoff do projeto." | "Premissa de trabalho para este indicador, pendente de validação com o cliente." |
| `a-perguntar`, `dono: cliente` | "Detalhe de negócio que fechamos com vocês no kickoff." | "Depende de confirmação do cliente antes do go-live — ver Perguntas para o Cliente." |
| `a-perguntar`, `dono: precisa-acesso-banco` (ou o caso especial do §6) | "Diagnóstico de disponibilidade de dado incluído no projeto." | "Depende de verificação técnica na base do cliente." |
| `a-perguntar`, `dono: analista` | *(não deveria chegar ao mockup — ver nota abaixo)* | *(idem)* |

Notas de leitura da tabela:

- **`confirmado` fica em silêncio de propósito.** Cobrir todo widget com um
  selo de "OK" seria ruído visual constante e contradiz o alvo "projetado,
  não glossy" de `identidade-visual.md` §8 — a ausência de marcador já
  comunica confiança, do mesmo jeito que as duas vistas vestidas do
  documento (comercial e termo — `documento-template.md`) tratam
  `confirmado` como "afirmação direta, sem qualificador".
- **A coluna comercial reposiciona, nunca esconde.** "Diagnóstico de
  disponibilidade de dado incluído no projeto" é a mesma lacuna que a
  coluna termo chama de "depende de verificação técnica" — só que
  enquadrada como trabalho que a Horus já embutiu no escopo, não como
  buraco. É decisão consciente de posicionamento, não suavização: numa
  proposta, um marcador de dúvida cru pode custar o
  negócio contra um concorrente que promete tudo sem verificar; a saída é
  reposicionar, não silenciar.
- **`dono: analista` não deveria aparecer no mockup.** Por definição
  (`incognitas.md`), esse tipo de lacuna se resolve na própria entrevista,
  antes da ficha chegar à `lumo-mockup`. Se um widget ainda carrega
  `confianca: a-perguntar` com `dono: analista` na hora de renderizar, isso
  é sinal de que a entrevista não fechou — a saída correta é voltar para a
  `lumo-scope`, não inventar uma frase vestida para tapar o buraco.

## 5. Modo — o mesmo texto, dois registros, nunca dois desenhos

`modo: termo` é a forma da tabela do §4, como está escrita: declarativa,
sem pergunta, sem convite — é o que cabe num documento que alguém assina.

`modo: rascunho` aplica uma transformação sobre a mesma frase: acrescenta
uma cláusula de convite à correção, porque é isso que uma rodada de
iteração existe para fazer. Não é uma frase nova — é a mesma base do §4 com
um fecho diferente:

| Frase-base (§4, modo termo) | Mesma frase, modo rascunho |
|---|---|
| "Proposta técnica da Horus para este indicador — validação incluída no kickoff do projeto." | "Proposta técnica da Horus para este indicador — faz sentido pra vocês, ou querem ajustar algo aqui?" |
| "Premissa de trabalho para este indicador, pendente de validação com o cliente." | "Premissa de trabalho para este indicador — nos digam se isso não bate com a realidade de vocês." |
| "Detalhe de negócio que fechamos com vocês no kickoff." | "Detalhe de negócio a alinhar — é isso mesmo que vocês tinham em mente?" |

**O que NÃO muda entre os dois modos: a aparência do widget.** Nenhuma
borda tracejada, nenhum estilo "rascunhado", nenhuma fonte diferente — isso
reintroduziria exatamente a tese que `wireframe-kit.md` já rejeitou (a
ideia de que estética inacabada convida crítica melhor, atribuída à SILK,
CHI '95, e descartada porque a fonte original chama a própria evidência de
"anecdotal"). O widget em `modo: rascunho` é tão acabado quanto em
`modo: termo` — muda o **fecho da frase do marcador**, não o desenho ao
redor dela. "Mesmo conteúdo, dois registros" significa exatamente isto:
registro de tom, não de acabamento.

## 6. O caso especial: estrutura confirmada, conteúdo pendente de carga

`incognitas.md` (seção "Estrutura ≠ conteúdo na promoção") já cobre o caso
em que um widget tem `confianca: confirmado` no nível de **estrutura**
(o cliente aprovou o layout, quais widgets, que perguntas) mas o
**conteúdo** — os números vão bater quando a carga rodar — ainda não tem
profiling real por trás. Esse caso não é capturado pela leitura ingênua da
tabela do §4 (que leria `confirmado` = silêncio): antes de decidir que um
widget fica mudo, verifique se o `evidencia` da ficha aponta para um `id`
de `escopo/incognitas.md` ainda em `a-perguntar` com
`dono: precisa-acesso-banco`. Se apontar, o widget carrega o marcador da
linha "`a-perguntar`, `dono: precisa-acesso-banco`" do §4 mesmo com
`confianca: confirmado` na própria ficha — a checagem do `evidencia` vale
mais que o valor superficial do campo, porque é exatamente esse
descolamento (estrutura aprovada relatada como "estrutura E conteúdo
aprovados") que o caso PADO documenta como incidente real.

## 7. Conexão com o placeholder — dois mecanismos, não um

`forma-sem-magnitude.md` §0 já resolve "como mostrar um número sem inventar
valor": o **placeholder sequencial fixo** (`R$ 123.456,78`, o mesmo em todo o
widget), presente em todo widget do mockup **independente do nível de
confiança**. Mesmo um KPI `confirmado` mostra placeholder, porque nenhum widget
do mockup carrega número real antes da assinatura.

Repare no que cada mecanismo declara, porque são coisas diferentes:

| Mecanismo | Declara |
|---|---|
| placeholder | a ausência de **valor medido** |
| marcador deste arquivo | a ausência de **confiança na definição** da métrica |

Um widget pode ter definição fechada e valor inexistente (o caso comum: mostra
placeholder e nenhum marcador), ou pode ter os dois em aberto (mostra
placeholder **e** marcador).

O marcador só aparece quando o nível de confiança é `hipótese` ou
`a-perguntar`, e ele nunca substitui o placeholder: convive com ele. Um widget
de `metrica-unica` em `hipótese` mostra os dois ao mesmo tempo, o placeholder
no slot do valor e o texto do §4/§5 no slot `helper` do `KpiV2`, explicando por
que o próprio indicador ainda está em validação.

**Um caso em que o marcador é o único sinal:** quando a métrica não tem âncora
nem default de escala, `forma-sem-magnitude.md` §2b manda usar a faixa cinza
(slab) em vez de placeholder, e registrar a incógnita aqui. Aí o marcador não é
opcional, é o que explica ao cliente por que aquele widget está diferente dos
outros.

## 8. Onde o marcador mora no widget

Reusa as variáveis CSS que `wireframe-kit.md` já define
(`--bg`, `--ink`, `--sub`, `--line`) — nenhuma cor nova. O texto do
marcador usa `var(--sub)` (`#393833`, grafite quente — já validado a
10.03:1 contra o fundo em `identidade-visual.md` §4c, o mesmo token que
rotula eixo e legenda); a borda superior usa `var(--line)`, chrome
decorativo, mesmo papel que já tem no kit.

```css
.wf-confidence {
  font-size: 11px;
  line-height: 1.35;
  color: var(--sub);
  border-top: 1px dashed var(--line);
  margin-top: 6px;
  padding-top: 4px;
}
```

```html
<div class="hb-card" style="grid-column:span 3; grid-row:span 3">
  <span class="wf-n">2</span>
  <div class="hb-kpi">
    <div class="hb-kpi__icon">📉</div>
    <div>
      <div class="hb-kpi__over">Churn de Clientes — mês</div>
      <div class="hb-kpi__val">12,3%</div>
      <div class="hb-kpi__help">Premissa de trabalho para este indicador, pendente de validação com o cliente.</div>
    </div>
  </div>
</div>
```

`.wf-confidence` nunca substitui o corpo do widget (o gráfico Vega-Lite
real, ou a slab do KPI) — é um rodapé de widget, na mesma família visual
do trilho de anotações (`.wf-annot`), só que preso ao próprio card, não ao
lado da tela. A borda tracejada é a única concessão a "isto é uma nota", e
ela mora no separador interno do card — nunca na borda externa do widget
(`.wf-w` continua sólida nos dois modos, ver §5).

## 9. Convive com "Perguntas para o Cliente", não substitui

`documento-template.md` já define que todo registro `a-perguntar` com
`dono: cliente` sai do corpo do documento e reaparece consolidado na seção
"Perguntas para o Cliente" (`pergunta_cliente`, pronto para enviar). Isso
não contradiz a regra de `wireframe-kit.md` de que "widget cuja métrica
ainda não foi validada nunca desaparece do mockup" — são dois canais
complementares, não um substituindo o outro:

- **No corpo do mockup**, o widget continua no grid, com o gráfico real
  (dado sintético de forma) e o marcador deste arquivo na posição dele —
  remover o widget pareceria que o escopo foi cortado, quando na verdade
  ele está incluído e só depende de confirmação.
- **Na seção consolidada**, o mesmo registro contribui sua
  `pergunta_cliente` para a lista única do documento — é dali que sai o
  "o que especificamente precisamos que vocês respondam", pronto para
  enviar, sem repetir a redação em cada lugar onde a incógnita aparece.

Quem lê o marcador do widget e quer o texto exato da pergunta encontra os
dois no mesmo bundle — o marcador aponta "isto depende de vocês", a seção
consolidada carrega o "isto, especificamente, é o que perguntamos".
