# Incógnitas — camada de confiança e registro de incógnita

## Conteúdo

- Os 3 níveis de confiança
- Como um campo carrega a etiqueta
- Schema do registro de incógnita
- Perguntas para o Cliente — geração automática

Este arquivo define o vocabulário-base do bundle: como cada campo declara o
quanto se confia nele, e como uma lacuna vira um registro rastreável em vez de
um `[TBD]` solto ou uma nota de rodapé. Todo outro arquivo da skill referencia
este vocabulário — a etiqueta de confiança e o schema de incógnita nascem
aqui.

## Os 3 níveis de confiança

Cada campo do bundle carrega uma etiqueta de confiança, em exatamente **3
níveis** — não é uma escala contínua nem um binário validado/ausente:

| Etiqueta | Significado | Origem típica |
|---|---|---|
| `confirmado` | validado com fonte/pessoa nomeada | resposta explícita do analista/cliente, evidência no banco |
| `hipótese` | assumido de forma defensável, a validar | destilação de documento, padrão do vertical, recomendação da skill |
| `a-perguntar` | lacuna conhecida, ninguém sabe ainda | pergunta de implementação sem resposta disponível no início |

**Sem limite, sem cota.** Não existe teto de quantos campos do bundle podem
estar em `hipótese` ou `a-perguntar` num dado momento — um documento pode ter
90% do inventário em `hipótese` no dia 1 e ainda ser um bundle válido para
seguir trabalhando. A etiqueta troca o binário "validado vs buraco" por um
espectro: o documento incompleto vira informação estruturada, não motivo de
bloqueio.

**Só `confirmado` exige rastro.** Os outros dois níveis não pedem nada além
da própria hipótese ou pergunta, escrita. `confirmado` exige 4 subcampos:

| Subcampo | O que registra |
|---|---|
| `validado_por` | pessoa nomeada (nunca "o comercial", "a diretoria", "cliente"). **Para as 4 decisões que congelam schema (grão, chave de negócio, tipo de carga, RLS): o próprio analista da Horus relatando a si mesmo ("analista via chat") NÃO promove a `confirmado`** — precisa de pessoa nomeada do lado do cliente, ou fica `hipótese` mesmo com profiling técnico (o profiling prova unicidade de chave, não a decisão de negócio do grão). |
| `validado_em` | data da validação |
| `canal` | onde aconteceu (call, e-mail, mensagem, select de exemplo) |
| `evidencia` | o que prova — trecho de transcrição, print, resultado de query |

Faltando qualquer um dos 4, o campo não é `confirmado`: cai para `hipótese`
(se ainda for defensável) ou `a-perguntar` (se não há base nenhuma).

### Estrutura ≠ conteúdo na promoção

Uma aprovação de layout ("confere", "aprovado, segue") promove a **estrutura**
do dashboard (quais widgets, que perguntas), nunca o **conteúdo** (que os números
são reais/válidos). Regra dura: **se o fato/tabela por trás não tem profiling real
registrado (carga que rodou, volumetria conhecida), a promoção de "conteúdo" a
`confirmado` é proibida** — só "estrutura" pode ser `confirmado`. Caso PADO:
Faturamento (flow de carga nunca executado) recebeu "estrutura E conteúdo
aprovados" — reivindicação mais forte que Metas/Margem, registrados no mesmo
vazio evidencial mas sem essa afirmação extra.

Isso não abre um par de campos novo (`estrutura:`/`conteudo:`), nem duplica
`confianca:` dentro do mesmo conceito. Reusa o mecanismo que este arquivo já
define: o dashboard promove normalmente (`confianca: confirmado`), mas o
`evidencia` tem de dizer explicitamente que o que foi aprovado é a estrutura
— e a dependência de dado que ficou de fora vira **um registro de incógnita**
(schema de 8 campos, seção acima), com `dono: precisa-acesso-banco` e
`gatilho` citando a carga que falta rodar. O `evidencia` do dashboard aponta
para o `id` desse registro: quem lê o campo do dashboard sempre acha o resto
da história, em vez de a ressalva morrer escondida numa frase solta dentro
do próprio `evidencia`.

Exemplo canônico — o caso PADO acima, nos dois lados do bundle:

```yaml
# dashboards/faturamento.md — campo de confiança do dashboard
confianca: confirmado
validado_por: "Ricardo Prado — Gerente Comercial"
validado_em: "2026-06-30"
canal: "call de apresentação do mockup"
evidencia: "aprovação cobre ESTRUTURA (widgets, perguntas) — cliente disse
  'confere' olhando o layout, não validou nenhum número. Conteúdo depende de
  carga real: ver incógnita fato-faturamento-sem-carga"
```

```yaml
# escopo/incognitas.md — registro de incógnita correspondente
- id: fato-faturamento-sem-carga
  campo: dashboards/faturamento.md#confianca
  hipotese: "os números do dashboard de Faturamento batem com a fonte quando
    a carga rodar pela primeira vez"
  confianca: a-perguntar
  dono: precisa-acesso-banco
  gatilho: "lumo flow logs flow:<id-do-flow-faturamento> mostrar ao menos 1
    execução — hoje o flow nunca rodou, log vazio"
  pergunta_cliente: null   # dono: precisa-acesso-banco — resolve rodando a
                            # carga e conferindo o profiling, nunca pergunta
                            # ao cliente final
  risco_se_errar: "dashboard sai do go-live com 'estrutura E conteúdo
    aprovados' registrado, sem nenhum número real por trás — cliente
    descobre a divergência sozinho depois"
```

