# Validação adversarial — gates A/B/C com revisores de contexto limpo

## Conteúdo

- Vocabulário de achado (todas as lentes)
- Mapa dos gates
- Gate A — Pós-entrevista
  - A1 — Revisor de Modelo Dimensional (Kimball estrito)
- Por que isso importa
- Leia primeiro
- Revise: <caminhos do bundle>
- O que checar
- Calibração
- Saída
  - A2 — Revisor "Implementador lumo-cli" (variante *fundação*)
- Leia primeiro
- Revise: <caminhos do bundle>
- O que checar
- Calibração
- Saída
- Gate B — Pós-wireframe
  - B1 — Implementador (*dashboards*): delta sobre A2
- Leia também: lumo-mockup:references/wireframe-kit.md (ficha antes do gráfico; integridade)
- Checar (além do A2):
  - B2 — Advogado do Fora-de-Escopo (1ª passada)
- Gatilhos de pedido-fantasma
- Calibração
- Gate C — Pré-sign-off
  - C1 — Cliente Cético
- Revise: SOMENTE escopo/termo-abertura.pdf
- Calibração
  - C2 — Advogado do Fora-de-Escopo (2ª passada): delta sobre B2
  - C3 — Implementador (*bundle completo*): delta sobre A2
  - C4 — Kimball condicional: delta sobre A1

**Estes revisores são um checkpoint que você aciona — não bloqueiam o fluxo.**
Use quando fizer sentido: ao fechar um processo de negócio, antes do
wireframe que depende dele; ao fechar a rodada de wireframe, antes de montar
o bundle final; ou antes de pedir aprovação do cliente. Em escopo simples,
com cliente já muito conhecido, pode não valer a pena acionar os quatro; em
projeto grande ou com muita coisa nova, é onde um erro de grain ou um
pedido-fantasma custa achar agora — antes de a tabela ter dados, não depois.

Quem valida o escopo **nunca é quem o escreveu**. Ao acionar um gate, você
dispara subagentes novos (`general-purpose`, Sonnet — julgamento de domínio,
não skim) que recebem **apenas caminhos de arquivo do bundle** — nunca a
transcrição da entrevista, nunca o seu raciocínio sobre "o que o analista
quis dizer". Se uma decisão não está escrita no bundle, para o revisor ela
não existe — e é esse o teste: se o revisor não reconstrói a decisão lendo o
arquivo, o lumo-cli (meses depois) também não vai.

Revisores de um mesmo gate, quando acionados, rodam **em paralelo**. Todos
são somente-leitura: podem rodar `lumo list/info/columns/credential
schema/query` para checar uma afirmação contra o workspace real; jamais
`new/push/scaffold/run-node/sync-table/publish`.

## Vocabulário de achado (todas as lentes)

- **Crítico** — problema que, deixado como está, tende a custar caro depois:
  schema que só se corrige com drop+recreate, cláusula que o cliente assina
  sem entender, suposição que a implementação vai herdar sem saber que era
  suposição. O caminho mais seguro normalmente é resolver antes de seguir —
  mas a decisão de seguir mesmo assim, com o risco registrado, é do
  analista/dono, não automática.
- **Importante** — vale registrar e endereçar, mas não trava nada sozinho:
  cada ressalva vira registro escrito — registro `a-perguntar` com dono e
  gatilho (ver `incognitas.md`), linha em `fora-de-escopo.md`, ou risco em
  `projeto.md` — nunca fica solta no texto da revisão.
- **Aprovado** — sem achados que mudem o documento.

**Escalonamento:** o mesmo achado Crítico reaparecendo depois de uma correção
(2ª rodada do mesmo gate) não pede uma 3ª rodada automática — vira decisão
direta do analista/dono: aceitar o risco registrado, ou resolver de outro
jeito.

**Trilha:** todo despacho gera entrada append-only em `escopo/revisoes.md`
(`type: review-log`): gate, lente, data, achados e resolução — mesmo quando o
achado foi aceito como risco registrado em vez de corrigido.

## Mapa dos gates

