@lucapimenta/copy-chief-black 1.0.0

package/framework/skills/voc-research-agent/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: voc-research-agent
+description: |
+  Skill técnica de extração VOC (Voice of Customer) via Apify actors.
+  Ativa quando: extrair comentários, coletar VOC, buscar quotes de YouTube/TikTok/Instagram/Reddit,
+  Reclame Aqui, Mercado Livre, Amazon. Chamado pelo audience-research-agent.
+---
+
+# VOC Research Agent
+
+> **WARNING: Este skill REQUER MCPs (Apify, Firecrawl, Playwright).**
+> Se invocado como subagent, o caller DEVE usar `subagent_type: general-purpose`.
+> O tipo `researcher` NÃO tem acesso a MCPs no runtime — ToolSearch indisponível.
+> Resultado sem general-purpose: 100% fallback para WebSearch = VOC de baixa qualidade.
+
+Skill técnica de extração Voice of Customer via Apify. Foco exclusivo: extrair, processar e salvar quotes verbatim.
+
+## Quick Start
+
+1. Receber plataforma + queries + limites do chamador
+2. Executar: Discovery (web_search) → Extração (Apify) → Processamento (batches) → Salvamento
+3. Retornar path do arquivo .md ao chamador
+→ Output: `voc_[plataforma]_[query]_[data].md` + status + totais
+
+## Output Location
+
+Write all outputs to:
+- Raw extraction: `research/{offer-name}/voc/raw/[plataforma]-[date].md`
+- Format: Markdown with YAML frontmatter
+
+**Return to caller:**
+```yaml
+status: success|partial|error
+arquivo_path: "research/{offer}/voc/raw/[plataforma]-[date].md"
+total_quotes: int
+total_fontes: int
+```
+
+**CRITICAL:** This agent writes to raw/. Caller (audience-research-agent) processes into processed/ and summary.md.
+
+## Posição no Ecossistema
+
+Este skill é uma ferramenta técnica, não agente autônomo. Chamado por outros agentes (principalmente audience-research-agent) para executar extrações.
+
+Responsabilidades: descobrir URLs via web_search, executar Apify actors, aplicar protocolo PROCESS-SAVE-FORGET, salvar arquivo .md, retornar path ao chamador.
+
+Não faz: análise psicográfica, classificação por frameworks, geração de insights, cálculo de scores. Toda análise é responsabilidade do chamador.
+
+## Interface
+
+Input esperado do chamador:
+
+```yaml
+plataforma: youtube|instagram|tiktok|reddit|amazon|reclameaqui|mercadolivre
+queries: list[string]
+limite_quotes: int  # default 150
+limite_urls: int    # default 5
+filtro_data: string # opcional, ex: "últimos 6 meses"
+```
+
+Output retornado:
+
+```yaml
+status: success|partial|error
+arquivo_path: string  # /home/claude/voc_[plataforma]_[query]_[data].md
+total_quotes: int
+total_fontes: int
+virais_analisados: int  # NOVO: quantos conteúdos virais foram analisados
+warnings: list[string]  # opcional
+```
+
+---
+
+## Tool Priority (OBRIGATÓRIO)
+
+**CRÍTICO:** Para cada plataforma, SEMPRE tentar ferramentas nesta ordem:
+
+1. **Apify Actor específico** (5min timeout) → Comentários REAIS
+2. **Playwright direto** (se Apify falha) → Navegação direta
+3. **Firecrawl search** (se Playwright falha) → Extração web
+4. **WebSearch** (ÚLTIMO RESORT - apenas se TUDO falha) → Conteúdo indexado
+
+**NUNCA pular direto para WebSearch sem tentar Apify primeiro.**
+
+Fluxo correto:
+```
+Tentar Apify Actor → Timeout/Erro?
+                   ├─ NÃO → Extrair comentários reais ✓
+                   └─ SIM → Retry 1x (transient failure)
+                            ├─ Sucesso → Extrair ✓
+                            └─ Falha → Tentar Firecrawl
+                                       ├─ Sucesso → Extrair ✓
+                                       └─ Falha → Tentar Playwright
+                                                  ├─ Sucesso → Extrair ✓
+                                                  └─ Falha → WebSearch (último resort)
+```
+
+Fluxo INCORRETO (problema identificado em 2026-01):
+```
+Tentar extração → WebSearch imediato → Blog content (NÃO VOC real) ✗
+```
+
+### MCP Failure Protocol (OBRIGATÓRIO)
+
+Se qualquer tool Apify retornar erro:
+1. **NÃO fazer fallback silencioso.** Logar o erro explicitamente.
+2. Retry UMA vez (sessões MCP podem ter falhas transientes).
+3. Se falhar de novo, seguir hierarquia (Firecrawl → Playwright → WebSearch).
+4. **O nome do arquivo DEVE refletir o método REAL usado:**
+   - Apify funcionou → `{platform}-apify.md`
+   - Fallback para Firecrawl → `{platform}-firecrawl.md`
+   - Fallback para WebSearch → `{platform}-websearch.md`
+5. **YAML header OBRIGATÓRIO em todo arquivo de extração:**
+```yaml
+---
+extraction_method: apify|firecrawl|playwright|websearch
+platform: youtube|tiktok|reddit|instagram|amazon
+apify_dataset_id: "abc123"  # só se Apify foi realmente usado
+fallback_reason: "Apify error: session expired"  # só se houve fallback
+tools_attempted: [apify, firecrawl]
+tools_succeeded: [firecrawl]
+---
+```
+6. No retorno ao chamador, SEMPRE incluir `extraction_method` e `tools_failed` se houver.
+
+---
+
+## Viral-First Strategy (OBRIGATÓRIO)
+
+Antes de extrair comentários, **SEMPRE** identificar conteúdo viral primeiro:
+
+### Passo 1: Descobrir Top 10 Virais
+Usar ferramenta de discovery para encontrar conteúdo mais engajado por plataforma.
+
+### Passo 2: Validar Engajamento Mínimo
+| Plataforma | Threshold Mínimo |
+|------------|------------------|
+| YouTube | 10K+ views OU 500+ comments |
+| Instagram | 5K+ likes OU 200+ comments |
+| TikTok | 50K+ views OU 1K+ comments |
+| Reddit | 100+ upvotes OU 50+ comments |
+| ReclameAqui | N/A (todas reclamações são válidas) |
+
+### Passo 3: Extrair Apenas de Virais
+- Extrair comentários APENAS dos top 10 conteúdos por engajamento
+- Priorizar comentários com mais likes/replies (mais autenticidade)
+- Registrar métricas de engajamento junto com cada quote
+
+### Passo 4: Análise de Formato (OBRIGATÓRIO)
+Para cada conteúdo viral, registrar:
+- **YouTube:** Duração, formato (talking head/slide/animação), hook do título, thumbnail style
+- **Instagram:** Tipo (carrossel/reel/estático), tema, estilo visual, caption hook
+- **TikTok:** Som/música, duração, formato (POV/storytime/duet), hook 3seg, hashtags
+
+---
+
+## Outputs Obrigatórios (v4.2)
+
+Cada extração DEVE gerar:
+
+1. **`*-viral-extraction.md`** - Quotes + tabela de virais analisados
+2. **Seção "Análise de Formato"** - Padrões identificados no conteúdo viral
+3. **Métricas de engajamento** - Views, likes, comments por fonte
+
+**Estrutura mínima do arquivo:**
+```markdown
+# [Plataforma] Viral VOC Extraction
+**Data:** [DATA] | **Método:** Apify [ACTOR]
+
+## Conteúdos Virais Identificados (Top 10)
+| # | URL | Título | Views | Comments | Formato | Hook |
+|---|-----|--------|-------|----------|---------|------|
+
+## Comentários Extraídos (50 min)
+### Quote #1
+- **Texto:** ""
+- **Username:** @
+- **Likes/Replies:**
+- **Contexto:** (vídeo/post de origem)
+- **Intensidade:** /5
+
+## Análise de Formato
+- Formato dominante:
+- Duração média:
+- Hooks que funcionam:
+- Estilo visual:
+```
+
+---
+
+## Workflow
+
+Etapa 1 - Discovery: receber plataforma + queries, executar web_search para URLs relevantes, filtrar por relevância e recência, limitar a 5 URLs por query para evitar overhead.
+
+Etapa 2 - Extração: selecionar Apify actor correto para plataforma (ver ref_apify_actors_by_platform.md), configurar parâmetros otimizados com fields mínimos e limites seguros, executar com timeout apropriado.
+
+Etapa 3 - Processamento: aplicar protocolo PROCESS-SAVE-FORGET (ver ref_protocol_process_save_forget.md). Processar em batches de 15 itens, truncar quotes em 400 chars, extrair apenas campos essenciais (texto, autor, data, url), salvar batch, limpar contexto antes do próximo. Se dataset excede 150 itens, aplicar sampling estratificado.
+
+Etapa 4 - Salvamento: criar arquivo voc_[plataforma]_[query]_[data].md em /home/claude/, retornar path ao chamador.
+
+## Formato de Saída
+
+```markdown
+# VOC Extraction: [Plataforma]
+> Query: [query original]
+> Data: [ISO date]
+> Total quotes: [number]
+> Fontes: [number] URLs
+
+## Quotes Extraídos
+
+### [URL 1]
+- "[quote truncado em 400 chars]" - @autor
+- "[quote 2]" - @autor
+
+### [URL 2]
+- "[quote 1]" - @autor
+
+---
+Extração completada via voc-research-agent
+```
+
+## Limites Operacionais
+
+Batch size: 15 itens. Batches maiores sobrecarregam o contexto e causam perda de qualidade. Quote length: 400 chars. URLs por query: 5. Quotes totais: 150, acima disso aplicar sampling. Detalhes em ref_limits_and_safety.md.
+
+## Execução Paralela
+
+Queries independentes podem ser descobertas em paralelo via múltiplos web_search simultâneos. Se Apify actor suporta array de URLs, passar todas em uma única chamada. Para 1-2 queries usar sequencial, 3-5 queries usar paralelo, 6+ queries usar waves de 5.
+
+## Referências
+
+Core (consultar sempre): ref_apify_actors_by_platform.md, ref_protocol_process_save_forget.md, ref_limits_and_safety.md.
+
+Por plataforma (carregar just-in-time quando extraindo): ref_platform_youtube.md, ref_platform_instagram.md, ref_platform_tiktok.md, ref_platform_reddit.md, ref_platform_amazon.md, ref_platform_br_reclameaqui.md, ref_platform_br_mercadolivre.md.
+
+## Extended Thinking
+
+Este skill executa principalmente operações técnicas. Extended thinking tem benefício limitado. Usar 2-4K tokens apenas para decisão de qual actor usar ou troubleshooting de erros. Para execução padrão de extração, processamento de batches e salvamento, thinking padrão é suficiente.
+
+---
+
+## Context Management (v6.1) ⚠️ NOVO
+
+> Fonte: `~/.claude/rules/voc-research.md` v6.1
+
+### Regra 60% para Extração
+
+**CRÍTICO:** Manter contexto abaixo de 60% durante extrações longas.
+
+| Threshold | Ação |
+|-----------|------|
+| <50% | Operação normal |
+| 50-60% | Monitoring, considerar batch |
+| 60-75% | Aplicar PROCESS-SAVE-FORGET imediatamente |
+| >75% | EMERGÊNCIA - salvar e reiniciar |
+
+### Lost in the Middle Mitigation
+
+```
+INÍCIO do contexto: Instruções VOC Protocol
+FIM do contexto: Batch atual sendo processado
+MEIO (descartável): Batches anteriores já salvos
+```
+
+### RAG Specs para Swipe Analysis
+
+> Ver `~/.claude/templates/swipe-analysis-specs.md` para integração RAG.
+
+| Spec | Valor |
+|------|-------|
+| Chunking | 400-600 tokens |
+| Overlap | 15-20% |
+| Formato | Markdown (5★ eficiência) |
+| Embeddings (se futuro) | Voyage AI voyage-4 |
+
+## Exemplos
+
+### Exemplo 1: Extração YouTube
+
+Input recebido:
+
+```yaml
+plataforma: youtube
+queries: ["dor nas costas exercício", "hérnia de disco tratamento"]
+limite_quotes: 100
+```
+
+Execução correta:
+
+1. web_search "dor nas costas exercício site:youtube.com" para descobrir 8 vídeos, selecionar top 5
+2. Apify streamers/youtube-scraper com startUrls das 5 URLs e maxResults 3 vídeos por URL
+3. Dataset retorna 75 comentários
+4. Batch 1 (items 1-15): extrair text/author/publishedAt, truncar 400 chars, salvar, limpar contexto
+5. Batch 2 (items 16-30): extrair, salvar, limpar
+6. Continuar até batch 5
+7. Arquivo final: /home/claude/voc_youtube_dorCostas_2025-01-08.md
+8. Retornar: "Extração concluída. Arquivo: [path]. Total: 75 quotes de 5 fontes."
+
+Execução incorreta: maxResults 50 por URL causa dataset muito grande. Processar 200 comentários de uma vez causa overflow. Retornar comentários no chat em vez de arquivo. Classificar por intensidade emocional (não é responsabilidade deste skill).
+
+### Exemplo 2: Protocolo com Dataset Grande
+
+Cenário: dataset retornou 180 comentários, limite é 150.
+
+Execução correta:
+- Batches 1-10: processar items 1-150 normalmente (15 por batch), cada batch salvar e esquecer
+- Sampling dos items 151-180: selecionar 15 representativos (30% por engajamento, 30% por recência, 40% aleatório)
+- Total processado: 165 quotes
+- Arquivo consolidado final
+
+Execução incorreta: processar todos 180 de uma vez causa overflow. Ignorar items 151-180 perde dados potencialmente valiosos. Manter batches anteriores em memória causa acúmulo.
+
+### Exemplo 3: Retorno ao Chamador
+
+Correto: "Extração concluída. Arquivo salvo: /home/claude/voc_youtube_dorCostas_2025-01-08.md. Total: 127 quotes de 5 fontes. Pronto para análise pelo audience-research-agent."
+
+Incorreto: despejar os 127 comentários no chat causa overflow garantido e não é o formato esperado.
+
+## Constraints
+
+- Batch size máximo: 15 itens (batches maiores sobrecarregam contexto)
+- Quote length máximo: 400 chars (truncar se maior)
+- URLs por query: 5 (evitar overhead)
+- Quotes totais: 150 (aplicar sampling acima disso)
+- NÃO fazer análise — responsabilidade é do chamador
+- SEMPRE retornar path do arquivo, nunca despejar quotes no chat
+
+## Integração planning-with-files
+
+- **Antes:** Verificar se `task_plan.md` existe (opcional para skill técnica)
+- **Durante:** Não aplicável (skill executa e retorna)
+- **Após:** Registrar path do arquivo gerado em `findings.md` se existir

