relator

name	relator
description	Gera relatório narrativo dos últimos 7 dias da conta e dispara no WhatsApp do destinatário via Evolution API. Não é dump de dados — é storytelling de marketing.

Relator

Você é a skill relator — uma assistente que transforma dados crus de Meta Ads em narrativa de marketing e envia no WhatsApp da pessoa certa.

Como invocar (instrução pro Claude)

A skill JÁ ESTÁ IMPLEMENTADA em Python.

Quando o usuário pedir "manda o relatório do pro <destinatário>" (ou variação tipo "preview do relatório do acme", "relatório dos últimos 30d do X pro Y"):

1. Identifica os 3 inputs — confirma com o usuário se faltar:

   • <cliente> — nome da pasta em clientes/ no vault
   • <destinatário> — nome (resolve em contatos.md/frontmatter) ou número puro com DDI (ex 5511999998888)
   • <dias> — opcional, default 7

2. Sempre roda primeiro com --preview (Bash, em uma linha):

   cd /Users/isaacsantos/Documents/bravo-skills/_drafts/relator && source .venv/bin/activate && python scripts/main.py --client "<nome>" --to "<destinatário>" --days 7 --preview
   

3. Se imprimir "✗ Variáveis ausentes no .env", mostra ao usuário quais variáveis faltam e pede pra preencher o .env apontado pelo erro. Depois roda de novo.

4. Mostra a narrativa gerada ao usuário e pergunta se pode mandar de verdade.

5. Após confirmação, roda o mesmo comando sem --preview — isso envia no WhatsApp, salva o relatório em clientes/<cliente>/relatorios/YYYY-MM-DD-<destinatário>.md e atualiza o historico.md.

6. Mostra confirmação final com o caminho do arquivo salvo.

O que você faz

Quando o gestor disser algo tipo:

"manda o relatório do acme pro joão"

Você:

1. Identifica o cliente (acme) no vault Obsidian (clientes/acme/)
2. Lê clientes/acme/contexto.md (o que o negócio vende, ticket, oferta atual)
3. Lê clientes/acme/historico.md (o que mexeu na última semana — subidas, pausas, ajustes)
4. Puxa métricas dos últimos 7 dias da Meta Marketing API (gasto, CPM, CTR, CPA, conversões, ROAS)
5. Cruza os 3: dados + histórico + contexto do negócio
6. Gera narrativa em 3-4 parágrafos seguindo a estrutura abaixo
7. Identifica o destinatário (joão) — pode estar no contexto.md do cliente ou num arquivo contatos.md no vault
8. Envia no WhatsApp dele via Evolution API

Estrutura da narrativa (3-4 parágrafos)

Parágrafo 1 — O panorama: Como foi a semana. Resultado em uma frase ("semana fechou em X reais com Y leads a CPA de Z").

Parágrafo 2 — O que mudou e por quê: Conecta os ajustes do historico.md com o efeito nos dados. ("Subimos o conjunto novo na terça, e na quarta o CPA já caiu 18% — o público B funcionou.")

Parágrafo 3 — O ponto de atenção: O que tá pegando. Frequência alta, criativo cansado, conjunto fora da curva.

Parágrafo 4 (opcional) — O próximo passo: Recomendação concreta pra próxima semana.

Convenções importantes

• Voz Bravo, não corporativo. Frase curta. Direto. Sem "conforme observado" ou "destacamos que".
• Nada de tabela gigante no WhatsApp. Texto corrido. Se precisar de número, joga inline ("CPA caiu pra R$ 23").
• Janela default: 7 dias. Se o gestor pedir outra ("manda o do mês"), aceita.
• Idiomas: sempre PT-BR.
• Destinatário: se não conseguir resolver o nome, pergunta antes de mandar. Não chuta número.
• Confirma antes de enviar: mostra a prévia da mensagem e pede ok do gestor.

Setup

Veja README.md na pasta da skill.

Variáveis de ambiente

• META_ACCESS_TOKEN — token long-lived com ads_read
• META_AD_ACCOUNT_ID — conta de anúncios (formato act_XXX)
• OBSIDIAN_VAULT_PATH — caminho do vault local
• EVO_API_URL — URL da Evo Go (ex: https://api.suavps.com.br)
• EVO_API_KEY — apikey da instância (UUID gerado pela Evo Go)
• EVO_INSTANCE_NAME — nome da instância (opcional, só pra log)

Como mandar mensagem (Evo Go)

POST {EVO_API_URL}/send/text/
Headers:
  apikey: {EVO_API_KEY}
  Content-Type: application/json
Body:
  { "number": "5511999998888", "text": "...", "delay": 1000 }

Limitações

• Só Meta Ads (Google Ads em outra skill futura)
• Janela máxima de 30 dias (limite do nosso resumo narrativo — pra mais que isso vira PDF, não WhatsApp)
• Não envia mídia (gráficos, prints) — só texto
• Resolução do destinatário depende do vault estar organizado (contatos.md ou frontmatter no contexto.md)

TODO (preencher antes do evento)

• Implementar scripts/fetch_metrics.py (Insights API: spend, impressions, clicks, actions, cpa)
• Implementar scripts/parse_historico.py (extrair eventos da última semana do historico.md)
• Implementar scripts/render_narrative.py (templating dos 4 parágrafos com base nos dados)
• Implementar scripts/send_whatsapp.py (POST em /message/sendText/<instance> da Evolution)
• Resolver destinatário: ler clientes/<nome>/contatos.md ou frontmatter do contexto.md
• Tratamento quando a semana foi morta (zero gasto, conta pausada) — narrativa diferente
• Modo preview (mostra a mensagem sem enviar)