| Gate | Bom momento pra acionar | Lentes | O que evita descobrir tarde |
|---|---|---|---|
| **A — Pós-entrevista** | ao fechar cada processo de negócio (critério de parada da entrevista), antes do wireframe que depende dele | Modelo Dimensional (Kimball) · Implementador lumo-cli (*fundação*) | retrabalho de wireframe em cima de grain errado |
| **B — Pós-wireframe** | todos os dashboards da rodada aprovados pelo analista, antes de montar o bundle final | Implementador (*dashboards*) · Advogado do Fora-de-Escopo (1ª) | pedido-fantasma do cliente / falha de integridade visual chegando no PDF |
| **C — Pré-sign-off** | depois do auto-review mecânico do documento, antes de apresentar ao cliente | Cliente Cético (só o PDF) · Advogado do Fora-de-Escopo (2ª) · Implementador (*bundle completo*) · Kimball condicional (se tabelas/métricas mudaram desde o Gate A) | cláusula que o cliente assina sem entender / suposição que sobra pra execução |

As lentes cobrem as óticas que valem sair satisfeitas do projeto: técnica-
dimensional (Kimball), executabilidade (Implementador), hierarquia de informação
e integridade visual (Implementador-dashboards, herdando as regras de
`wireframe-kit.md` da skill `lumo-mockup`), valor de
negócio vs data-vanity (Kimball checa `pergunta`/`decisao_associada` do KPI card;
Cliente Cético checa se o valor é dizível em uma frase), performance/custo de
pipeline (Implementador checa load type vs volumetria da evidência), contrato e
linguagem (Cliente Cético), e escopo futuro (Advogado do Fora-de-Escopo).

---

## Gate A — Pós-entrevista

Insumos: `projeto.md`, `processos/<p>.md`, `tabelas/*.md` e `metricas/*.md` do
processo, `lineage.md`, `fora-de-escopo.md`. **Nunca a conversa.**

### A1 — Revisor de Modelo Dimensional (Kimball estrito)

```
Você é um modelador dimensional Kimball sênior, cético por ofício. Você nunca
participou da entrevista nem viu a conversa — julgue SOMENTE pelo que está
escrito nos arquivos. Se uma decisão estrutural não está escrita e evidenciada,
ela NÃO EXISTE, por mais razoável que pareça.

## Por que isso importa
No Lumo, o schema de uma tabela DW congela na criação. Grain errado, chave
errada ou aditividade mal classificada não se corrige — se reconstrói (drop +
recreate + reload). Ache agora tudo que só apareceria quando fosse tarde.

## Leia primeiro
- references/entrevista.md (KPI card, taxonomia de armadilhas)
- references/fonte-profiling.md (formato de evidência)
- references/sizing-change-control.md (mudança de grain)
- references/limites-horus.md (limites do motor Horus — fanout, fato mestre, SCD2)

## Revise: <caminhos do bundle>

## O que checar
| Categoria | Pergunta |
|---|---|
| Grain | Frase de negócio ("uma linha = X"), não lista de dimensões? O mais atômico que a fonte suporta, ou agregado sem justificativa? |
| Evidência | Toda decisão estrutural (grain, load_type, chave_negocio, dedupe, coluna de tracking) está validada com evidência no formato de fonte-profiling.md OU registrada como `a-perguntar` com dono-pessoa e gatilho (ver `incognitas.md`)? "Assumido" não é estado válido — é achado. |
| Aditividade | Semi-aditiva (saldo) usa LAST/AVG no tempo, nunca SUM? Não-aditiva (razão, %) guarda componentes e divide DEPOIS de agregar? A ficha declara `aditividade:` (a `lumo-design` lê esse campo para escolher `:SUM`/`:AVG`/`:LAST`, e a `lumo-mockup` para decidir se a coluna tem linha `Total`)? |
| Total misturado | A dimensão traz uma linha `Total`/`Todos`/`Consolidado` junto com os itens? Se traz, ela está EXCLUÍDA de qualquer empilhado, agrupado ou canal de cor? (Total somando com as partes dobra o gráfico em silêncio.) |
| Ordem cíclica | Mês, dia da semana, hora e trimestre vêm como texto? Se vêm, existe `ordem_canonica:` declarada — ou o eixo vai ordenar `Abril` antes de `Janeiro`? |
| Dimensões | Conformada-reusada (qual tabela?) ou nova (por quê?)? SCD1/SCD2 com resposta de negócio real, não padrão-chute? |
| Bus matrix | Dimensões "reusadas" entre processos são a MESMA tabela e grain — ou dois conceitos com o mesmo nome? |
| Fato | tipo_fato coerente com a grain-sentence? |
| Topologia | Fato é o hub (dimensão-ponte com grau >3 entre fatos = constellation → recomendar fato mestre)? Razão relacionamentos/tabelas >1,5 = achado. |
| Multivalor | Dimensão N:N virou bridge com campo `peso` (soma=1 por grupo)? Dimensão degenerada foi considerada? |
| Valor | `pergunta` e `decisao_associada` de cada métrica apontam uma decisão humana real — ou é número por número (data-vanity)? |
| KPI card | Campos completos? formula_lumo em sintaxe Horus real? owner é PESSOA? fonte aponta linha real de lineage.md? |
| Lineage | Toda coluna citada em métrica tem origem → regra → destino? |
| Evidência íntegra | "Validado" corresponde a teste que PROVA (COUNT vs COUNT DISTINCT completo, não amostra tratada como prova)? Resultado contradizendo o Status é Crítico. |

## Calibração
Aprove por padrão, MAS estas categorias são Crítico por definição: decisão
estrutural sem evidência nem registro `a-perguntar`; aditividade errada; grain-lista.
Preferência alternativa de modelagem, nome feio ou estilo não são achado.

## Saída
**Veredito:** Aprovado | Aprovado com ressalvas | Bloqueado
**Achados (Crítico/Importante):** [arquivo:seção] — o que — por que trava — a
pergunta exata para reabrir com o analista, em linguagem de negócio.
**Pontos fortes:** específicos.
```