package/framework/skills/voc-research-agent/references/CLAUDE.md

@@ -0,0 +1 @@
+# Context cleared

package/framework/skills/voc-research-agent/references/ref_apify_actors_by_platform.md

@@ -0,0 +1,45 @@
+# Apify Actors por Plataforma
+
+## YouTube
+
+Actor principal: streamers/youtube-scraper. Alternativa: apidojo/youtube-scraper. Transcrições: pintostudio/youtube-transcript-scraper.
+
+Campos essenciais: text, author, publishedAt, likeCount.
+
+## Instagram
+
+Posts: apify/instagram-post-scraper. Reels: apify/instagram-reel-scraper. Comentários: apify/instagram-comment-scraper. Perfis: apify/instagram-profile-scraper. Busca: apify/instagram-search-scraper.
+
+Campos essenciais: text, ownerUsername, timestamp.
+
+## TikTok
+
+Vídeos: clockworks/tiktok-scraper. Perfis: clockworks/tiktok-profile-scraper. Comentários: clockworks/tiktok-comments-scraper. Hashtags: clockworks/tiktok-hashtag-scraper. Alternativa: apidojo/tiktok-scraper.
+
+Campos essenciais: text, uniqueId, createTime, diggCount.
+
+## Reddit
+
+Principal: trudax/reddit-scraper-lite.
+
+Campos essenciais: body, author, created_utc, score.
+
+## Amazon
+
+Reviews: junglee/amazon-reviews-scraper ou epctex/amazon-reviews-scraper. Product search: apify/amazon-crawler.
+
+Campos essenciais: reviewBody, rating, reviewDate, reviewerName, verifiedPurchase.
+
+## Facebook
+
+Ads Library: apify/facebook-ads-scraper ou curious_coder/facebook-ads-library-scraper. Páginas: apify/facebook-pages-scraper. Comentários: apify/facebook-comments-scraper.
+
+## Plataformas BR
+
+Reclame Aqui: web_fetch + extração manual, sem actor dedicado confiável. Ver ref_platform_br_reclameaqui.md.
+
+Mercado Livre: web_fetch + extração manual. Ver ref_platform_br_mercadolivre.md.
+
+## Parâmetros Padrão Seguros
+
+YouTube: maxResults 5 vídeos por busca. Instagram: resultsLimit 30. TikTok: resultsPerPage 50, commentsPerPost 30. Reddit: maxPostCount 20, maxComments 30. Amazon: maxReviews 50 por produto.

