# Schema JSON — Output da skill `/diagnostico-gargalo-funil`

Toda execucao da skill em modo `--auto` ou `--manual` salva 2 arquivos:

```
~/imperio/mentoradas/[nome]/diagnostico-gargalo-[YYYY-MM-DD].json   # consumido por /tatou-2.0 e /celeste
~/imperio/mentoradas/[nome]/diagnostico-gargalo-[YYYY-MM-DD].md     # versao legivel pra mentora
```

Este documento define o **schema completo do JSON**.

---

## ESTRUTURA RAIZ

```json
{
  "schema_version": "1.0",
  "skill_version": "1.0.0",
  "skill_name": "diagnostico-gargalo-funil",
  "execution_id": "uuid-v4",
  "executed_at": "2026-05-08T14:30:00-03:00",
  "executed_by_mode": "auto | manual | comparar | despachar",
  "mentorada": { ... },
  "context": { ... },
  "etapas": [ ... ],
  "scorecard": { ... },
  "gargalo_principal": { ... },
  "gargalo_secundario": { ... | null },
  "teste_ab": { ... },
  "skills_despachadas": [ ... ],
  "impacto_financeiro_estimado": { ... },
  "proximo_diagnostico": { ... },
  "metadata": { ... }
}
```

---

## OBJETO `mentorada`

```json
"mentorada": {
  "nome": "Bianca Silva",
  "slug": "bianca-silva",
  "ticket_medio_brl": 3500,
  "faturamento_mensal_brl": 32000,
  "estagio": "30k",                    // "30k" | "100k" | "300k+"
  "sub_nicho": "coaching",             // "generalista" | "business" | "coaching" | "terapia" | "copy-marketing"
  "ano_inicio_negocio": 2023
}
```

---

## OBJETO `context`

```json
"context": {
  "periodo_analise": {
    "inicio": "2026-04-08",
    "fim": "2026-05-07",
    "dias": 30
  },
  "mix_trafego": {
    "pago_pct": 60,
    "organico_pct": 30,
    "indicacao_pct": 10
  },
  "temperatura_predominante": "frio_morno",  // "frio" | "frio_morno" | "morno" | "morno_quente" | "quente"
  "canal_venda_principal": "call_descoberta",  // "DM" | "call_descoberta" | "aplicacao_call" | "direto_LP"
  "lista_email_size": 3200,
  "comunidade": {
    "existe": false,
    "plataforma": null,
    "membros_ativos": 0
  },
  "investimento_ads_mensal_brl": 4500,
  "ferramentas": {
    "pixel_meta": true,
    "capi": true,
    "google_analytics": true,
    "crm": "rd_station",
    "email_tool": "activecampaign",
    "agendamento": "cal.com",
    "plataforma_entrega": "hotmart"
  }
}
```

---

## ARRAY `etapas` (10 objetos, um por etapa)

Cada objeto:

```json
{
  "numero": 1,
  "nome": "impressoes",                       // slug
  "nome_legivel": "Impressoes",
  "kpi_principal": {
    "nome": "total_impressoes_mensal",
    "valor_atual": 110000,
    "unidade": "absoluto",
    "benchmark": {
      "vermelho_max": 80000,
      "ok_min": 100000,
      "ok_max": 300000,
      "otimo_min": 500000
    },
    "calibrador_aplicado": {
      "estagio": 1.0,
      "sazonalidade": 1.0,
      "canal_dominante": 1.0
    },
    "desvio_pct": 10,
    "status": "verde"                          // "verde" | "amarelo" | "vermelho"
  },
  "kpis_secundarios": [
    {
      "nome": "cpm_meta_frio",
      "valor_atual": 45,
      "unidade": "BRL",
      "benchmark_ok_max": 50,
      "status": "verde"
    },
    {
      "nome": "frequencia",
      "valor_atual": 3.2,
      "unidade": "absoluto",
      "benchmark_ok_max": 4,
      "status": "verde"
    }
  ],
  "is_gargalo_principal": false,
  "is_gargalo_secundario": false,
  "comentario_diagnostico": "Volume saudavel pra estagio 30k. CPM dentro da faixa."
}
```

### Status possiveis

- `verde` — metrica >= benchmark OK
- `amarelo` — metrica entre -15% e benchmark OK
- `vermelho` — metrica < -15% benchmark OK
- `na` — nao aplicavel (dado faltando ou nao coletado)

### Etapas obrigatorias

Sempre 10 entradas, mesmo que algumas sejam `status: "na"`:

1. `impressoes`
2. `cliques`
3. `visitas_lp`
4. `leads`
5. `mql`
6. `sql`
7. `vendas`
8. `onboarding`
9. `recompra`
10. `indicacao`

