---
name: matriz-rfv
description: Segmenta a base de clientes com a Matriz RFV (Recência, Frequência, Valor) — em inglês RFM. Recebe uma base (CSV, planilha ou descrita), pontua cada cliente 1-5 em R, F e V e classifica nos 11 segmentos do Método Imperatriz (Campeões, Clientes Fiéis, Fiéis em Potencial, Novos, Promissores, Precisam de Atenção, Prestes a Dormir, Em Risco, Não Posso Perdê-los, Hibernando, Perdidos), com plano de ação + scripts de WhatsApp/e-mail por segmento + dashboard HTML. 5 modos — calcular (script sobre CSV), segmentar/plano, dashboard, interpretar/ensinar (sem dados) e auditar. Use quando pedir "matriz RFV", "RFM", "segmentar clientes", "segmentar minha base", "recência frequência valor", "quem são meus melhores clientes", "clientes em risco de churn", "reativar base", "análise de base de clientes", "pra quem mando essa oferta", "clientes VIP", "win-back", ou mandar um CSV/planilha de compras. Integra com Leadflow, /reativacao-por-temperatura e /resgate-carrinho-imperatriz. Método Imperatriz — propriedade Tata Gonçalves.
---

# Matriz RFV — Segmentação de Clientes (Método Imperatriz)

Classifica clientes por **R**ecência (há quanto tempo comprou), **F**requência
(quantas vezes) e **V**alor (quanto gastou) — as três métricas comportamentais que
mais preveem recompra. Cada cliente recebe nota 1-5 em cada eixo, vira um código
(ex: `554`) e cai em um dos **11 segmentos**, cada um com ação e verba próprias.

Fundamento, faixas por ticket, ponderação e edge cases: **`references/metodologia.md`**.
Os 11 segmentos com scripts literais de WhatsApp/e-mail: **`references/segmentos-e-acoes.md`**.

## Fluxo padrão

1. **Descobrir o insumo.** A pessoa tem um CSV/planilha de compras? Ou só quer
   entender o método / segmentar de cabeça? Isso decide o modo.
2. **Definir o ticket** (low / mid / high) — muda as faixas de nota. Mentoria =
   high; produto de entrada = low. Na dúvida, pergunte o valor médio de compra.
3. **Calcular** (rodar o script) ou **segmentar manualmente** (poucos clientes).
4. **Entregar plano de ação por segmento** + scripts, priorizando verba onde há
   dinheiro escapando (Em Risco, Não Posso Perdê-los).
5. **Gerar o dashboard HTML** e salvar tudo no Obsidian Vault (`03 - Projetos/`).

Antes de disparar qualquer script em escala, rode `/voz-humana-br`.

## Modos

Selecione pelo pedido (pode combinar; o padrão é calcular → plano → dashboard):

### `--calcular` — pontuar uma base real (CSV)
O caminho principal quando há dados. O CSV precisa de 4 colunas: identificador,
data da última compra, nº de compras, total gasto (nomes flexíveis via flags).

```bash
python3 scripts/calcular_rfv.py <base.csv> --saida rfv --hoje AAAA-MM-DD
# base pequena (<100) ou comparação estável entre meses:
python3 scripts/calcular_rfv.py <base.csv> --metodo faixa --ticket high --saida rfv
# colunas com outros nomes:
python3 scripts/calcular_rfv.py <base.csv> --col-id email --col-data ultima_compra --col-freq pedidos --col-valor ltv
```
Aceita `,` e `;`, datas BR/US e valores `R$ 1.234,56`. Gera
`rfv_clientes.csv` (base + R,F,V,código,segmento) e `rfv_resumo.json` (contagem e
receita por segmento). Se faltar coluna, o script diz quais existem — remapeie.
Roda só com stdlib (imune ao pyexpat quebrado); se der erro de ambiente, `uv run`.

### `--dashboard` — visual HTML (Painel da Tata)
Depois de calcular, transforma o resumo em dashboard standalone (KPIs + grade
Recência×Frequência + tabela por receita com ação sugerida):
```bash
python3 scripts/gerar_dashboard.py rfv_resumo.json --saida dashboard-rfv.html --titulo "RFV — Base <mês>"
```

### `--segmentar` / `--plano` — ação + scripts por segmento
Para cada segmento presente na base (ou nos que a pessoa quer atacar), leia
`references/segmentos-e-acoes.md` e entregue: quem é, prioridade de verba, canal e
o **script pronto** (WhatsApp/e-mail) personalizado com o produto/oferta dela.
Regra de ouro: esforço 1:1 em Em Risco e Não Posso Perdê-los; automatize
Hibernando e Perdidos; cultive Campeões e Fiéis com relacionamento, não desconto.

### `--interpretar` / ensinar — sem dados
Quando não há CSV: explique o método com o vocabulário do negócio da pessoa,
monte as faixas de nota junto com ela (use `references/metodologia.md`) e, se ela
descrever poucos clientes, segmente manualmente aplicando as regras de
classificação. Ofereça montar a planilha-modelo de 4 colunas pra ela preencher.

### `--auditar` — criticar uma segmentação existente
Recebe uma segmentação já feita (dela ou de outra ferramenta) e verifica: a
inversão da Recência está correta? As faixas fazem sentido pro ticket? Está
tratando Em Risco como massa (erro caro)? Está dando desconto pra Campeão
(desvaloriza)? A base é recalculada com que frequência? Entregue correções.

## Regras que não se quebram
- **Recência inverte:** mais dias desde a compra = nota menor. Erro clássico.
- **Não trate a base toda igual** — o ponto inteiro do RFV é parar de fazer isso.
- **Em Risco e Não Posso Perdê-los pedem contato pessoal**, nunca disparo em massa
  impessoal: é receita grande fugindo.
- **V usa receita; se houver o dado de lucro/margem, prefira-o** (ver metodologia).
- **Compra única** (F sempre 1)? Migre pra RFM-E (Engajamento no lugar de F) —
  ver `references/metodologia.md`.
- **Recalcule periódico:** mensal (infoproduto/mentoria), semanal (e-commerce).

## Integração com o ecossistema
Em produção, o motor natural é o **Leadflow** (exportar CSV → calcular → reimportar
`_clientes.csv` com o segmento). RFV alimenta a temperatura de
`/reativacao-por-temperatura` e a escalada de `/resgate-carrinho-imperatriz`.
Segmentar quem comprou produto de entrada (R alto, F1) → funil de ascensão pro high
ticket. Detalhes em `references/metodologia.md` (seção 7). Salvar entregáveis no
Obsidian Vault; app novo em produção também na Central de Apps + inventário.
