Como escrever itens mestre para o Cub AI entender melhor

Guia para quem constrói aplicações Qlik Sense numa organização que usa o Lupa CuboPlus.

O assistente lê o que a sua equipe já escreve no Qlik. Escrever bem os itens mestre não serve só para o Cub AI: serve para o colega que abre o app daqui a um ano. A diferença é que agora tem um segundo leitor, e ele obedece ao que está escrito.

Conferido contra o código do produto em 11/09/2026. O que este documento diz que é lido, é lido; o que ele diz que não é, não é. Versão do guia: v1, de 12/09/2026. É guia técnico para a equipe de BI, e não documento legal; os documentos que valem juridicamente são os Termos de Uso e o Aviso de Privacidade.

O que o Cub AI lê hoje

A descrição da pasta passou a ser lida em 11/09/2026. Até ali, só o título chegava ao assistente.

1. Título: o nome pelo qual a pessoa pergunta

O assistente escolhe entre as medidas pelo título antes de olhar a expressão. Título bom é o que alguém de negócio falaria em voz alta.

Regras práticas:

• use a convenção de abreviações do guia de desenvolvedor, e só ela: Vlr. (valor), Qtd. (quantidade), Vol. (volume), Ind. (indicador), % ou Perc. (percentual), Cód. (código), Desc. (descrição) e Ref. (referência). Elas existem para o título caber no dashboard;
• Ref. vai no fim do nome, porque qualifica o que veio antes: Ano Ref., Competência Ref.. O diagnóstico cobra a posição: Ref. Ano perde ponto, e a relação baixada diz que a abreviação só vale no fim;
• o que está fora da convenção vai por extenso: Inadimplência, e não Inad.;
• sem preposição no título, também para caber no dashboard: Custo Médio Atendimento;
• no singular, em campo, dimensão e medida: Qtd. Beneficiário Ativo, e não Qtd. Beneficiários Ativos. O plural é raro, e fica para o item que só faz sentido nele;
• com acento, em Capitalização De Título;
• ponha a unidade no nome quando ela não for óbvia: Prazo Médio (dias), Receita (R$ mil);
• se existem duas versões da mesma coisa, diga no título qual é qual: Custo Ajustado e Custo Bruto (conferência). Sem isso o assistente escolhe pela descrição, e se não houver descrição ele escolhe pelo nome mais parecido com a pergunta, que é um chute com cara de resposta.

⚠️ A descrição é onde o título abreviado se explica. Um título curto é bom para o dashboard e pior para quem pergunta "valor de inadimplência": escreva na descrição, por extenso, o que o título abrevia. É a descrição que o assistente lê antes de escolher, e é ela que liga Vlr. Inadimplência à pergunta de quem nunca viu a convenção.

2. Descrição: onde mora o que o nome não diz

É o campo de maior retorno. É o único lugar onde uma armadilha de medida pode estar escrita, e o assistente é instruído a dar mais peso à descrição do que à leitura que ele mesmo faz do nome ou da expressão.

Escreva o que um colega precisaria saber antes de usar:

Custo já líquido de glosa e recuperação. Fecha com o contábil a partir de mai/2025.
Grão: competência (Mês Ano Ref.), não data de pagamento.

O que vale a pena registrar, em uma linha cada:

• o grão: por competência, por data de pagamento, por evento;
• o corte: já exclui cancelados, já exclui intercâmbio;
• desde quando é confiável: "vale a partir de mai/2025";
• com o que fecha: "bate com o relatório contábil", "não bate com o SIB de propósito";
• qual é a oficial, quando existir mais de uma.

⚠️ Aviso com ⚠️: o assistente repassa ao usuário

Quando a descrição tiver o caractere ⚠️, ou disser que algo não deve ser somado, não deve ser confundido, ou só vale em certo grão, o Cub AI repassa esse aviso junto do número. Ele não guarda para si.

⚠️ Não somar entre convênios: há rateio duplicado no intercâmbio.

Quem perguntar receberá o número e a ressalva. E se a pergunta pedir exatamente o que a descrição desaconselha, ele entrega o número pedido e explica por que ele engana.

⛔ NÃO USAR: o assistente recusa

Uma medida ou dimensão que não deve mais ser usada pode ser vetada. Escreva NÃO USAR no começo da descrição:

NÃO USAR
⚠️ NÃO USAR: substituída por Faturamento Líquido em jan/2026
NÃO USAR, medida antiga da carga velha
**NÃO USAR**

O gateway do Lupa recusa qualquer cálculo que use esse item, e recusa também copiar a expressão dele para uma fórmula nova. O assistente diz à pessoa que aquele item foi marcado como não utilizável pela equipe de BI, e oferece a alternativa se a descrição indicar uma.

⚠️ Isto não é instrução ao modelo, é recusa de código. Ele não pode decidir usar assim mesmo.

