deskcomm-prompt

# Afinar o prompt de um agente com dados "O agente está ruim" quase nunca é o prompt inteiro. Às vezes é o roteador mandando para o agente errado; às vezes é um portão de saída vetando por vocabulário que o próprio prompt ensinou; às vezes é a base de conhecimento que não cobre; às vezes é o horário. Otimizar prompt sem olhar os dados troca um problema por outro. Este guia diagnostica primeiro. ## Como você age - **Sabe o que o prompt controla e o que não controla.** O texto do agente é uma camada dentro de um prompt montado pelo motor, e onze portões barram a resposta na saída. Reescrever regra que o motor já impõe é ruído; escrever jargão ou "encaminhe ao gerente" cria veto e mata a agenda. Lista completa em `references/anatomia-e-antipadroes.md`. - **Diagnóstico antes da reescrita.** Execuções, vetos, handoffs, consultas à base, custo por turno: `references/diagnostico.md`. Só depois disso você abre o prompt. - **Amostra mínima de conversa, com ciência da pessoa.** Ler mensagens é ler dado pessoal de terceiros. Quando for indispensável, poucas conversas, só o trecho, só na instalação, e a pessoa sabe. Preferir agregados (o guia `deskcomm-metricas` cobre). - **Versão nova, nunca edição.** A otimização vira uma versão em rascunho, testada pelo botão Testar com o mesmo roteiro antes e depois; o clique em Publicar é da pessoa. Versão publicada é imutável e reversível. - **Uma mudança por vez, medida.** Trocar cinco coisas e a conversão subir não ensina nada. ## Passo 0 — o que a pessoa vê Uma pergunta por vez: qual agente; o que acontece (a frase exata que incomoda, se houver); desde quando; o que mudou perto disso (versão publicada, materiais, roteador, número novo). Descubra a versão publicada e a data — as métricas comparam "antes/depois" por essa data. ## Passo 1 — o diagnóstico Rode o bloco de `references/diagnostico.md`: vetos por portão nas execuções recentes (se o veto é `internal_vocabulary` ou `promise`, a origem costuma ser o prompt); handoffs e casos (passa demais ou de menos); consultas à base sem acerto (material que falta × limiar); roteador errando (intenções, não prompt); custo e tamanho do turno; fora da janela. Cada sinal aponta para uma causa — e nem toda causa é prompt. | sinal | causa provável | onde mexer | |---|---|---| | vetos de vocabulário interno | prompt cita ferramenta, "lead", etapa, sistema | prompt | | vetos de promessa | prompt permite desconto/prazo que a tabela não permite (ou a tabela não existe) | prompt + tabela de promessas | | "vou confirmar com o gerente" e agenda parada | prompt manda encaminhar tudo a uma pessoa nomeada | prompt | | base sem acerto com score perto do limiar | limiar apertado | ajuste avançado (técnico) | | base sem acerto com score baixo | material não cobre | conhecimento, não prompt | | agente errado respondeu | intenções do roteador | roteador | | respostas longas, custo alto | prompt gigante (o turno custa ao menos duas chamadas) | prompt: cortar o que o motor já faz | | some à noite | horário do agente | configuração, não prompt | ## Passo 2 — a revisão do prompt Com o diagnóstico, abra a versão publicada e revise contra o checklist de `references/anatomia-e-antipadroes.md`: o que está lá e o motor já impõe (corte); o que está lá e cria veto (reescreva); o que falta (diagnóstico antes da oferta, situações, quando usar capacidade, limites por situação); tom e tamanho. Conteúdo situacional (objeção de preço, reativação) vai para **skill do produto**, não para o prompt — o corpo só entra quando o assunto aparece. Escreva a versão nova inteira em `prompt-<agente>-v<N>.md` com um bloco "o que mudou e por quê", uma linha por mudança, ligada ao sinal do diagnóstico. ## Passo 3 — antes/depois pelo botão Testar Monte 5 a 8 mensagens do nicho (o guia `deskcomm-cliente-novo` tem roteiros) cobrindo o que incomodava. Rode cada uma na versão publicada **e** na versão nova (rascunho) pelo botão Testar: compare texto, ações tentadas e portões. Registre a tabela em `references/diagnostico.md` (seção "antes/depois"). Se a nova não melhora onde doía, não publique — volte ao diagnóstico. ## Passo 4 — publicar (a pessoa) e medir (você, depois) A pessoa clica em Publicar. Anote a data e a versão. Em 7 a 14 dias, o guia `deskcomm-metricas` compara handoffs, vetos, custo por turno e conversão antes/depois **da data da publicação** — é a única prova de que a otimização valeu. Piorou? **Reverter** cria uma versão a partir da anterior em segundos. ## O que você nunca faz - Não edita a tabela do agente no banco (o motor ignora; a rota barra). - Não publica sem a pessoa ver o antes/depois. - Não troca modelo, provedor ou credencial "de brinde" — é outra mudança, medida à parte. - Não escreve no prompt regra que é portão do motor, nem nome de ferramenta, nem placeholder `{{assim}}`. - Não conclui pela conversa de um cliente só. Uma frase ruim é anedota; padrão é dado.