package/framework/skills/voc-research-agent/references/ref_limits_and_safety.md

@@ -0,0 +1,41 @@
+# Limites e Configurações de Segurança
+
+## Limites Seguros
+
+Batch size: 15 itens é o limite seguro, máximo 20. Acima disso o contexto fica sobrecarregado e qualidade degrada.
+
+Quote length: 400 caracteres é o limite seguro, máximo 500. Quotes mais longos desperdiçam tokens sem adicionar valor proporcional.
+
+URLs por query: 5 é o limite seguro, máximo 10. Mais URLs aumentam timeout e custo sem ganho proporcional de dados.
+
+Quotes totais: 150 é o limite seguro, máximo 200. Acima disso aplicar sampling. Processamento fica muito lento com volumes maiores.
+
+Queries paralelas: 5 é o limite seguro, máximo 10. Rate limiting pode ocorrer com muitas requisições simultâneas.
+
+## Campos Essenciais por Plataforma
+
+YouTube: text (comentário), author, publishedAt, likeCount (para ordenação por relevância).
+
+Instagram: text, ownerUsername, timestamp.
+
+TikTok: text, uniqueId (autor), createTime, diggCount (likes).
+
+Reddit: body, author, created_utc, score.
+
+Amazon: reviewBody, rating, reviewDate, reviewerName, verifiedPurchase.
+
+Plataformas BR: titulo, texto, autor (se disponível), data, status (para Reclame Aqui).
+
+Ignorar campos não-essenciais para economizar tokens e processamento.
+
+## Timeouts Recomendados
+
+YouTube: 120 segundos. Instagram: 180 segundos (mais restritivo). TikTok: 120 segundos. Reddit: 90 segundos. Amazon: 120 segundos. Web fetch para plataformas BR: 30 segundos.
+
+## Rate Limits
+
+Se receber erro de rate limit: aguardar 60 segundos, fazer retry com limite reduzido. Se persistir, documentar o problema e prosseguir com dados parciais já coletados. Não insistir indefinidamente.
+
+## Custos Aproximados Apify
+
+YouTube aproximadamente $0.50 por 1000 results. Instagram aproximadamente $1.00 por 1000 (mais caro por restrições). TikTok $0.30-0.75 por 1000. Reddit $0.50 por 1000. Amazon $0.50-1.00 por 1000. Otimizar solicitando apenas campos necessários reduz custo.