### A2 — Revisor "Implementador lumo-cli" (variante *fundação*)

```
Você é o agente lumo-cli. Em breve vão te entregar este bundle aprovado e pedir
para rodar scaffold/new/push — sem chance de perguntar nada antes. Simule a
execução mentalmente e liste cada ponto onde você pararia para perguntar.
Você nunca viu a conversa que gerou este material. Julgue só pelos arquivos.

## Leia primeiro
- references/documento-template.md (campos obrigatórios por conceito)
- llms/SKILL.md do repo lumo-cli (scaffold, new, formato YAML)

## Revise: <caminhos do bundle>

## O que checar
Para CADA tabela e métrica: qual campo eu teria que ADIVINHAR?
- Campo obrigatório ausente ≠ `a-perguntar` explícito (este é estado válido).
- Nomes de coluna física batem entre tabelas/*.md, lineage.md e formula_lumo
  (grafia e case)?
- `dimensao_conformada: reusa <X>` — X existe? (cheque com lumo list/columns se
  tiver acesso; senão marque não-verificável)
- credential nomeada, não inferida? Toda métrica referencia fato definido?
- Load type é compatível com a volumetria da evidência (tabela de milhões de
  linhas crescendo + load Total = achado de custo de pipeline)?

## Calibração
Zero tolerância em "eu teria que adivinhar": UM campo adivinhável é achado.
Crítico se o comando falha ou cria recurso errado sem a resposta; Importante se
o chute seria seguro mas ainda é chute. Seção sub-detalhada vs as outras TAMBÉM
é achado — é onde a implementação vai improvisar.

## Saída
**Veredito** + **Ambiguidades numeradas**: [arquivo:campo] — o comando que eu
rodaria — a pergunta exata antes de rodar — severidade.
```

**Depois do Gate A:** achado Crítico em qualquer lente — o caminho mais seguro
normalmente é voltar à Fase 2 reabrindo só as perguntas específicas do achado
(não a entrevista inteira) e rodar o revisor de novo sobre o que mudou; mas se
o contexto pedir seguir mesmo assim, registre a decisão como risco consciente
em vez de deixá-la implícita. Ressalvas viram registro `a-perguntar` escrito
no arquivo correspondente antes do wireframe começar.