---

## OBJETO `scorecard`

```json
"scorecard": {
  "total_verde": 14,
  "total_amarelo": 4,
  "total_vermelho": 2,
  "total_na": 0,
  "saude_geral": "atencao",                   // "saudavel" | "atencao" | "critico"
  "etapas_verdes": [1, 3, 4, 5, 7, 8, 10],
  "etapas_amarelas": [2, 6, 9],
  "etapas_vermelhas": [2, 6],
  "regra_aplicada_gargalo_prioritario": false  // true se reembolso > 5% ou NPS D7 < 60
}
```

### Saude geral (regra)

- `saudavel` — 0 etapas vermelhas
- `atencao` — 1-2 etapas vermelhas
- `critico` — 3+ etapas vermelhas (recomendar `/imperio-diagnostico` antes)

---

## OBJETO `gargalo_principal`

```json
"gargalo_principal": {
  "etapa_numero": 6,
  "etapa_nome": "sql",
  "metrica_atual": 9,
  "metrica_unidade": "pct",
  "benchmark_esperado": 11,
  "desvio_pct": -18,
  "selecionado_por": "maior_desvio_negativo",  // "maior_desvio_negativo" | "regra_reembolso" | "regra_nps" | "regra_topo_critico"
  "hipoteses": [
    {
      "id": "h1",
      "ordem": 1,
      "probabilidade": "alta",
      "nome_curto": "Agendamento longo demais",
      "mecanismo": "Lead esfria entre marcacao e call quando janela > 4 dias.",
      "sinal_confirmatorio": "Media de dias agendamento->call > 4",
      "sinal_eliminatorio": "Janela maxima ja capada em 48h"
    },
    {
      "id": "h2",
      "ordem": 2,
      "probabilidade": "media",
      "nome_curto": "Sem reminder D-1 e D-0",
      "mecanismo": "Lead esquece...",
      "sinal_confirmatorio": "...",
      "sinal_eliminatorio": "..."
    },
    {
      "id": "h3",
      "ordem": 3,
      "probabilidade": "baixa",
      "nome_curto": "Qualificacao DM frouxa",
      "mecanismo": "...",
      "sinal_confirmatorio": "...",
      "sinal_eliminatorio": "..."
    }
  ]
}
```

### Probabilidade

Sempre exatamente 3 hipoteses, com probabilidades `alta`, `media`, `baixa` (uma de cada).

---

## OBJETO `gargalo_secundario` (ou `null`)

Mesmo schema de `gargalo_principal`. Nulo se nao houver gargalo secundario.

```json
"gargalo_secundario": null
```

ou

```json
"gargalo_secundario": {
  "etapa_numero": 2,
  "etapa_nome": "cliques",
  ...
}
```

---

## OBJETO `teste_ab`

```json
"teste_ab": {
  "hipotese_testada_id": "h1",
  "variavel": "janela_maxima_agendamento",
  "variante_a": {
    "label": "controle",
    "descricao": "Lead pode agendar ate 7 dias depois"
  },
  "variante_b": {
    "label": "variante",
    "descricao": "Janela maxima 48h via Cal.com cap"
  },
  "metrica_primaria": "no_show_rate",
  "metrica_primaria_atual": 32,
  "metrica_primaria_alvo": 22,
  "metrica_secundaria": "pct_mql_to_sql",
  "amostra_minima_por_variante": 60,
  "duracao_prevista_dias": 21,
  "criterio_decisao": "queda_no_show >= 8 pontos absolutos + p < 0.05",
  "rastreamento": {
    "ferramenta_sugerida": "Cal.com + planilha",
    "responsavel": "mentora"
  }
}
```

---

## ARRAY `skills_despachadas`

Lista ordenada (ordem = sequencia de execucao).

```json
"skills_despachadas": [
  {
    "ordem": 1,
    "skill_slug": "copy-conversacional-dm",
    "skill_nome_legivel": "/copy-conversacional-dm",
    "categoria": "primaria",                  // "primaria" | "secundaria" | "suporte"
    "para_que_serve_no_caso": "Refazer fluxo DM com qualificacao + agendamento <= 48h",
    "pre_condicoes": [
      "Pelo menos 50 DMs/mes (mentora ja tem)",
      "Calendario funcionando"
    ],
    "tempo_estimado_dias": 5,
    "impacto_esperado": "Reduz no-show + aumenta % MQL->SQL",
    "depende_de_skill_anterior": false
  },
  {
    "ordem": 2,
    "skill_slug": "analise-performance-call",
    "skill_nome_legivel": "/analise-performance-call",
    "categoria": "primaria",
    "para_que_serve_no_caso": "Auditar 5 calls que viraram no-show pra entender padrao",
    "pre_condicoes": ["Gravacoes ou transcricoes disponiveis"],
    "tempo_estimado_dias": 2,
    "impacto_esperado": "Identifica padroes especificos de no-show",
    "depende_de_skill_anterior": false
  }
]
```

