@lucapimenta/copy-chief-black 1.0.0

package/framework/skills/audience-research-agent/references/ref_voc_database_schema.md

@@ -0,0 +1,362 @@
+# Voice of Customer Library - Formato de Banco de Dados
+
+> **Usar para:** Estruturar VOC coletado de forma consultável e reutilizável
+> **Benefício:** Outros agentes (HELIX, Lead, Close) podem fazer queries específicas
+
+---
+
+## Estrutura do Banco de Dados VOC
+
+A VOC Library é estruturada como banco de dados em YAML, organizado por categorias consultáveis.
+
+### Schema Principal
+
+```yaml
+voc_library:
+  metadata:
+    produto: "[nome]"
+    nicho: "[nicho]"
+    data_coleta: "[YYYY-MM-DD]"
+    total_quotes: [número]
+    fontes_utilizadas: [lista]
+    
+  # ═══════════════════════════════════════════════════════════
+  # ÍNDICE POR TIPO DE INSIGHT
+  # ═══════════════════════════════════════════════════════════
+  
+  dores:
+    superficiais: []    # Sintomas visíveis, reclamações comuns
+    intermediarias: []  # Causas percebidas, frustrações
+    viscerais: []       # Raiz emocional, vergonha, medo profundo
+    
+  desejos:
+    declarados: []      # O que dizem querer abertamente
+    implicitos: []      # O que realmente buscam
+    secretos: []        # O que têm vergonha de admitir
+    
+  objecoes:
+    preco: []           # "É caro", "não tenho dinheiro"
+    tempo: []           # "Não tenho tempo", "demora muito"
+    esforco: []         # "Parece difícil", "não vou conseguir"
+    ceticismo: []       # "Já tentei", "não funciona"
+    adequacao: []       # "Não é pra mim", "meu caso é diferente"
+    
+  linguagem:
+    metaforas: []       # Analogias recorrentes
+    expressoes: []      # Frases-chave repetidas
+    emocional: []       # Palavras de carga emocional alta
+    tecnica: []         # Termos específicos do nicho
+    
+  gatilhos:
+    sistema1: []        # Ativam decisão emocional
+    sistema2: []        # Justificativas racionais
+    reptilianos: []     # Poder, segurança, controle, etc.
+```
+
+---
+
+## Formato de Cada Quote
+
+Cada entrada no banco segue este schema:
+
+```yaml
+- id: "VOC-[TIPO]-[NÚMERO]"
+  quote: "[texto verbatim exato]"
+  fonte:
+    plataforma: "[YouTube|Instagram|TikTok|ML|RA|Reddit|Amazon]"
+    url: "[link se disponível]"
+    data: "[YYYY-MM-DD]"
+    contexto: "[descrição breve da situação]"
+  classificacao:
+    tipo_primario: "[dor|desejo|objeção|linguagem|gatilho]"
+    subtipo: "[superficial|visceral|declarado|secreto|etc]"
+    emocao: "[frustração|esperança|raiva|medo|vergonha|etc]"
+    intensidade: [1-5]  # 1=leve, 5=extrema
+  validacao:
+    confidence: "[alto|médio|baixo]"
+    aparece_em_outras_fontes: [true|false]
+    fontes_confirmacao: ["[lista se aplicável]"]
+  uso_sugerido:
+    headline: [true|false]
+    lead: [true|false]
+    bullet: [true|false]
+    testimonial_style: [true|false]
+    objecao_handle: [true|false]
+```
+
+---
+
+## Exemplo Completo - Nicho Emagrecimento
+
+```yaml
+voc_library:
+  metadata:
+    produto: "Método XYZ Emagrecimento"
+    nicho: "emagrecimento feminino 35+"
+    data_coleta: "2024-12-27"
+    total_quotes: 47
+    fontes_utilizadas: 
+      - Reclame Aqui
+      - YouTube
+      - Instagram
+      - Mercado Livre
+    
+  dores:
+    superficiais:
+      - id: "VOC-DOR-001"
+        quote: "Já tentei de tudo e nada funciona pra mim"
+        fonte:
+          plataforma: YouTube
+          url: "https://youtube.com/..."
+          data: "2024-12-15"
+          contexto: "Comentário em vídeo de nutricionista"
+        classificacao:
+          tipo_primario: dor
+          subtipo: superficial
+          emocao: frustração
+          intensidade: 3
+        validacao:
+          confidence: alto
+          aparece_em_outras_fontes: true
+          fontes_confirmacao: ["Instagram", "Reclame Aqui"]
+        uso_sugerido:
+          headline: true
+          lead: true
+          bullet: false
+          testimonial_style: false
+          objecao_handle: false
+          
+    viscerais:
+      - id: "VOC-DOR-015"
+        quote: "Tenho vergonha de tirar foto com meus filhos. Sempre me escondo atrás de todo mundo"
+        fonte:
+          plataforma: Instagram
+          url: "https://instagram.com/p/..."
+          data: "2024-12-10"
+          contexto: "Comentário em post de antes/depois"
+        classificacao:
+          tipo_primario: dor
+          subtipo: visceral
+          emocao: vergonha
+          intensidade: 5
+        validacao:
+          confidence: alto
+          aparece_em_outras_fontes: true
+          fontes_confirmacao: ["YouTube", "TikTok"]
+        uso_sugerido:
+          headline: true
+          lead: true
+          bullet: true
+          testimonial_style: true
+          objecao_handle: false
+          
+  desejos:
+    secretos:
+      - id: "VOC-DES-008"
+        quote: "Queria poder usar biquíni sem ficar me cobrindo o tempo todo"
+        fonte:
+          plataforma: TikTok
+          url: "https://tiktok.com/..."
+          data: "2024-12-20"
+          contexto: "Storytime sobre insegurança corporal"
+        classificacao:
+          tipo_primario: desejo
+          subtipo: secreto
+          emocao: esperança
+          intensidade: 4
+        validacao:
+          confidence: alto
+          aparece_em_outras_fontes: true
+          fontes_confirmacao: ["Instagram"]
+        uso_sugerido:
+          headline: true
+          lead: true
+          bullet: true
+          testimonial_style: true
+          objecao_handle: false
+          
+  objecoes:
+    ceticismo:
+      - id: "VOC-OBJ-003"
+        quote: "Já gastei mais de 5 mil reais em curso, suplemento, nutricionista... e continuo na mesma"
+        fonte:
+          plataforma: Reclame Aqui
+          url: "https://reclameaqui.com.br/..."
+          data: "2024-12-18"
+          contexto: "Reclamação sobre produto concorrente"
+        classificacao:
+          tipo_primario: objeção
+          subtipo: ceticismo
+          emocao: raiva
+          intensidade: 5
+        validacao:
+          confidence: alto
+          aparece_em_outras_fontes: true
+          fontes_confirmacao: ["YouTube", "Mercado Livre"]
+        uso_sugerido:
+          headline: false
+          lead: true
+          bullet: false
+          testimonial_style: false
+          objecao_handle: true
+          
+  linguagem:
+    metaforas:
+      - id: "VOC-LING-001"
+        quote: "efeito sanfona"
+        fonte:
+          plataforma: YouTube
+          contexto: "Termo recorrente em múltiplos comentários"
+        classificacao:
+          tipo_primario: linguagem
+          subtipo: metafora
+          emocao: frustração
+          intensidade: 3
+        validacao:
+          confidence: alto
+          aparece_em_outras_fontes: true
+          fontes_confirmacao: ["Instagram", "TikTok", "Reclame Aqui"]
+        uso_sugerido:
+          headline: true
+          lead: true
+          bullet: true
+          testimonial_style: false
+          objecao_handle: false
+          
+    emocional:
+      - id: "VOC-LING-010"
+        quote: "desesperada"
+        fonte:
+          plataforma: múltiplas
+          contexto: "Palavra recorrente em desabafos"
+        classificacao:
+          tipo_primario: linguagem
+          subtipo: emocional
+          emocao: desespero
+          intensidade: 5
+        validacao:
+          confidence: alto
+          aparece_em_outras_fontes: true
+        uso_sugerido:
+          headline: true
+          lead: true
+          bullet: false
+          testimonial_style: true
+          objecao_handle: false
+
+  gatilhos:
+    sistema1:
+      - id: "VOC-GAT-001"
+        quote: "Imagina acordar e a roupa que você ama finalmente servir"
+        fonte:
+          plataforma: Instagram
+          contexto: "Frase de alta ressonância em comentários"
+        classificacao:
+          tipo_primario: gatilho
+          subtipo: sistema1
+          emocao: esperança
+          intensidade: 4
+        validacao:
+          confidence: médio
+        uso_sugerido:
+          headline: true
+          lead: true
+          bullet: true
+          testimonial_style: false
+          objecao_handle: false
+          
+    reptilianos:
+      - id: "VOC-GAT-005"
+        quote: "Quero que meu marido me olhe do jeito que olhava antes"
+        fonte:
+          plataforma: YouTube
+          contexto: "Comentário emocional em vídeo de transformação"
+        classificacao:
+          tipo_primario: gatilho
+          subtipo: reptiliano
+          gatilho_especifico: "aceitação social"
+          emocao: medo
+          intensidade: 5
+        validacao:
+          confidence: alto
+          aparece_em_outras_fontes: true
+        uso_sugerido:
+          headline: true
+          lead: true
+          bullet: true
+          testimonial_style: true
+          objecao_handle: false
+```
+
+---
+
+## Queries Rápidas para Outros Agentes
+
+### Para Headlines
+```
+Filtrar: uso_sugerido.headline = true AND intensidade >= 4
+```
+
+### Para Leads
+```
+Filtrar: tipo_primario = "dor" AND subtipo = "visceral"
+```
+
+### Para Bullets de Benefício
+```
+Filtrar: tipo_primario = "desejo" AND uso_sugerido.bullet = true
+```
+
+### Para Handle de Objeções
+```
+Filtrar: tipo_primario = "objeção" AND uso_sugerido.objecao_handle = true
+```
+
+### Para Testimonial-Style Copy
+```
+Filtrar: uso_sugerido.testimonial_style = true AND confidence = "alto"
+```
+
+### Por Intensidade Emocional
+```
+Filtrar: intensidade >= 4 (para copy mais agressivo)
+Filtrar: intensidade <= 2 (para copy mais suave)
+```
+
+---
+
+## Resumo Estatístico (Incluir no Output)
+
+Ao final da VOC Library, incluir:
+
+```yaml
+estatisticas:
+  total_quotes: [número]
+  por_tipo:
+    dores: [número]
+    desejos: [número]
+    objecoes: [número]
+    linguagem: [número]
+    gatilhos: [número]
+  por_intensidade:
+    nivel_5: [número]
+    nivel_4: [número]
+    nivel_3: [número]
+    nivel_2: [número]
+    nivel_1: [número]
+  por_confidence:
+    alto: [número]
+    medio: [número]
+    baixo: [número]
+  por_fonte:
+    reclame_aqui: [número]
+    youtube: [número]
+    instagram: [número]
+    tiktok: [número]
+    mercado_livre: [número]
+    reddit: [número]
+    amazon: [número]
+  validacao_cruzada:
+    quotes_multi_fonte: [número]
+    quotes_fonte_unica: [número]
+```