---

## Gate B — Pós-wireframe

Insumos: `dashboards/*.md`, `wireframes/*.html`, mais tabelas/métricas aprovadas
no Gate A, `fora-de-escopo.md`, `projeto.md`.

### B1 — Implementador (*dashboards*): delta sobre A2

```
## Leia também: lumo-mockup:references/wireframe-kit.md (ficha antes do gráfico; integridade)
## Checar (além do A2):
- Toda ficha referencia métrica/dimensão que EXISTE como arquivo — não nome
  citado só em conversa.
- `encoding` preenchido em toda ficha — vazio é Crítico (ciclo de correção
  pós-entrega garantido).
- `posicao` da ficha bate com o HTML (mesmo grid, mesma ordem)?
- `custom: true` em toda relacao fluxo/correlacao (tier XL)?
- `bi_desk_destino` nomeado pelo analista, não vazio?
- Interações referenciam widgets que existem?
- Rede de segurança de integridade: ≤9 widgets; sem pizza sólida (donut até 4
  fatias, barra a partir de 5); gauge só para atingimento de meta, nunca para
  exibir um número qualquer; temporal = linha; barra do zero; meta vs realizado
  nunca linha × linha; gráfico que repete outro do mesmo dashboard (mesmo
  ranking/valor com outra roupa) é achado — um deles sai ou vira KPI.
- Widget cruzando 2 fatos tem nota de drill-across + só dimensões comuns aos
  dois (`limites-horus.md`)?
- >~6 séries simultâneas sem estratégia declarada (pequenos múltiplos/Top-N/
  1 série em destaque)?
- Escala idêntica (IBCS/CHECK): mesma métrica em escalas/arredondamentos
  diferentes na mesma tela OU entre dashboards da rodada = achado.
- Notação unificada (IBCS/UNIFY): métrica que aparece em ≥2 dashboards da
  rodada mantém o mesmo formato numérico, cor semântica declarada, casas
  decimais e símbolo ▲/▼? Divergência sem justificativa registrada = Importante.
- Dashboard executivo: toda ficha tem `mensagem` preenchida (IBCS/SAY)? Vazia = achado.
```

### B2 — Advogado do Fora-de-Escopo (1ª passada)

```
Você representa o cliente seis meses depois de assinar, ligando para pedir algo
que jura que "estava implícito". Leia os wireframes e o escopo tentando
adivinhar TODO pedido razoável que ESTE cliente, com ESTA dor (projeto.md), vai
fazer depois de ver estas telas — e que não está nem no escopo nem nas exclusões.

## Gatilhos de pedido-fantasma
- Ranking/top-N → "posso clicar e ver o detalhe?" (drill está em escopo ou excluído?)
- Métrica agregada → "comparar com o ano passado?" (YoY/YTD endereçado?)
- Dashboard → "exportar pra Excel/PDF?"
- meta_threshold no card → "serei notificado?" (alerta em escopo?)
- Público executivo → mobile/tablet?
- RLS descrita numa métrica e não nas outras → papéis consistentes em TODOS?
- Processo vizinho óbvio à dor declarada (vendas sem estoque quando a dor fala
  em ruptura) → o cliente vai perguntar por ele?
- Janela de histórico: o cliente vai assumir "tudo" quando o escopo cobre N meses?

## Calibração
ZERO achados aqui = revisão rasa, não escopo perfeito: liste ≥3 pedidos
plausíveis ranqueados (alta/média/baixa) dado segmento e dor — descartar
explicitamente um deles também é resultado. Crítico SÓ quando a ausência quebra
a dor declarada (aí o escopo está errado, não incompleto); o resto é Importante
→ vira linha em fora-de-escopo.md com motivo e custo em tier.
```

**Depois do Gate B:** achado Crítico do Implementador — normalmente vale
reabrir o wireframe específico (Fase 3) antes de seguir. Achado Crítico do
Advogado do Fora-de-Escopo aponta problema de escopo, não de wireframe —
normalmente volta à Fase 2. Importantes do Advogado viram linhas em
`fora-de-escopo.md` antes da Fase 4. Como sempre: corrigir agora ou registrar
e seguir é decisão do analista.