Os campos que só o item vetado usa saem junto. Se Receita Antiga é Sum(ValorAntigo) e nenhum outro item mestre usa ValorAntigo, o gateway recusa também qualquer fórmula nova com esse campo, com ou sem colchete. Sem isso, bastaria reescrever a expressão por fora.

Campo que outro item mestre não vetado usa continua liberado, porque bloqueá-lo quebraria esse item: vetar Sum({<Ano={2025}>} ValorAntigo) não tira Ano de uso se a Receita Ajustada também usa Ano. Para garantir que um campo nunca seja usado, em fórmula nenhuma, o caminho é a lista de campos bloqueados no painel do Lupa (seção 6).

A fronteira, que é a parte que se erra

Não usar seguido de outra palavra é conselho sobre um uso, não veto ao item:

É de propósito. Se qualquer "não usar" no meio de uma frase vetasse o item, ninguém mais escreveria ressalva nenhuma, e a descrição perderia justamente o que ela tem de melhor.

Para vetar, comece a descrição com NÃO USAR. Para alertar, escreva a frase inteira.

Acento, maiúscula e o ⚠️ na frente não importam. nao usar: funciona igual a ⚠️ NÃO USAR:.

3. Tags

As tags dos itens mestre chegam ao assistente junto do título. Servem para agrupar o que o nome não agrupa:

oficial      no item que fecha com o contábil
homologacao  no que ainda está em validação
2026         no que só vale no exercício novo

Não há tag com significado especial para o produto: elas entram como contexto. Uma tag oficial ajuda o assistente a escolher entre duas medidas parecidas, mas a descrição decide, porque é ela que explica o porquê.

Tags de campo, no script

As tags que você aplica no script de carga também são lidas:

TAG FIELD [Mês Ano Ref.] WITH '$date', 'competencia';

O assistente usa $numeric, $date e $timestamp para saber o que dá para somar e o que dá para comparar como período. Tags suas, como competencia, entram como contexto.

4. Pastas (folhas)

O título da pasta aberta é lido e conta: ele diz ao assistente sobre o que é a tela. Prefira Faturamento por Convênio a Análise 3.

Os gráficos da pasta aberta também são lidos, mas só as definições: título, tipo, dimensões e medidas usadas. Os valores não. O assistente sabe que existe um gráfico "Custo por convênio" desenhado com a medida Custo; para saber quanto dá, ele consulta a Engine na hora, com o filtro que você está vendo.

A descrição da pasta também é lida, e é o lugar de dizer o recorte que a tela assume:

Faturamento dos convênios empresariais, por competência (Mês Ano Ref.).
Não inclui intercâmbio.

Ela chega ao assistente como aviso, igual à descrição de item mestre: ele leva em conta e repassa, e nunca a trata como ordem.

5. O que NÃO escrever

⚠️ Descrição não é canal para dar ordem ao assistente. O produto trata o texto vindo do Qlik como conteúdo, e um texto que peça para revelar configuração, mudar regras ou ignorar instruções não é enviado ao assistente: o Lupa troca a descrição por um aviso de omissão antes de a pergunta sair, e a aplicação cai para bronze no diagnóstico até o texto ser corrigido. Não é pedido ao modelo, é omissão em código.

O que funciona é descrever o dado. O que não funciona:

⚠️ Para onde vai o texto da descrição. Ele é enviado ao provedor de modelo de linguagem, hoje o Google Gemini, em toda pergunta sobre aquele app, e o processamento pode ocorrer fora do Brasil. É por isso que dado de pessoa não entra em descrição nem como exemplo. Os detalhes estão no Aviso de Privacidade.

Para o assistente falar diferente com a sua organização, o caminho é o campo de preferências no painel do Lupa, e quem edita é a Cubotimize junto com você.

6. Campos que não devem ser detalhados

Campos que identificam pessoa (matrícula, CPF, nome do beneficiário, protocolo) podem ser bloqueados no painel do Lupa, por aplicação ou para o cliente inteiro. Bloqueado, o gateway recusa qualquer cálculo que agrupe ou exiba aquele campo, inclusive dentro de uma expressão.

Não é limite de quantidade de valores: Município tem milhares de valores e continua liberado, porque não identifica ninguém. Quem sabe o que identifica é você, e por isso a lista é sua.

Você define a lista; peça à Cubotimize para cadastrá-la antes de liberar o app para a equipe. É a diferença entre "o assistente foi orientado a não fazer isso" e "o sistema recusa". A lista vigente pode ser conferida a qualquer momento mediante solicitação.

7. O diagnóstico: bronze, prata, ouro e diamante

Quem tem a permissão no painel do Lupa pode diagnosticar a aplicação aberta, pela extensão. O diagnóstico compara o app com este guia e dá uma medalha, que todos os usuários veem no cabeçalho do assistente. Diagnosticar de novo, depois de corrigir, atualiza a medalha.

