--- id: educacao/assistente-ia-coordenadores industria: Educação uso: muito usado esforco: médio grao: Um documento por domínio, um protocolo de resposta e um playbook por entregável --- # Assistente de IA para coordenadores Coordenadores e educadores perguntam em português e recebem números auditáveis, com recorte declarado, sem dado pessoal exposto e sem causa inventada. ## Resumo executivo **Para quem:** Escolas, faculdades e infoprodutores que querem que coordenadores e educadores consultem os dados sem passar pelo time de BI. **O que resolve** - Cada coordenador pergunta ao seu assistente e recebe o mesmo número que o colega recebeu para a mesma pergunta. - O assistente diz até quando o dado vai e o que a base não responde, em vez de completar a lacuna com palpite. - Dado de aluno, responsável e comprador fica dentro da consulta: a resposta sai agregada. **Por que importa:** Quando o assistente inventa um número ou uma causa, o coordenador leva isso para a reunião e a confiança em todos os dados cai junto. Escrever o protocolo e os documentos certos custa pouco e vale para toda pergunta futura, de qualquer pessoa. É também o que permite abrir o acesso a mais gente sem abrir os dados pessoais. **Perguntas de negócio que responde** - Como foram as vendas do mês, comparando com o mês anterior e com o mesmo mês do ano passado? - Quantas matrículas novas fizemos neste período e quantas continuam ativas? - Quantos interessados em determinado nível estão em andamento no CRM? - Até quando esses números estão atualizados? - O que mais pesou na queda deste mês: volume ou ticket? - O que a base atual não consegue me responder sobre esse resultado? **O que você precisa** - Tabelas curadas na Nekt para cada domínio (matrícula, venda, mídia, agenda), com nomes de colunas estáveis - Um responsável que escreva e mantenha os context documents e os números de conferência - Decisão de quem pode ver o quê: quais tabelas cada perfil de agente lê **O que você recebe** - Um protocolo de resposta que vale para toda pergunta - Documentos de domínio com definição, números de conferência medidos e limites - Playbooks que fixam a estrutura dos relatórios recorrentes - Um sumário de entrada que diz ao agente quais documentos ler ## Detalhado ### O problema Coordenadores e educadores perguntam ao assistente sobre matrículas, vendas e funil, e o assistente responde com o primeiro número que a consulta devolve. Ele soma linhas de retratos diferentes, chama interessado de aluno, completa série incompleta e explica a queda com uma causa que não está em tabela nenhuma. Duas pessoas fazem a mesma pergunta e recebem números diferentes. ### Regras de negócio 1. **Contexto antes de SQL.** Ordem fixa de trabalho: buscar o contexto semântico com a pergunta original do usuário, ler os documentos devolvidos, verificar a última carga da tabela, só então gerar e rodar a consulta. No fim, conferir a ordem de grandeza contra os números de referência do documento de domínio antes de entregar. (Evite: Ir direto para o SQL com o nome de tabela que parece certo.) 2. **Três tipos de documento, cada um com seu papel.** O protocolo diz como responder (regras de número, o que não inventar, formato). O documento de domínio diz como calcular cada métrica. O playbook diz o que montar e em que ordem. Em conflito, o documento de domínio vence no cálculo e o protocolo vence na forma. Separe também regra operacional (qual tabela, qual data, como contar) de semântica (o que cada coluna significa), e nunca transfira o significado de uma tabela para outra sem regra escrita. (Evite: Um documento único misturando definição de coluna, regra de contagem e formato do relatório.) 3. **Um sumário de entrada com Ler quando.** Mantenha um documento raiz que lista cada documento com uma linha de Ler quando (assunto e palavras do pedido). O agente lê todos os que combinam; métricas encadeadas se leem juntas (pergunta de ROAS lê também mídia e receita). Se nenhum documento cobre o pedido, o agente avisa em vez de improvisar. Todo documento novo ou renomeado atualiza o sumário na mesma tarefa. (Evite: Deixar o agente escolher documentos só pela busca semântica.) 4. **Número só da consulta, sempre com recorte.** Nunca preencher número que não veio da consulta, nem completar ou arredondar série. Nulo é ausência e se reporta como ausência. Toda resposta com tempo traz data inicial, data final e data da última carga (MAX da coluna de data). O dia corrente é parcial: compare só dias fechados e diga isso. (Evite: Estimar o mês corrente ou comparar o dia de hoje com o dashboard.) 5. **Base pequena invalida percentual.** Quando o período de comparação é zero, negativo ou menor que um quarto do valor atual, escreva base baixa e mostre a variação em reais. Toda variação relevante leva o valor em reais junto do percentual. Variação de taxa sai em pontos percentuais. Não some percentuais nem médias entre linhas: recalcule a razão a partir dos totais. (Evite: Reportar +1.775% sobre uma base de R$ 20 mil.) 6. **Aponte o fato, nunca a causa.** Decompor é análise: volume contra ticket, qual grupo ou unidade explica a variação em reais. Explicar por que caiu ou recomendar ação, sem dado de produtividade, meta ou budget na base, é invenção. Feche com a lista do que a base atual não responde. Quando o mês cai contra o anterior e sobe contra o ano passado, mostre as duas comparações e não escolha uma. (Evite: A queda veio de menor produtividade da equipe.) 7. **Evento é uma coorte que não encolhe.** Pergunta de evento (quantas matrículas novas entre A e B) usa a data do evento e a data final inteira, não meia-noite. A coorte histórica não muda depois: se 20 entraram e 2 cancelaram, foram 20 matrículas novas; a situação atual (18 ativas, 2 canceladas) vem separada, pela situação mais recente da mesma matrícula. Pergunta de posição (quantos estavam matriculados em D) usa um único retrato. (Evite: Responder 18 matrículas novas porque 2 já cancelaram.) 8. **Pessoas só sob pedido, e com teto.** Por padrão, responda com contagens e somas. Liste pessoas só quando quem pergunta pedir, com as colunas que a pergunta precisa e até 50 linhas. Em agentes de coordenadores e de mídia, e-mail, nome, telefone e documento ficam só dentro da consulta (para casar fontes) e nunca saem na resposta. Contato do CRM pode ser responsável, interessado ou familiar. (Evite: Devolver a lista de compradores com e-mail quando perguntaram quantos compraram.) 9. **Acesso curado e recusa com destino.** Agentes de coordenadores leem só um conjunto curado de tabelas, citadas pelo nome completo no documento. Erro de acesso fora dele é o escopo funcionando: o agente responde que aquilo está fora do seu acesso e diz onde está (dashboard, planilha, outro responsável), sem pedir permissão nova. Cada documento traz uma tabela O que esta fonte não responde e onde procurar. (Evite: Tentar outra tabela bruta quando a curada não tem a resposta.) 10. **Mesmo critério para todos os usuários.** A mesma pergunta usa o mesmo cálculo para qualquer pessoa, conversa ou painel. Filtros seguem esta prioridade: os explícitos na pergunta atual, os mantidos claramente na conversa, os ativos no painel, as regras padrão do documento. Relatório recorrente segue o playbook: leitura executiva de até cinco linhas antes de qualquer tabela, mês com comparação contra o mês anterior e o mesmo mês do ano anterior sempre juntas, acumulado do ano, quebras e rodapé de metodologia. Muda o meio (página, documento, markdown), não a estrutura. (Evite: Cada coordenador recebe um recorte diferente para Como foram as vendas.) ### Que documento resolve o quê Cada pergunta passa pelos três, nesta precedência. - **Sumário de entrada** → Quais documentos ler (`Ler quando: `) - **Protocolo de resposta** → Como responder (`vence na forma`) - **Documento de domínio** → Como calcular (`vence no cálculo`) - **Playbook** → O que montar e em que ordem (`manda na estrutura`) - **Semântica da tabela** → O que cada coluna significa (`não vira regra de contagem`) - **Lista de tabelas permitidas** → O que o agente pode ler (`nome completo`) ### Definições | Métrica | Definição | |---|---| | Última carga | maior data da coluna de data da tabela consultada, rodada antes da resposta e escrita nela | | Recorte | data inicial e data final, inclusivas, mais a data da última carga; dias fechados por padrão | | Janelas do relatório | Mês = último mês fechado; MoM = mês anterior; YoY = mesmo mês do ano anterior; YTD = 1º de janeiro até o fim do mês contra o mesmo intervalo do ano anterior | | Base baixa | período de comparação zero, negativo ou menor que um quarto do valor atual; mostra-se a variação em reais no lugar do percentual | | Variação de taxa | diferença em pontos percentuais entre as duas taxas, recalculadas a partir dos totais | | Coorte de entradas | pessoas distintas com o evento (matrícula, venda, cadastro) dentro do período; não muda com a situação posterior | | Situação atual da coorte | situação mais recente disponível de cada item da coorte, apresentada separada do total histórico | | Número de conferência | valor medido com data e hora num mês fechado, escrito no documento, que o agente precisa reproduzir | ### Armadilhas - **Causa inventada.** O assistente explicou uma queda de vendas por menor produtividade da equipe e sugeriu priorizar conversão, numa base que só tinha venda, cancelamento e cadastro. Como evitar: Escreva no protocolo o que a base não tem e exija a lista do que o dado não responde. - **Percentual sobre quase nada.** Rankings de unidade e de consultor traziam variações de quatro dígitos sobre bases ínfimas, e esses nomes iam para o topo da leitura. Como evitar: Regra de base baixa e ordenação por variação absoluta em reais. - **A coorte encolheu.** Perguntaram quantas matrículas novas houve e o agente filtrou a situação ativa de hoje, descontando quem cancelou depois. Como evitar: Coorte pelo evento no período; situação atual em bloco separado. - **Último dia cortado.** O período até o dia 31 virou 31 às 00:00 e todas as matrículas daquele dia ficaram de fora. Como evitar: Compare pela data, com a data final inclusiva. - **Lead que não é lead.** Na ferramenta de agenda, lead era quem agendou uma call. O agente apresentou esse número como Leads e MQL, que na casa vinham de outra fonte, fora do banco. Como evitar: Nomeie cada conceito pela fonte e escreva no documento o que ele não é. - **Endereço antigo no documento.** Depois de restringir o acesso dos coordenadores a um conjunto curado, documentos ainda citavam as tabelas antigas e o agente batia em erro de acesso em toda pergunta. Como evitar: Atualize os nomes completos no mesmo dia da mudança e trate erro de acesso como fora do escopo. ### Teste de aceitação - [ ] A mesma pergunta, feita por dois usuários em conversas diferentes, devolve o mesmo número, o mesmo recorte e a mesma data de última carga. - [ ] Para o mês fechado de referência, o agente reproduz os números de conferência do documento (por exemplo, faturamento ao centavo e quantidade de vendas exata). - [ ] Toda resposta com recorte de tempo traz data inicial, data final e última carga. - [ ] Pedir a lista de compradores a um agente de coordenador devolve recusa e o total agregado; num agente com permissão, a lista vem com no máximo 50 linhas. - [ ] Perguntar por que um número caiu devolve a decomposição em reais e a frase de limite, sem causa nem recomendação. ### Context document ```text Protocolo de resposta do assistente - Sempre: buscar o contexto semântico com a pergunta original antes de qualquer SQL; ler os documentos devolvidos; se houver playbook para o entregável, ele manda na estrutura. - Rodar MAX() e declarar a última carga em toda resposta com recorte de tempo. Dia corrente é parcial: comparar só dias fechados. - Conferir a ordem de grandeza contra os números de referência do documento de domínio antes de entregar. - Precedência: documento de domínio vence no cálculo; este protocolo vence na forma. Pergunta explícita do usuário > regras operacionais > semântica da tabela. - Nunca preencher número que não veio da consulta. Nulo é ausência, não zero. - Base de comparação zero, negativa ou menor que um quarto do atual: escrever base baixa e mostrar a variação em reais. Variação de taxa em pontos percentuais. Não somar percentuais nem médias entre linhas. - Apontar o fato, nunca a causa. Não recomendar ação. Fechar com o que a base não responde. Se MoM e YoY discordarem, mostrar os dois. - Evento usa a data do evento, com a data final inclusiva. A coorte histórica não diminui com cancelamentos posteriores; situação atual vem separada. - Responder com contagens e somas. Listar pessoas só quando pedido, com as colunas necessárias e até 50 linhas. Nos agentes de coordenadores, nunca listar e-mail, nome, telefone ou documento. - Ler só as tabelas listadas pelo nome completo. Erro de acesso fora delas = fora do escopo: dizer onde a resposta está, sem pedir acesso. - Filtros: pergunta atual > contexto da conversa > filtros do painel > padrão do documento. - Relatório de vendas sem conteúdo especificado: seguir o playbook (leitura executiva, mês com MoM e YoY, YTD, trajetória do ano, quebras, rankings por variação em reais, leitura e metodologia). - Valores em padrão pt-BR, sem emoji, rodapé com fonte e última carga. Exceções por cliente: - : o agente dos coordenadores lê só ; metas ficam no e não estão no banco. - : não é ; a métrica oficial vem de e não está no banco. - : número de conferência do mês de referência: = em . ``` ### Variações - **Handoff por fonte:** Um documento por fonte (vendas, mídia, agenda) e um que cruza as fontes, cada um com seção para o agente. - **Escopo por perfil:** Agentes diferentes para coordenação, tráfego e diretoria, com listas de tabelas diferentes. - **Educadores e CRM:** Perguntas de interessados e etapas respondidas como análise de CRM, nunca como matrícula.