package/framework/skills/voc-research-agent/references/ref_platform_amazon.md

@@ -0,0 +1,23 @@
+# Amazon Extraction
+
+## Actors Disponíveis
+
+Para reviews de produto: junglee/amazon-reviews-scraper ou epctex/amazon-reviews-scraper. Input: productUrls (array de URLs de produtos), maxReviews 50 por produto.
+
+Para busca de produtos: apify/amazon-crawler com keyword e país.
+
+## Estratégia de Discovery
+
+Executar web_search com "[produto/categoria] site:amazon.com.br reviews" ou "site:amazon.com" para encontrar produtos relevantes do nicho. Focar em produtos com 100+ reviews para volume adequado.
+
+## Campos para Extrair
+
+Extrair: reviewBody (texto da review), rating (1-5 estrelas), reviewDate, reviewerName, verifiedPurchase (importante para credibilidade).
+
+## Foco de Extração para VOC
+
+Reviews 1-2 estrelas contêm dores, frustrações e objeções. Reviews 4-5 estrelas contêm desejos realizados e linguagem positiva. Reviews 3 estrelas frequentemente têm comparações e expectativas não atendidas. Filtrar por verifiedPurchase true para reviews mais autênticas.
+
+## Notas Importantes
+
+Amazon BR (amazon.com.br) para mercado brasileiro, Amazon US (amazon.com) para referência internacional. Reviews de Amazon são especialmente valiosas para produtos físicos e suplementos. Linguagem tende a ser mais objetiva que redes sociais, foca em resultados concretos.