---

## OBJETO `impacto_financeiro_estimado`

```json
"impacto_financeiro_estimado": {
  "premissas": [
    "No-show rate caindo de 32% pra 22%",
    "Calls efetivas subindo de 41 pra 47/mes",
    "Close rate atual estavel em 38%"
  ],
  "vendas_extras_mes": 2.3,
  "ticket_usado_brl": 3500,
  "receita_extra_mes_brl": 8000,
  "receita_extra_ano_brl": 96000,
  "confianca": "media"                         // "alta" | "media" | "baixa"
}
```

---

## OBJETO `proximo_diagnostico`

```json
"proximo_diagnostico": {
  "data_recomendada": "2026-06-08",
  "tipo_recomendado": "auto",
  "automatizado_via_tatou": true,
  "checkpoints_intermediarios": [
    {
      "data": "2026-05-22",
      "objetivo": "Verificar se teste A/B atingiu amostra minima"
    },
    {
      "data": "2026-05-29",
      "objetivo": "Decisao do teste A/B"
    }
  ]
}
```

---

## OBJETO `metadata`

```json
"metadata": {
  "input_source": "auto_planilha",            // "auto_planilha" | "auto_api" | "manual_entrevista"
  "qualidade_dado": "alta",                   // "alta" | "media" | "baixa"
  "campos_estimados": [],
  "campos_faltando": [],
  "warnings": [
    "Frequencia de retargeting alta (8.2) — monitorar saturacao"
  ],
  "tempo_execucao_skill_segundos": 142,
  "consumido_por": ["tatou-2.0", "celeste"],
  "hash_input": "sha256-abc123..."
}
```

---

## EXEMPLO COMPLETO MINIMIZADO

```json
{
  "schema_version": "1.0",
  "skill_version": "1.0.0",
  "skill_name": "diagnostico-gargalo-funil",
  "execution_id": "550e8400-e29b-41d4-a716-446655440000",
  "executed_at": "2026-05-08T14:30:00-03:00",
  "executed_by_mode": "auto",
  "mentorada": {
    "nome": "Bianca Silva",
    "slug": "bianca-silva",
    "ticket_medio_brl": 3500,
    "faturamento_mensal_brl": 32000,
    "estagio": "30k",
    "sub_nicho": "coaching",
    "ano_inicio_negocio": 2023
  },
  "context": {
    "periodo_analise": { "inicio": "2026-04-08", "fim": "2026-05-07", "dias": 30 },
    "mix_trafego": { "pago_pct": 60, "organico_pct": 30, "indicacao_pct": 10 },
    "temperatura_predominante": "frio_morno",
    "canal_venda_principal": "call_descoberta",
    "lista_email_size": 3200,
    "comunidade": { "existe": false, "plataforma": null, "membros_ativos": 0 },
    "investimento_ads_mensal_brl": 4500,
    "ferramentas": { "pixel_meta": true, "capi": true }
  },
  "etapas": [
    { "numero": 1, "nome": "impressoes", "kpi_principal": { "valor_atual": 110000, "status": "verde", "desvio_pct": 10 }, "is_gargalo_principal": false, "is_gargalo_secundario": false },
    { "numero": 2, "nome": "cliques", "kpi_principal": { "valor_atual": 0.7, "status": "vermelho", "desvio_pct": -25 }, "is_gargalo_principal": false, "is_gargalo_secundario": true },
    { "numero": 6, "nome": "sql", "kpi_principal": { "valor_atual": 9, "status": "vermelho", "desvio_pct": -18 }, "is_gargalo_principal": true, "is_gargalo_secundario": false }
  ],
  "scorecard": {
    "total_verde": 14, "total_amarelo": 4, "total_vermelho": 2, "saude_geral": "atencao",
    "etapas_vermelhas": [2, 6], "regra_aplicada_gargalo_prioritario": false
  },
  "gargalo_principal": {
    "etapa_numero": 6, "etapa_nome": "sql",
    "metrica_atual": 9, "benchmark_esperado": 11, "desvio_pct": -18,
    "selecionado_por": "maior_desvio_negativo",
    "hipoteses": [
      { "id": "h1", "ordem": 1, "probabilidade": "alta", "nome_curto": "Agendamento longo demais" },
      { "id": "h2", "ordem": 2, "probabilidade": "media", "nome_curto": "Sem reminder D-1 e D-0" },
      { "id": "h3", "ordem": 3, "probabilidade": "baixa", "nome_curto": "Qualificacao DM frouxa" }
    ]
  },
  "gargalo_secundario": {
    "etapa_numero": 2, "etapa_nome": "cliques",
    "metrica_atual": 0.7, "benchmark_esperado": 0.93, "desvio_pct": -25,
    "selecionado_por": "maior_desvio_negativo",
    "hipoteses": []
  },
  "teste_ab": {
    "hipotese_testada_id": "h1",
    "variavel": "janela_maxima_agendamento",
    "metrica_primaria": "no_show_rate",
    "metrica_primaria_atual": 32, "metrica_primaria_alvo": 22,
    "amostra_minima_por_variante": 60, "duracao_prevista_dias": 21
  },
  "skills_despachadas": [
    { "ordem": 1, "skill_slug": "copy-conversacional-dm", "categoria": "primaria", "tempo_estimado_dias": 5 },
    { "ordem": 2, "skill_slug": "analise-performance-call", "categoria": "primaria", "tempo_estimado_dias": 2 },
    { "ordem": 3, "skill_slug": "criativos-dor-beneficio", "categoria": "primaria", "tempo_estimado_dias": 3 }
  ],
  "impacto_financeiro_estimado": {
    "vendas_extras_mes": 2.3, "ticket_usado_brl": 3500,
    "receita_extra_mes_brl": 8000, "receita_extra_ano_brl": 96000, "confianca": "media"
  },
  "proximo_diagnostico": {
    "data_recomendada": "2026-06-08", "automatizado_via_tatou": true
  },
  "metadata": {
    "input_source": "auto_planilha", "qualidade_dado": "alta",
    "consumido_por": ["tatou-2.0", "celeste"]
  }
}
```