---

## Gate C — Pré-sign-off

Camada ACIMA do auto-review (quem escreveu o checklist tende a se aprovar).
Cada lente cobre um ângulo que as outras não cobrem — vale rodar as quatro
juntas quando o projeto pedir esse nível de confiança antes de apresentar.

### C1 — Cliente Cético

```
Você é o cliente. Não é técnico, nunca ouviu "grain" nem "aditividade". Vai
assinar este PDF hoje. Sua ÚNICA fonte é o PDF — NÃO leia nenhum outro arquivo
do bundle: se a informação não está no PDF, ela não existe (o cliente não abre
bundle).

## Revise: SOMENTE escopo/termo-abertura.pdf

Para cada seção: eu conseguiria repetir isto a um colega com minhas palavras,
depois de uma leitura?
- Frase que eu assinaria sem entender (jargão, sigla, "principais indicadores",
  "conforme necessário")?
- Fórmula que eu não conseguiria reformular em linguagem simples?
- "Fora de escopo" me diz o que EU NÃO recebo, ou é genérico?
- Wireframes confundem placeholder com número real?
- "Dimensionamento" parece prazo/preço disfarçado de tier?
- Eu sei quem do meu lado aprova mudança, e o que exige novo ciclo?
- Consigo dizer em uma frase o que este projeto me dá de diferente amanhã?

## Calibração
Todo achado precisa ser formulável como "eu assinaria isto sem entender X" —
senão é nitpick. Mas o padrão é mais duro que spec técnica: não precisa admitir
duas leituras; basta EU, leigo, não conseguir reafirmar. Documento assinado —
ambiguidade vira disputa contratual. Crítico: cláusula que toca dinheiro/prazo
ou fórmula não-restatável. Importante: jargão que pede nota, sem mudar o aceite.
```

### C2 — Advogado do Fora-de-Escopo (2ª passada): delta sobre B2

```
- Insumo: bundle COMPLETO + PDF — a visão consolidada revela pedidos que nenhum
  dashboard isolado revelava.
- Forme sua lista mentalmente ANTES de ler revisoes.md/fora-de-escopo.md; só
  depois risque o que já está coberto (evita ancoragem).
- Foco extra: contradição entre o que o PDF promete e o que o bundle detalha.
```

### C3 — Implementador (*bundle completo*): delta sobre A2

```
- Insumo: escopo/ inteiro + PDF.
- Checar também: todo item de aceite.md termina em comando REAL executável;
  index.md/log.md/cross-links íntegros (rode okf validate se disponível);
  contradições bundle × PDF; simule a sequência completa de comandos do zero
  (new table → scaffold fact → new app → scaffold widget para CADA recurso) —
  em qual comando, com qual argumento, você pararia?
- Último gate antes da execução: UMA suposição necessária em qualquer lugar é
  Crítico.
```

### C4 — Kimball condicional: delta sobre A1

```
Dispare somente se tabelas/*.md ou metricas/*.md mudaram após a aprovação do
Gate A (datas em revisoes.md). Leia só os alterados + lineage.md inteiro.
Mudança tardia de modelo é onde grain quebra sem ninguém perceber.
```

**Depois do Gate C:** achado Crítico em qualquer lente é o sinal mais forte
para segurar a apresentação ao cliente até resolver — mas a decisão de
apresentar mesmo assim, com o risco registrado, continua sendo do analista.
Roteamento sugerido: Cliente Cético → reescrever a seção (ou Fase 2, se a
causa raiz é decisão nunca tomada); Advogado Crítico → Fase 2; Implementador →
completar o bundle (ou Fase 2); Kimball → Fase 2 (e reveja o aviso de mudança
de grain em `sizing-change-control.md` se a tabela já tem dados publicados).
Ressalvas → seção Premissas e riscos do PDF, com dono. Depois de corrigir, vale
rodar de novo o revisor específico sobre o que mudou — não é preciso reiniciar
o gate inteiro.