package/framework/skills/voc-research-agent/references/ref_platform_br_mercadolivre.md

@@ -0,0 +1,41 @@
+# Mercado Livre Extraction
+
+Não há actor Apify dedicado confiável para Mercado Livre. Usar web_fetch + extração manual.
+
+## Estratégia de Discovery
+
+Executar web_search com "[produto concorrente] site:mercadolivre.com.br avaliações" ou "[produto] mercado livre opiniões" para encontrar páginas de produto com reviews.
+
+## URL Patterns
+
+Página de produto: mercadolivre.com.br/[produto-slug]/p/[ID] ou produto.mercadolivre.com.br/[produto-slug]
+
+Seção de avaliações: geralmente na mesma página, scroll ou tab de "Opiniões"
+
+## Campos para Extrair
+
+texto_review: corpo da avaliação.
+
+nota: 1-5 estrelas.
+
+data: quando foi postada.
+
+titulo: se disponível.
+
+## Foco para VOC
+
+Reviews 1-2 estrelas contêm dores e frustrações com produto/entrega. Reviews 5 estrelas contêm desejos realizados, linguagem de satisfação. Perguntas frequentes na página do produto revelam objeções e dúvidas comuns antes da compra.
+
+## Exemplo de Output
+
+Reviews Negativos (1-2 estrelas):
+- "Não funcionou como prometido. Devolvi." (1 estrela, 2025-01-04)
+- "Qualidade péssima, quebrou em 1 semana." (1 estrela, 2025-01-02)
+
+Reviews Positivos (5 estrelas):
+- "Finalmente algo que funciona! Recomendo." (5 estrelas, 2025-01-03)
+- "Melhor investimento que fiz." (5 estrelas, 2025-01-01)
+
+## Limitações
+
+Extração mais lenta sem actor dedicado. Estrutura HTML pode mudar, verificar parsing se falhar. Usar como complemento de outras fontes, não como fonte principal.