---

## VALIDACAO DO SCHEMA

A skill valida antes de salvar:

1. `etapas` array tem **exatamente 10 objetos**, com `numero` 1-10
2. `gargalo_principal` nunca e null se ha pelo menos 1 etapa vermelha
3. `gargalo_principal.hipoteses` tem **exatamente 3 objetos**
4. `gargalo_principal.hipoteses` cobre os 3 niveis de probabilidade (alta + media + baixa, sem repetir)
5. `skills_despachadas` tem ordem sequencial sem buracos (1, 2, 3...)
6. Toda `skill_slug` referenciada existe no inventario do ecossistema Tata
7. `executed_at` em ISO 8601 com timezone -03:00
8. `mentorada.estagio` e enum valido
9. `mentorada.sub_nicho` e enum valido
10. `scorecard.total_verde + amarelo + vermelho + na = 20` (10 etapas x 2 KPIs medios — pode variar)

Se validacao falha, JSON nao e salvo, skill retorna erro e logs sao escritos em `~/imperio/mentoradas/[nome]/diagnostico-gargalo-[YYYY-MM-DD].error.log`.

---

## VERSIONAMENTO DO SCHEMA

- **v1.0** (atual) — schema inicial, 10 etapas fixas, 3 hipoteses obrigatorias
- **v1.1** (planejado) — adicionar campo `historico_diagnostico_anterior` pra comparar mes a mes
- **v2.0** (planejado) — schema multi-mentora pra diagnostico em lote (varias mentoradas no mesmo JSON)

---

## CONSUMIDORES DO JSON

### `/tatou-2.0`
Usa `gargalo_principal`, `skills_despachadas` e `proximo_diagnostico` pra orquestrar a jornada da mentora mes a mes.

### `/celeste`
Usa o JSON inteiro pra montar plano semanal de execucao (cada skill despachada vira tarefa na semana correspondente).

### Marketing Command app (dashboard)
Usa `etapas[]` pra renderizar grafico de evolucao das 10 etapas mes a mes. Usa `scorecard.saude_geral` pra status no dashboard de mentoradas ativas.

### Reuniao de Resultado mensal (Tata + mentora)
Usa `gargalo_principal`, `teste_ab` e `impacto_financeiro_estimado` como pauta da reuniao.

---

## PRIVACIDADE E SEGURANCA

- JSON e salvo localmente em `~/imperio/mentoradas/[slug]/`
- Nao contem dados sensiveis (CPF, email, senha)
- `mentorada.slug` e o unico identificador (kebab-case do nome)
- Hash do input em `metadata.hash_input` permite verificar integridade sem expor inputs
- Backup recomendado: sync com Obsidian Vault `08 - Recursos/diagnosticos-mentoradas/`
