deskcomm-metricas

# Analisar as métricas de uma instalação O produto mostra números em várias telas — Desempenho, Radar de risco, Uso e orçamento, Evolução da IA, Execuções, Atividades — e cada uma usa a própria régua: "handoff" tem **três definições** diferentes em três telas; "ganho" é `crm_leads` numa e a transição do agente noutra; um dia é UTC numa tela e o fuso da organização em outra. Um analista que soma números de telas diferentes chega a conclusões erradas com cara de precisas. Este guia lê a fonte (o banco), declara a régua ao lado de cada número e transforma medida em decisão. ## Como você age - **Pergunta de negócio primeiro, consulta depois.** "A conversão caiu?" vira: qual funil, qual período, comparado a quê, medido por qual definição. Sem isso, o número não responde nada. - **Agregados, nunca o texto.** Você lê contagens, medianas, taxas e enums. Nunca o corpo de mensagem, nome, telefone, notas do agente, motivo de perda em texto livre sem tratar. A instalação é de terceiros e a LGPD é nativa: o que sai do banco para o modelo é só o que a anonimização preserva (ids, datas, estados, valores). `references/acesso-e-lgpd.md`. - **Régua ao lado do número.** Todo número vem com: período fechado `[de, até)`, fuso, definição (qual tabela, qual filtro), e o que ficou de fora (grupos, arquivados, custo sem preço). - **`null` não é zero.** "Sem dado" e "zero" são respostas diferentes; o produto trata assim e você também. - **Compare com uma referência.** Período anterior, outro agente, outro funil, ou a meta que a pessoa disse. Número solto não é análise. - **Termine em ação.** Cada achado vira uma hipótese e um próximo passo: ajustar prompt (guia `deskcomm-prompt`), follow-up, horário do agente, base de conhecimento, equipe, ou "coletar mais 2 semanas". ## Passo 0 — onde está o dado e como chegar nele Não há banco na VPS: o Postgres é o Supabase, alcançado pela connection string `SUPABASE_DB_URL` do `.env` da instalação (Session pooler). Não existe papel de banco só-leitura no produto — a string do app enxerga **todas** as organizações da instalação, então toda consulta filtra `organization_id`. Como obter, o que pedir à pessoa, o que fazer com uma instalação de várias organizações e a alternativa por MCP: `references/acesso-e-lgpd.md`. ## Passo 1 — a triagem do pedido Uma pergunta por vez: qual organização (nome → id); período (padrão: últimos 30 dias fechados, comparados aos 30 anteriores); o que está incomodando (vender menos, demorar, gastar, perder); qual funil e quais agentes existem (você descobre no banco e confirma). Anote a régua escolhida antes de rodar qualquer coisa. ## Passo 2 — o panorama (sempre, antes de aprofundar) Rode o bloco "panorama" de `references/consultas.md`: volume de mensagens recebidas por semana e por origem de resposta (IA, pessoa, celular), funil por origem com taxa de ganho sobre fechados e dias até ganhar, estagnação por etapa, handoffs (somando os dois runtimes), custo de IA por propósito com o furo de preço declarado, follow-ups por desfecho, conversas esperando resposta agora. Apresente em uma tabela por bloco, com a régua embaixo. ## Passo 3 — aprofunde onde dói | sintoma | consultas | o que costuma explicar | |---|---|---| | "vende menos" | funil por origem; motivos de perda; estagnação por etapa; fluxo entre etapas por ator | etapa gargalo; motivo de perda concentrado (preço, sumiu); origem que caiu | | "demora / cliente reclama" | 1ª resposta por hora do dia (IA × humano); conversas esperando agora; horários de pico × janela do agente | agente fora da janela nos horários de pico; humano assume e demora | | "o agente passa tudo para pessoa" | handoffs por agente; vetos por portão; casos por desfecho | prompt manda encaminhar demais; portão de promessa/vocabulário vetando | | "gasta muito com IA" | custo por propósito/modelo; custo por contato qualificado e por ganho; chamadas sem preço | classificadores em modelo caro; turno com prompt gigante; custo desconhecido em modelo fora da tabela de preços | | "follow-up não funciona" | desfecho por fluxo/versão; promessas de retorno com resposta em 48 h | esperas longas demais; mensagem genérica; muitos `esgotado` | | "a base não responde" | consultas ao conhecimento: acertos, quase-acertos, limiar | material não cobre; limiar apertado | Cada achado: o número, a régua, a comparação, a hipótese, o próximo passo. As armadilhas que distorcem cada leitura — fuso, `sent_at` × `created_at`, grupos, anonimizados, tetos de linhas, três definições de handoff — estão em `references/regua-e-armadilhas.md`. Leia antes de afirmar. ## Passo 4 — o relatório ```markdown # {Organização} — {período} (fuso {tz}) · comparado a {período anterior} ## Em uma frase ## O que está bem (3 números, com régua) ## O que está travando (achado → hipótese → próximo passo) ## Custo de IA (total, por propósito, o que ficou sem preço) ## O que NÃO medi e por quê ``` Grave o relatório onde a pessoa pedir (`relatorio-<org>-<data>.md`). Números na tabela, prosa curta. Se o próximo passo é otimizar o prompt, passe o bastão ao guia `deskcomm-prompt` com os achados — ele precisa deles para não otimizar no escuro. ## O que você nunca faz - Não lê `messages.body`, `lead_checkpoints`, notas, `crm_leads.title`, telefone, nome — nem "só para entender". Se a análise exige ler conversas, é o guia de prompt, com amostra mínima e consentimento da pessoa. - Não roda `SELECT *` em tabela com dado pessoal; não copia linhas para arquivo fora da instalação. - Não escreve no banco. Nunca. - Não compara número de tela com número de consulta sem declarar que as réguas diferem. - Não afirma tendência com uma semana de dado: diz que é cedo e quando voltar a medir.