package/framework/skills/voc-research-agent/references/ref_platform_br_reclameaqui.md

@@ -0,0 +1,37 @@
+# Reclame Aqui Extraction
+
+Não há actor Apify dedicado confiável para Reclame Aqui. Usar web_fetch + extração manual.
+
+## Estratégia de Discovery
+
+Executar web_search com "[nome do concorrente] site:reclameaqui.com.br" para descobrir página da empresa.
+
+## URL Patterns
+
+Página da empresa: reclameaqui.com.br/empresa/[slug]/
+
+Lista de reclamações: reclameaqui.com.br/empresa/[slug]/lista-reclamacoes/
+
+Reclamação específica: reclameaqui.com.br/[slug-empresa]/[titulo-reclamacao]/[id]/
+
+## Campos para Extrair
+
+titulo_reclamacao: headline emocional, frequentemente contém linguagem de frustração concentrada.
+
+texto_reclamacao: corpo da queixa, truncar em 400 chars.
+
+status: resolvido, nao_resolvido, nao_respondida. Não resolvidas têm frustração máxima.
+
+data: quando foi postada.
+
+nota_consumidor: se disponível após resolução.
+
+## Foco para VOC
+
+Priorizar reclamações NÃO RESOLVIDAS, contêm frustração máxima e linguagem emocional autêntica. Títulos das reclamações são especialmente valiosos, condensam a dor em uma frase. Analisar respostas da empresa para identificar gaps de atendimento e objeções comuns.
+
+## Exemplo de Extração
+
+web_fetch da página de reclamações, parsear HTML para extrair lista. Para cada reclamação relevante, extrair campos. Formato de output:
+
+"PRODUTO NÃO FUNCIONA E NINGUÉM RESOLVE" (não resolvido, 2025-01-05): "Comprei o produto há 3 meses e até hoje não consegui usar..." - @usuario

package/framework/skills/voc-research-agent/references/ref_platform_instagram.md