Verificação mínima de "carga que rodou": `lumo flow logs flow:<id>` sem
nenhuma execução retornada — o flow nunca rodou, essa é a condição
observável que falta, não uma opinião do analista. (No relato do caso PADO,
"`last_log: null`" foi só a notação usada para descrever essa condição no
relatório — não é campo de `tabelas/*.md` nem saída real de `lumo flow
logs`.)

## Como um campo carrega a etiqueta

Convenção de YAML nos arquivos do bundle: todo campo sujeito a confiança leva
`confianca:` como irmão direto do valor, mais `origem:` explicando de onde
veio a hipótese — em `confirmado`, os 4 subcampos da seção anterior tomam o
lugar de `origem`.

Exemplo canônico:

```yaml
grain:
  frase: "um item de cada pedido de venda"
  confianca: hipótese
  origem: "destilado da proposta comercial (insumos/proposta.pdf)"
```

O mesmo campo, depois de validado com o analista:

```yaml
grain:
  frase: "um item de cada pedido de venda"
  confianca: confirmado
  validado_por: "Marcos Aurélio — Diretor Comercial"
  validado_em: "2026-07-20"
  canal: "call de kickoff"
  evidencia: "transcrição min 12:40 — confirma grain de item, não de pedido"
```

A etiqueta viaja com o campo, não com o arquivo inteiro: um mesmo arquivo do
bundle normalmente tem campos em níveis de confiança diferentes lado a lado.

## Schema do registro de incógnita

Uma lacuna não vira nota de rodapé nem `[TBD]` solto — vira um registro
estruturado, no formato RAID/assumptions log, com 8 campos fixos:

```yaml
- id: cancelamento-pedido
  campo: metricas/receita.md#inclusoes
  hipotese: "pedidos com status 'CANCELADO' NÃO entram na receita"
  confianca: a-perguntar
  dono: cliente            # ou: analista, precisa-acesso-banco
  gatilho: "confirmar em transcrição de call OU select de exemplo OU acesso ao banco na esteira"
  pergunta_cliente: "Um pedido cancelado deve contar na receita? Em que status ele sai da conta?"
  risco_se_errar: "métrica de receita infla; recalcular após carga"
```

| Campo | O que registra |
|---|---|
| `id` | identificador curto, slug, único no bundle |
| `campo` | ponteiro para o campo do bundle que a incógnita afeta (`arquivo.md#âncora`) |
| `hipotese` | a suposição de trabalho — o que a skill assume até ser corrigida |
| `confianca` | um dos 3 níveis acima — normalmente `hipótese` ou `a-perguntar` |
| `dono` | quem resolve: `analista` \| `cliente` \| `precisa-acesso-banco` |
| `gatilho` | texto livre, mas sempre citando a fonte de resolução (transcrição de call, select de exemplo, acesso ao banco na esteira) |
| `pergunta_cliente` | a pergunta fechada/objetiva, pronta para enviar, quando `dono: cliente` |
| `risco_se_errar` | consequência concreta de manter a hipótese errada — o que quebra, o que precisa recalcular |

Incógnitas vivem em `escopo/incognitas.md` no bundle do cliente — um registro
por lacuna, lista plana, sem agrupamento por fase ou gate.

## Perguntas para o Cliente — geração automática

A skill agrega automaticamente todo registro de `escopo/incognitas.md` com
`dono: cliente` numa lista de perguntas fechadas/objetivas — o
`pergunta_cliente` de cada um, pronto para enviar, sem reescrever nada na
hora de despachar.

**Regra de nascimento:** pergunta de implementação (ex.: "como um pedido é
considerado cancelado", semântica de status, regra de corte de data) nasce
como registro `a-perguntar`, **nunca** é feita ao analista no início da
entrevista. O analista responde sobre o negócio dele; o cliente final (ou o
banco de dados) responde sobre a implementação de dados dele. Misturar as
duas sobrecarrega a entrevista com perguntas que o analista não tem como
responder e atrasa a produção do documento à toa.

Registros com `dono: analista` ou `dono: precisa-acesso-banco` não entram
nesta lista: o primeiro se resolve na própria entrevista (é sobre o
processo de negócio, não sobre a implementação), o segundo é tarefa do
profiling da fonte ou de quem tem acesso ao banco — não pergunta a mandar
para o cliente.

**Antes de pendurar em `dono: cliente`, cheque se é `dono: precisa-acesso-banco`
que a skill resolve sozinha AGORA.** Se a resposta está a um `lumo columns`/
`lumo credential schema` de distância (ex.: "a carteira tem Cliente?" quando um
fato-irmão da mesma chave de negócio já expõe `CLI_ID`), NÃO nasce pergunta ao
cliente: a skill roda a checagem e resolve. Perguntar ao cliente o que o schema
já responde é o princípio 5 ao contrário (defeito PADO: `cliente-e-vinculo-carteira`
pendurado no cliente com `CLI_ID` visível num `lumo columns` de 100 turnos antes).