package/framework/skills/audience-research-agent/references/ref_voc_sources_rules_templates.md

@@ -0,0 +1,352 @@
+# Voice of Customer - Fontes e Técnicas de Extração
+
+> **Usar para:** Capturar a linguagem EXATA que o público usa para descrever seus problemas e desejos.
+> **Contexto:** A linguagem verbatim é ouro - diferencia copy que ressoa de copy que soa genérica.
+
+---
+
+## Por que Voice of Customer é Crítico
+
+"Use as palavras deles, não as suas."
+
+Quando você usa a linguagem exata do público:
+- Eles sentem que você ENTENDE
+- A copy ressoa em nível visceral
+- Objeções são superadas antes de surgir
+- Conversão aumenta dramaticamente
+
+---
+
+## Reddit - Linguagem Emocional Crua
+
+### Por que Reddit é Ouro
+- Anonimato = honestidade brutal
+- Longas discussões = contexto rico
+- Upvotes = validação social do sentimento
+- Subreddits = segmentação por interesse
+
+### Como Usar
+
+**1. Encontre subreddits relevantes:**
+- r/[nicho] - comunidade principal
+- r/[nicho]advice - pedidos de ajuda
+- r/[nicho]support - desabafos
+- r/AskReddit + filtro de tópico
+
+**2. Queries de busca eficazes:**
+- "[problema] help"
+- "[problema] advice"
+- "[problema] struggle"
+- "finally [solução]"
+- "I hate [sintoma]"
+- "anyone else [sintoma]?"
+
+**3. O que capturar:**
+- Títulos de posts (resumo do problema)
+- Primeiros parágrafos (contexto emocional)
+- Comentários com muitos upvotes (validação)
+- Histórias de fracasso com soluções anteriores
+
+### Queries por Nicho
+
+**Emagrecimento:**
+- "weight loss plateau"
+- "can't lose weight"
+- "finally lost weight how"
+- "diet failed again"
+
+**Relacionamento:**
+- "marriage problems"
+- "spouse doesn't understand"
+- "finally fixed relationship"
+- "dating after [idade]"
+
+**Disfunção Erétil:**
+- "ED at [idade] help"
+- "can't perform anxiety"
+- "girlfriend doesn't know"
+- "finally fixed ED"
+
+**Finanças:**
+- "debt help"
+- "can't save money"
+- "finally debt free how"
+- "paycheck to paycheck"
+
+**Concursos:**
+- "estudar para concurso"
+- "reprovado de novo"
+- "finalmente passei"
+- "desistir de concurso"
+
+---
+
+## Amazon Reviews - Objeções e Desejos Estruturados
+
+### Por que Amazon é Poderoso
+- Reviews de 5★ = o que amam (desejos realizados)
+- Reviews de 1-2★ = o que odeiam (objeções reveladas)
+- Reviews de 3★ = expectativas não atendidas
+- Linguagem natural sobre resultados
+
+### Como Usar
+
+**1. Encontre produtos relacionados:**
+- Livros sobre o problema/solução
+- Suplementos/produtos concorrentes
+- Cursos e programas relacionados
+- Equipamentos/ferramentas do nicho
+
+**2. Foque em reviews de 1-3 estrelas:**
+- Frustrações com o produto
+- Expectativas não atendidas
+- Comparações com outros produtos
+- Histórias de uso
+
+**3. O que capturar:**
+- Frases que começam com "Eu esperava..."
+- Frases que começam com "Infelizmente..."
+- Descrições de resultados (ou falta deles)
+- Comparações explícitas
+
+### Padrões a Identificar
+
+**Reviews Positivos (5★):**
+- "Finalmente encontrei..."
+- "Isso mudou minha..."
+- "Eu não acreditava, mas..."
+- "Diferente de tudo que já tentei..."
+
+**Reviews Negativos (1-2★):**
+- "Não funcionou para mim porque..."
+- "Esperava mais porque..."
+- "O problema é que..."
+- "Igual a todos os outros..."
+
+---
+
+## YouTube - Comentários Reveladores
+
+### Por que YouTube Funciona
+- Vídeos sobre o problema atraem público qualificado
+- Comentários revelam perguntas reais
+- Histórias pessoais nos comentários
+- Linguagem informal e honesta
+
+### Como Usar
+
+**1. Encontre vídeos sobre o problema/solução:**
+- "[problema] como resolver"
+- "[solução] funciona?"
+- "[produto/método] review honesto"
+- Canais de especialistas no nicho
+
+**2. Ordene comentários por "Mais recentes":**
+- Mais emocionais
+- Menos filtrados
+- Perguntas genuínas
+
+**3. O que capturar:**
+- Perguntas que fazem
+- Histórias que compartilham
+- Objeções que levantam
+- Resultados que relatam
+
+### Sinais de Ouro
+- Comentários longos (investimento emocional)
+- Comentários com muitos likes
+- Threads de discussão (controvérsia = dor)
+- Perguntas específicas (gaps de informação)
+
+---
+
+## Quora - Perguntas Reveladoras
+
+### Por que Quora é Útil
+- Formato de pergunta = problema declarado
+- Respostas longas = contexto rico
+- Upvotes = validação do problema
+- Seguir tópicos = segmentação
+
+### Como Usar
+
+**1. Busque perguntas sobre o problema:**
+- "Como [resolver problema]?"
+- "Por que [sintoma] acontece?"
+- "Alguém já [conseguiu resultado]?"
+- "É possível [desejo]?"
+
+**2. Analise as perguntas populares:**
+- Número de seguidores da pergunta
+- Número de respostas
+- Qualidade das respostas
+
+**3. O que capturar:**
+- A pergunta em si (formulação do problema)
+- Contexto dado pelo perguntador
+- Respostas que geraram mais engajamento
+- Objeções levantadas nas respostas
+
+---
+
+## Google Autocomplete / People Also Ask
+
+### Por que é Valioso
+- Baseado em buscas reais
+- Revela preocupações comuns
+- Linguagem natural
+- Atualizado constantemente
+
+### Como Usar
+
+**1. Digite início de frase comum:**
+- "como emagrecer sem..."
+- "por que não consigo..."
+- "é possível..."
+- "[problema] mesmo depois de..."
+- "[solução] funciona para..."
+
+**2. Capture sugestões do autocomplete:**
+- Completações mais comuns
+- Variações de busca
+- Perguntas relacionadas
+
+**3. Explore "People Also Ask":**
+- Perguntas expandidas
+- Clique para revelar mais
+- Padrões de preocupação
+
+### Exemplos de Queries por Nicho
+
+**Emagrecimento:**
+- "como emagrecer..."
+- "por que engordo..."
+- "dieta que..."
+- "exercício para..."
+
+**Relacionamento:**
+- "como fazer ele..."
+- "por que meu marido..."
+- "como salvar..."
+- "sinais de que..."
+
+**Finanças:**
+- "como sair das..."
+- "por que não consigo..."
+- "investimento para..."
+- "como ganhar..."
+
+---
+
+## Fóruns e Grupos de Facebook
+
+### Por que São Valiosos
+- Comunidades ativas = problemas recorrentes
+- Moderação mínima = honestidade
+- Contexto social = dinâmicas reais
+- Histórias detalhadas
+
+### Como Usar
+
+**1. Encontre grupos/fóruns do nicho:**
+- Busca no Facebook por "[nicho] grupo"
+- Google: "[nicho] forum"
+- Comunidades em plataformas específicas
+
+**2. Identifique posts populares:**
+- Muitos comentários
+- Muitas reações
+- Tópicos recorrentes
+
+**3. O que capturar:**
+- Desabafos emocionais
+- Pedidos de ajuda
+- Histórias de sucesso
+- Debates e controvérsias
+
+---
+
+## Regras de Extração (Todos os Canais)
+
+### 5 Regras de Ouro
+
+**1. VERBATIM sempre**
+- Copie exatamente como escreveram
+- Não corrija gramática
+- Não resuma ou parafraseie
+- Mantenha erros de digitação (autenticidade)
+
+**2. Contexto importa**
+- Capture a situação, não só a frase
+- Inclua o "antes" e "depois"
+- Note o tom emocional
+- Registre reações de outros
+
+**3. Emoção > Lógica**
+- Priorize linguagem carregada
+- Busque extremos (odeio, amo, desespero)
+- Note metáforas e analogias
+- Capture frustrações viscerais
+
+**4. Repetição = Ouro**
+- Padrões em múltiplas fontes são verdade
+- Frases que aparecem várias vezes
+- Problemas mencionados repetidamente
+- Desejos expressos de formas similares
+
+**5. Triangulação**
+- Insight confiável = 2-3 fontes independentes
+- Cross-reference entre canais
+- Valide padrões antes de usar
+- Marque confidence score
+
+---
+
+## Template de Coleta
+
+### Para cada fonte, registre:
+
+```
+FONTE: [Reddit/Amazon/YouTube/Quora/Google]
+URL: [link específico]
+DATA: [quando foi postado]
+CONTEXTO: [situação do autor]
+QUOTE VERBATIM: "[exatamente como escreveram]"
+TIPO: [dor/desejo/objeção/linguagem]
+CONFIDENCE: [alto/médio/baixo]
+VALIDAÇÃO: [aparece em outras fontes? quais?]
+```
+
+### Categorização Sugerida
+
+**Por Tipo:**
+- DORES: frustrações, problemas, sintomas
+- DESEJOS: aspirações, resultados, transformação
+- OBJEÇÕES: ceticismo, medos, resistências
+- LINGUAGEM: termos, metáforas, expressões
+
+**Por Profundidade:**
+- SUPERFICIAL: o que dizem publicamente
+- INTERMEDIÁRIO: o que admitem em anonimato
+- PROFUNDO: o que revelam em vulnerabilidade
+
+**Por Frequência:**
+- COMUM: aparece em 5+ fontes
+- RECORRENTE: aparece em 2-4 fontes
+- ÚNICO: aparece em 1 fonte (usar com cautela)
+
+---
+
+## Checklist de Coleta Completa
+
+Antes de considerar a coleta de VOC completa, verifique:
+
+- [ ] Reddit pesquisado (mínimo 3 subreddits)
+- [ ] Amazon reviews analisados (mínimo 2 produtos)
+- [ ] YouTube comentários capturados (mínimo 3 vídeos)
+- [ ] Quora perguntas coletadas (mínimo 10)
+- [ ] Google autocomplete explorado
+- [ ] Mínimo 30 quotes verbatim coletados
+- [ ] Quotes categorizados por tipo
+- [ ] Padrões identificados e validados
+- [ ] Confidence scores atribuídos