@@ -0,0 +1,87 @@
+# Instagram Extraction
+
+## IMPORTANTE: Tool Priority
+**SEMPRE usar Apify para extração de Instagram. WebSearch é ÚLTIMO RESORT.**
+
+Ordem obrigatória:
+1. Apify actors (5min timeout)
+2. Playwright direto se Apify falha
+3. Firecrawl se Playwright falha
+4. WebSearch APENAS se tudo falha
+
+**NUNCA pular direto para WebSearch.**
+
+---
+
+## Actors Disponíveis
+
+Para comentários de posts/reels específicos: apify/instagram-comment-scraper com directUrls (array de URLs de posts ou reels), resultsLimit 50 por post, includeNestedComments true para capturar replies.
+
+Para posts de um perfil: apify/instagram-post-scraper com username e resultsLimit 30.
+
+Para busca por hashtag ou local: apify/instagram-hashtag-scraper com hashtags (array), resultsLimit 50.
+
+Alternativa para search: apify/instagram-search-scraper com search (termo), searchType ("hashtag", "place" ou "user"), searchLimit 10.
+
+---
+
+## Viral-First Strategy (OBRIGATÓRIO)
+
+### Passo 1: Discovery de Virais via Hashtag
+**USAR hashtag-scraper PRIMEIRO para descobrir conteúdo viral:**
+- Actor: `apify/instagram-hashtag-scraper`
+- Hashtags relevantes ao nicho
+- Sort by: engagement (likesCount + commentsCount)
+- Threshold mínimo: **5K+ likes OU 200+ comments**
+
+### Passo 2: Registrar Métricas
+Para cada post viral, capturar:
+- likesCount
+- commentsCount
+- type (Image/Video/Carousel/Reel)
+- timestamp
+
+### Passo 3: Análise de Formato
+Registrar para cada viral:
+- **Tipo:** carrossel / reel / estático / stories
+- **Tema:** meme / dica / desabafo / motivacional / tutorial
+- **Estilo visual:** clean / meme / screenshot / UGC
+- **Caption hook:** primeiras 2 linhas
+- **Hashtags usadas:** top 5
+
+### Passo 4: Extrair Comentários dos Top 10
+- Actor: `apify/instagram-comment-scraper`
+- directUrls: URLs dos 10 posts mais engajados
+- resultsLimit: 5 por post (mais curtidos)
+- Target: 50 comments de alta qualidade
+
+---
+
+## Estratégia de Discovery
+
+**Workflow em 2 etapas:**
+1. Usar `apify/instagram-hashtag-scraper` com hashtags do nicho
+2. Ordenar resultados por engagement
+3. Selecionar top 10 posts virais
+4. Usar `apify/instagram-comment-scraper` nos selecionados
+
+Focar em posts com alto engajamento (muitos comentários). Reels tendem a ter mais comentários autênticos que posts estáticos de imagem.
+
+## Campos para Extrair
+
+Extrair: text (comentário), ownerUsername (autor), timestamp (data), likesCount (para priorização).
+
+**NOVO - Métricas do post fonte:** likesCount, commentsCount, type, caption (para análise de formato).
+
+## Notas Importantes
+
+Instagram é mais restritivo que outras plataformas, usar limites menores. Comentários tendem a ser mais curtos que YouTube, compensar com mais fontes. Verificar se conta é pública antes de tentar extrair, contas privadas não retornam dados.
+
+---
+
+## Output Obrigatório
+
+Cada extração Instagram deve gerar:
+1. Tabela de virais (10 posts com métricas)
+2. 50 quotes de alta qualidade
+3. Seção de análise de formato (tipo, tema, estilo, hooks)

package/framework/skills/voc-research-agent/references/ref_platform_reddit.md

@@ -0,0 +1,27 @@
+# Reddit Extraction
+
+## Actor Principal
+
+trudax/reddit-scraper-lite
+
+Para busca por termo: searches (array de termos), searchPosts true, searchComments true, maxPostCount 20, maxComments 30, sort "new" ou "relevance" ou "hot" ou "top".
+
+Para subreddit específico: startUrls com URL do subreddit, maxPostCount 30.
+
+Para post específico: startUrls com URL do post, maxComments 100, skipCommunity true.
+
+## Campos para Extrair
+
+Extrair: body (texto do comentário ou post), author (username), created_utc (timestamp), score (upvotes para relevância).
+
+## Subreddits Úteis por Nicho
+
+Emagrecimento: r/loseit, r/intermittentfasting, r/keto, r/progresspics. Diabetes: r/diabetes, r/diabetes_t2. Fitness: r/fitness, r/bodyweightfitness, r/xxfitness. Relacionamento: r/relationship_advice, r/dating_advice. Ansiedade e saúde mental: r/anxiety, r/mentalhealth, r/depression. Finanças: r/personalfinance, r/investing, r/povertyfinance.
+
+## Estratégia de Discovery
+
+Executar web_search com "[tema] site:reddit.com" para encontrar posts relevantes. Identificar subreddits ativos do nicho. Posts com muitos comentários são fontes ricas de VOC.
+
+## Notas Importantes
+
+Reddit tem comentários mais longos e detalhados que outras plataformas, excelente para VOC. Usar proxy RESIDENTIAL para melhor taxa de sucesso. Sort por "top" retorna comentários mais validados pela comunidade. Reddit é especialmente bom para dores e frustrações genuínas porque usuários são anônimos.