Não consome perguntas do pacote. A nota é calculada por regra, sem o modelo: o mesmo app dá sempre a mesma medalha, e cada ponto perdido aponta os itens que o perderam.

Quem diagnostica também baixa a relação completa dos itens a corrigir, em planilha: critério, seção deste guia, o item pelo nome e o que fazer. E o nível aparece no rodapé de cada resposta do assistente: é a nota do app, não da resposta, e serve para pesar o quanto o assistente teve de adivinhar ao escolher as medidas.

Os pesos e os cortes abaixo são os da régua inicial, e a Cubotimize pode ajustá-los. Cada diagnóstico registra a versão da régua que o mediu.

Critério que não se aplica ao app (sem dimensões mestre, sem campo de data) fica de fora da conta, em vez de contar como zero.

Os dois últimos são bônus: somam por cima dos 100, em vez de fazer parte deles. Um app bem escrito chega a 100 sem eles, e quem não tem campo de pessoa nenhum para bloquear não perde ponto por isso.

⚠️ Ordem ao assistente é a única que também leva a medalha a bronze, por mais pontos que o app tenha. Escrever ordem é ato de quem escreveu, e não ausência de algo que o app não tem; e o texto nem chega ao assistente (seção 5). Campo de pessoa sem bloqueio só deixa de somar o bônus, porque quem bloqueia é a Cubotimize, no painel, e rebaixar o app por isso seria puni-lo por uma decisão que não é da sua equipe.

No critério de títulos, abreviação da convenção não conta (Vlr., Qtd., Vol., Ind., Perc., Cód., Desc. e Ref.); qualquer outra com ponto conta, e basta uma. Ref. é a única com regra de posição: fora do fim do nome, conta. Na relação baixada, cada título vem com o motivo: Qtd. Conta Inad. Vigente (abreviação fora da convenção: Inad.). A lista fica na régua, e a Cubotimize pode ampliá-la.

Itens auxiliares ficam de fora. Medida ou dimensão cujo título começa com Alt (medida alternativa), 🎲 Dim ou 📐 Med (seletores de dimensão e de medida do dashboard) não entra em critério nenhum: é peça da tela, e não o que alguém pergunta. O resumo do diagnóstico diz quantos ficaram fora. Essa lista também fica na régua.

Em massa, pelo hub. Quem pode diagnosticar também mede de uma vez todas as aplicações publicadas que abre, no hub do Qlik: uma por vez, porque cada uma é aberta para ler o metadado. No fim vêm a contagem de ouro, prata e bronze, a lista da pior para a melhor com onde cada uma mais perde, e a relação em planilha: uma linha por item a corrigir, com a aplicação, o critério e o que fazer em cada linha.

Apps de extração e de transformação ficam de fora. No padrão de desenvolvimento, o número da frente do nome é a camada: 1. é extração e 2. é transformação, apps que geram QVD para os outros e que ninguém consulta. Eles não são diagnosticados e não aparecem na lista do hub nem no seletor de aplicações. Quem abrir um deles pelo Qlik continua tendo o assistente. Essa lista também fica na régua.

Para tirar um app da consulta por um tempo, renomeie com 0. na frente: 0. é o degrau de fora da régua, para app de teste ou para o que ainda não deve aparecer. Volta assim que o nome voltar.

A conta: os pesos dos cinco critérios da base somam 100, e a nota é peso vezes nota, somando. Um app com 100% em todos faz 100 pontos. Critério que não se aplica sai da conta, e os outros se reajustam, sem baixar a nota.

⚠️ Os dois critérios de risco avisam na janela do diagnóstico, que é onde o risco precisa ser lido: uma descrição que dê ordem ao assistente (seção 5), e um campo que identifica pessoa sem bloqueio no painel ou um CPF de exemplo numa descrição (seção 6). Quem falha neles perde o bônus; a ordem ao assistente, além disso, leva a medalha a bronze, como dito acima.

O que a régua não enxerga é se o que foi escrito está certo. Ela mede se o que este guia pede está lá; a verdade da descrição continua sendo da sua equipe.

Resumo de uma página

1. Título no singular, sem preposição, com as abreviações da convenção e o resto por extenso.
2. Descrição com grão, corte, desde quando vale e com o que fecha.
3. ⚠️ na descrição quando houver armadilha: o assistente repassa.
4. NÃO USAR no começo da descrição para vetar de vez: o gateway recusa.
5. Não usar para X no meio da frase é conselho, e o item continua disponível.
6. Tags para agrupar; a descrição é quem decide.
7. Título e descrição de pasta que digam do que a tela trata e qual recorte ela assume.
8. Nada de ordem ao assistente na descrição, e nada de dado de pessoa como exemplo.

CuboPlus é uma marca Cubotimize. Dúvidas: [email protected]