Pesquisa Profunda com Perplexity

Chame a API do Perplexity Agent (POST /v1/agent) para realizar pesquisas de navegação em várias etapas com citações. Antes de chamar a API, este skill exige um loop estruturado de coleta + aprovação do plano, para que o agente use as fontes certas, tenha o contexto adequado e retorne um relatório em formato escaneável.

Metodologia

Este skill é uma aplicação programática do playbook de pesquisa profunda do Growth Unhinged para GTM: https://www.growthunhinged.com/p/deep-research-for-gtm. As cinco recomendações do artigo mapeiam 1:1 para as etapas abaixo:

Recomendação do artigo	Implementado por
Fornecer contexto abrangente (objetivo, GTM/produto, restrições, fontes preferidas)	Etapa 1 — coleta de cinco dimensões
Solicitar um plano de pesquisa primeiro, aprovar antes de executar	Etapa 2 — portão de aprovação do plano (sem gasto de API sem aprovação)
Apontar para fontes de alta qualidade; preferir primárias a secundárias; citar tudo	Bloco de formato — Tabela de fontes, prioridade de fontes primárias, citações inline obrigatórias
Especificar formato do relatório; resumos e tabelas em vez de prosa (Princípio da Pirâmide)	Bloco de formato — TL;DR primeiro, tabelas de comparação, conclusões antes do contexto
Estruturar o prompt (`<objetivo>`, `<contexto>`, `<fontes>`, `<instruções>`)	Layout do bloco `--instructions`

A verificação do orçamento de saída por chamada (Etapa 2.5) e o sequenciamento de múltiplas chamadas (Etapa 2.6) são adições em relação ao artigo, para evitar o modo de falha de truncamento silencioso que grandes planos de GTM (bibliotecas de hooks, calendários de 30 dias, matrizes de fornecedores) sofrem rotineiramente.

Pré-requisitos

PERPLEXITY_API_KEY disponível no ambiente (obtenha uma em https://www.perplexity.ai/account/api)
curl e jq instalados

Execute a verificação prévia uma vez no primeiro uso para confirmar que tudo está configurado:

bash ./scripts/check-setup.sh

Ele imprime ✓/✗ para cada requisito e uma correção copiável para o que estiver faltando. Sai com 0 quando estiver pronto. Se alguma verificação falhar, mostre a saída ao usuário e pare — não tente executar o script da API até que a verificação prévia seja aprovada.

Quando Usar

O usuário pede explicitamente por "pesquisa profunda", "pesquisa avançada" ou "pesquisa perplexity"
O usuário precisa de um resumo com fontes (empresa, pessoa, evento, tecnologia, regulamentação)
Perguntas que exigem navegação em várias etapas e síntese de muitas fontes
Perguntas que exigem informações muito recentes com citações inline

NÃO usar para:

Consultas factuais simples ("qual é o preço atual de X") — use WebSearch / WebFetch (mais barato, mais rápido)
Comparações binárias simples ("a ferramenta A ou B é melhor") — uma única rodada de WebSearch geralmente resolve
Conteúdo autenticado ou atrás de paywall (Perplexity não pode fazer login)
Edições rápidas de código ou perguntas respondíveis a partir do código-fonte — inline é mais rápido
Verificar um fato específico sobre o qual você já tem contexto — WebFetch é preciso o suficiente

Fluxo de Trabalho (OBRIGATÓRIO — não pule etapas)

Pesquisas profundas custam dinheiro real e levam de 2 a 5 minutos. Uma execução ruim desperdiça ambos. Sempre siga este loop:

Etapa 0 — Verificar configuração (apenas na primeira execução)

Se esta for a primeira invocação no projeto, execute bash ./scripts/check-setup.sh e só continue se ele sair com 0. Se relatar uma ferramenta faltando ou chave não definida, mostre a correção e pare. Pule esta etapa em execuções subsequentes na mesma sessão.

Etapa 1 — Auditar a consulta inicial, depois perguntar APENAS o que estiver faltando

Primeiro, leia a consulta inicial do usuário e determine quais das cinco dimensões de contexto abaixo já foram respondidas, quais foram respondidas parcialmente e quais estão totalmente ausentes. Não pergunte novamente coisas que o usuário já informou.

As cinco dimensões:

Objetivo e motivação — o que estão tentando alcançar, como o resultado será usado (decisão, documento, pitch, estratégia), trabalho prévio já realizado.
Contexto do produto/situação — a empresa/produto/função, como opera, detalhes relevantes de configuração (tamanho, estágio, GTM, público).
Restrições — orçamento, prazos, equipe, conformidade legal, opções descartadas, itens não negociáveis.
Fontes preferidas — especialistas/criadores nomeados, tipos de publicação (acadêmica, dados primários/governamentais, fóruns, analistas, arquivos da SEC, GitHub, etc.), domínios permitidos vs. bloqueados, janela de atualidade.
Limites de escopo — o que está explicitamente fora do escopo, suposições que o agente NÃO deve fazer.

Decida se deve perguntar:

Se todas as cinco dimensões estiverem suficientemente respondidas → pule a clarificação e vá direto para a Etapa 2 (elaborar o plano). Não faça perguntas apenas para confirmar o que você já sabe.
Se uma ou mais dimensões estiverem faltando ou ambíguas → use AskUserQuestion para perguntar apenas sobre as lacunas, em um único bloco consolidado. Liste explicitamente o que você já entendeu (para que o usuário possa corrigir) e o que ainda precisa.
Se o usuário disser "apenas vá" / "use seu julgamento" → pule para a Etapa 2 e liste suas suposições para cada dimensão faltante no plano, para que o usuário ainda possa corrigi-las lá.

Tenda a fazer menos perguntas. Uma consulta bem especificada de um parágrafo muitas vezes não precisa de clarificação — vá direto ao plano.

Etapa 2 — Elaborar um plano de pesquisa e obter aprovação

Antes de chamar a API, elabore um plano de pesquisa em sua resposta e peça ao usuário para aprová-lo ou editá-lo. O plano deve incluir:

Perguntas de pesquisa — as subperguntas específicas que o agente responderá
Metodologia — como avaliará/comparará opções, qual framework usará
Estratégia de fontes — quais tipos de fontes priorizará, quais evitará, quaisquer filtros de domínio ou janela de atualidade
Estrutura do relatório — títulos de seções que o relatório final usará
Entregáveis — além de prosa, haverá tabelas, matrizes de comparação, modelos, listas de verificação, trechos de código?
Suposições abertas — qualquer coisa que você esteja supondo e que o usuário deva corrigir

Aguarde aprovação explícita ("parece bom", "vá", "execute", edições no plano, etc.) antes de prosseguir. Se o usuário editar o plano, re-confirme antes de executar.

Etapa 2.5 — Verificação do orçamento de saída (OBRIGATÓRIA — evita truncamento)

O preset advanced-deep-research tem um teto prático de saída em torno de ~16k tokens / ~10k palavras por resposta. Planos que excedem isso são truncados silenciosamente — seções listadas no sumário simplesmente não aparecem, e grandes entregáveis (bibliotecas de hooks, calendários de N dias, catálogos de antipadrões) são cortados no meio de uma tabela. Você deve fazer um orçamento contra esse teto ANTES de executar.

Orçamento de saída por chamada (limites rígidos):

Item	Máx. por chamada
Seções principais (H2)	8
Tabelas grandes (6+ linhas, 4+ colunas)	4
Bibliotecas/catálogos detalhados (hooks, templates, exemplos, ideias)	10 itens no total em todas as bibliotecas
Entregáveis de formato longo (calendários de N dias, scripts cena por cena, playbooks completos)	1
Prosa total (excluindo tabelas)	~4.000 palavras

Sinais de alerta de que seu plano é grande demais para uma chamada:

Sumário tem >8 seções
Plano promete "25+ hooks" / "calendário de 30 dias" / "20 templates" junto com múltiplas matrizes
Plano pede vários grandes entregáveis na mesma chamada (ex.: biblioteca de hooks E calendário de conteúdo E template cena por cena E catálogo de antipadrões)
Plano cobre >1 segmento de público distinto ou >1 objetivo distinto em profundidade

Se o plano se encaixa no orçamento → prossiga para a Etapa 3.

Se o plano excede o orçamento → divida-o em um plano sequencial de múltiplas chamadas (veja "Sequenciamento de múltiplas chamadas" abaixo) e apresente-o ao usuário para aprovação.

Etapa 2.6 — Sequenciamento de múltiplas chamadas (para escopos grandes OU pesquisa dependente)

Existem duas razões separadas para dividir em múltiplas chamadas sequenciais, e ambas usam a mesma mecânica:

(A) Divisão por orçamento — o plano excede o teto de saída por chamada da Etapa 2.5. Divida em chamadas focadas, cada uma com UM entregável principal.

(B) Divisão por dependência — o escopo da chamada N depende das descobertas da chamada N-1. Exemplo: um levantamento de mercado de fornecedores (chamada 1) informa quais 3 fornecedores receberão análises aprofundadas (chamadas 2–4). Isso não é sobre tamanho — é sobre permitir que chamadas posteriores reajam ao que chamadas anteriores descobrirem. Não tente pré-planejar tudo antecipadamente quando você realmente não sabe a resposta até executar a chamada 1.

Regras para qualquer divisão em múltiplas chamadas:

Execute chamadas sequencialmente, não em paralelo — cada chamada deve poder citar ou construir sobre resultados anteriores.
Cada chamada deve ter UM foco de entregável principal.
Cada chamada deve permanecer dentro do orçamento por chamada da Etapa 2.5.
Cada chamada deve ser individualmente valiosa — não crie chamadas que só façam sentido em combinação.
Em cada chamada subsequente, no --instructions, cole as principais descobertas das chamadas anteriores (não o relatório completo — apenas as conclusões importantes, ~200–400 palavras) sob um cabeçalho PRIOR FINDINGS (não pesquisar novamente) para que o agente não perca etapas recobrindo terreno.
Após cada chamada ser concluída, Read a saída, verifique se nada foi truncado (confira se cada seção no sumário da chamada está presente e se nenhuma tabela termina no meio de uma linha) e resuma brevemente ao usuário antes de iniciar a próxima chamada.

Apresente a divisão como:

Este plano precisa de N chamadas sequenciais porque <motivo de orçamento/dependência>:
  Chamada 1 — <foco>  (~$X, ~3 min)
  Chamada 2 — <foco>  (~$X, ~3 min)
  ...
Custo total estimado: $X. Aprove a divisão, ou diga o que cortar.

Aguarde aprovação explícita da divisão antes de executar qualquer chamada. Se o usuário editar a divisão, re-confirme.

Etapa 3 — Executar a pesquisa

Uma vez aprovado, invoque o script. Passe o plano + contexto + requisitos de formato aprovados via --instructions. Use as flags --domains e --recency quando o usuário as especificar.

Sempre passe --topic <slug> para que a saída caia em um subdiretório de tópico em ./docs/research/. Antes de invocar, inspecione os subdiretórios existentes (ls docs/research/) e reutilize um slug existente que corresponda à área de pesquisa ou crie um novo slug curto em kebab-case. Se estiver criando um novo tópico, escolha algo durável — um slug que você ainda usaria para os próximos 3–5 relatórios na mesma área, não uma frase única da pergunta atual. Exemplos de slugs bons: comparacao-fornecedores, analise-competitiva, atualizacao-regulatoria, <area-produto>. Exemplos de slugs ruins: doppler-vs-vault-2026 (muito específico e vinculado à data).

O script está em ./scripts/research.sh (relativo a este SKILL.md). Quando invocado por um agente, use esse caminho relativo ao skill — ele resolve corretamente tanto em instalações npx skills quanto em instalações /plugin do Claude Code.

bash ./scripts/research.sh \
  --preset advanced-deep-research \
  --output ./docs/research \
  --topic <slug-do-topico> \
  --instructions "$(cat <<'EOF'
<cole o plano aprovado + contexto + requisitos de formato aqui>
EOF
)" \
  "<a pergunta de pesquisa, refinada a partir do plano aprovado>"

Etapa 4 — Ler o relatório e resumir

O script imprime o caminho do markdown. Sempre Read esse arquivo antes de relatar de volta.

Verificação de truncamento (obrigatória):

Confirme se cada seção listada no sumário do relatório está realmente presente no corpo.
Confirme se nenhuma tabela termina no meio de uma linha e se nenhuma lista detalhada termina no meio de um item.
Confirme se as seções "Fontes", "Onde as fontes discordam" e "Confiança e lacunas" no final estão presentes.

Fluxo de recuperação de truncamento. Se algum desses estiver faltando → a saída foi truncada. Faça o seguinte:

Identifique exatamente o que está faltando. Compare o sumário do relatório com seu corpo. Liste as seções faltantes, tabelas incompletas (anote a última linha completa) e itens de lista cortados (anote o último item completo).
Quantifique o trabalho restante. "X seções, Y itens, Z linhas ainda necessárias."
Proponha uma chamada de acompanhamento focada com um escopo que se encaixe no orçamento por chamada. NÃO tente o mesmo escopo novamente — ele truncará de novo.
Inclua PRIOR FINDINGS no --instructions da chamada de acompanhamento — cole um resumo de ~200–400 palavras das seções concluídas para que o agente não as pesquise novamente. Diga explicitamente "não recubra X, Y, Z; foque apenas em A, B, C."
Informe o usuário sobre o que foi truncado e mostre o plano de acompanhamento antes de executar.

Mostre: principais insights, o custo em USD do relatório, quaisquer discordâncias notáveis entre fontes e uma flag de truncamento, se aplicável.

Padrões Avançados

Esses padrões melhoram consistentemente a qualidade da saída. Use-os na Etapa 2 ao elaborar o plano.

Cite especialistas ou frameworks específicos em sua consulta

Nomear 3–6 especialistas, autores, criadores ou frameworks nomeados relevantes na consulta dá ao agente fontes concretas para pesquisar e comparar. O relatório se torna uma comparação de pontos de vista conhecidos, em vez de uma síntese anônima.

Fragmentos de consulta de exemplo:

"Compare os frameworks usados por , e para..."
"De acordo com a metodologia do , avalie..."
"Reconcilie as abordagens recomendadas por (em <livro/blog>) vs ..."

Funciona melhor quando os especialistas publicam regularmente (artigos, vídeos, posts, palestras) — o agente pode buscar o material primário deles.

Especifique entregáveis quantificados

Em vez de pedir "um bom número de exemplos", declare a contagem e a forma exatas. Isso trava o escopo, evita desvios e revela quando você está acima do orçamento (cruze com a Etapa 2.5).

Boas especificações de entregáveis:

"Uma matriz de comparação: 8 linhas (uma por fornecedor), 5 colunas (preço, latência, autenticação, SDKs, conformidade)"
"Uma biblioteca de exatamente 10 templates, agrupados em 3 categorias"
"Uma sequência de 14 dias com um item por dia"

Evite: "uma biblioteca abrangente", "vários exemplos", "muitas opções" — estes são convites para truncar ou oscilar.

Pré-carregue contexto em `--instructions`, não na consulta

A consulta deve permanecer uma frase curta de 1–2 sentenças. Qualquer coisa sobre a situação do usuário, restrições, decisões anteriores ou preferências de fonte vai em --instructions. Isso mantém as consultas de busca do agente focadas enquanto a síntese permanece ancorada em seu contexto.

Instruções de formato obrigatórias (incluir sempre em `--instructions`)

Cada execução deve incorporar estes requisitos de formato na string --instructions para que o relatório seja escaneável e confiável:

RESTRIÇÃO DE ESCOPO E TAMANHO (leia primeiro — isso determina a estrutura do relatório):

- Máximo de 8 seções H2 (incluindo esta).
- Máximo de 4 tabelas grandes (6+ linhas, 4+ colunas).
- Máximo de 10 itens no total em quaisquer bibliotecas/catálogos combinados.
- Máximo de 1 entregável de formato longo.
- Prosa total (excluindo tabelas): ~4.000 palavras.
- Se qualquer seção, tabela ou biblioteca exceder esses limites, pare e informe ao usuário — não entregue saída truncada.

ESTRUTURA DO RELATÓRIO:

1. **TL;DR** (3–5 marcadores ou uma tabela de 1 linha: o que, por que, resultados principais, principais fontes, nível de confiança)
2. **Principais descobertas** (tabela de comparação ou lista priorizada com destaques)
3. **Contexto / background** (breve — apenas o necessário para entender as descobertas)
4. **Análise aprofundada** (subseções conforme necessário, cada uma com uma conclusão no início)
5. **Onde as fontes discordam** (sem esconder debates — mostre ambos os lados com citações)
6. **Confiança e lacunas** (o que é certo, o que é incerto, o que ainda precisa de pesquisa)
7. **Entregáveis** (tabelas, modelos, bibliotecas, listas de verificação que foram solicitados)
8. **Fontes** (lista com links numerados — prioridade: dados primários > relatórios > blogs > fóruns; citações inline usam [n])

DIRETRIZES DE CONTEÚDO:

- Cada afirmação importante deve ser citada com uma fonte primária. Se nenhuma fonte primária existir, cite uma fonte secundária forte e marque como "secundária".
- Sempre mostre a data da fonte entre parênteses ao lado de cada citação, ex.: [1] (2025-02-15).
- Ao comparar opções, use uma tabela, não prosa.
- Evite linguagem excessivamente promocional ou negativa — atenha-se a afirmações apoiadas por citações.
- Para qualquer coisa que você não tenha certeza, diga isso explicitamente na seção "Confiança e lacunas" — não invente.
- O relatório deve ser compreensível para alguém que lê apenas o TL;DR e as tabelas.

Detalhes de Configuração

Opções do Script

Flag	Obrigatório	Descrição
`--preset`	Sim	Modelo de pesquisa (`advanced-deep-research` para pesquisa profunda, `research` para pesquisa regular)
`--output`	Sim	Diretório de saída para resultados de pesquisa
`--topic`	Sim	Nome do tópico para organização do relatório (kebab-case, slug durável)
`--instructions`	Não	Instruções e contexto de pesquisa detalhados
`--domains`	Não	Filtros de domínio (separados por vírgula)
`--recency`	Não	Janela de atualidade (dias; padrão: sem restrição)
`--model`	Não	Modelo (padrão: `sonar-pro`); `sonar-deep-research` também disponível

Variáveis de Ambiente

Variável	Obrigatório	Descrição
`PERPLEXITY_API_KEY`	Sim	Chave de API do Perplexity

Estrutura de Saída

Para cada chamada, um arquivo markdown é criado em:

./docs/research/<topic-slug>/<carimbo-data-hora>-<topic-slug>.md

O carimbo de data/hora está no formato ISO 8601, permitindo que múltiplos relatórios no mesmo tópico coexistam e sejam ordenados por data.

Custos Estimados

Preset	Custo por chamada	Duração típica
`research`	~$0.50	~30–60 segundos
`advanced-deep-research`	~$2.00	~2–5 minutos

Os custos são aproximados. Custos reais podem variar com base na complexidade da consulta e no número de consultas de busca.

Exemplos

Exemplo 1: Pesquisa de concorrente (pequena, uma chamada)

bash ./scripts/research.sh \
  --preset advanced-deep-research \
  --output ./docs/research \
  --topic analise-concorrencia \
  --instructions "$(cat <<'EOF'
OBJETIVO: Comparar os recursos de produto, preços e avaliações de clientes do Competidor X e do Competidor Y no espaço de automação de marketing.
CONTEXTO: Nosso produto é uma ferramenta de automação de marketing para PMEs focada em simplicidade. Preço é um fator chave. Precisamos de dados dos últimos 6 meses.
FONTES PREFERIDAS: G2, Capterra, sites oficiais de documentação de produtos, artigos de analistas do setor (Gartner, Forrester).
ENTREGÁVEIS:
- Matriz de comparação de recursos (10 linhas, 4 colunas: recurso, X, Y, notas)
- Tabela de comparação de preços (3 linhas, 3 colunas: plano, X, Y)
- Trechos de avaliações de clientes (máx. 5 por concorrente, com classificação por estrelas e plataforma)
EOF
)" \
  "Quais são as principais diferenças entre o Competidor X e o Competidor Y em automação de marketing para PMEs?"

Exemplo 2: Pesquisa regulatória (grande, três chamadas)

Este plano precisa de 3 chamadas sequenciais porque o escopo excede o orçamento de saída por chamada:
  Chamada 1 — Linha do tempo regulatória e órgãos reguladores  (~$1, ~3 min)
  Chamada 2 — Requisitos de conformidade e penalidades        (~$1, ~3 min)
  Chamada 3 — Impacto no setor e estratégias de preparação    (~$1, ~3 min)
Custo total estimado: $3. Aprove a divisão, ou diga o que cortar.

Notas sobre a Implementação

O script usa a API POST /v1/agent do Perplexity com streaming para fornecer feedback em tempo real.
Os resultados são salvos como markdown com metadados (modelo, carimbo de data/hora, custo, duração).
O preset advanced-deep-research executa iterações de busca interna e síntese, resultando em pesquisas mais profundas com maior custo.
Todas as chamadas de API e tempos de resposta são registrados para depuração e rastreamento de custos.
Se uma chamada falhar (por exemplo, tempo limite, erro de API), nenhum resultado parcial é salvo — a falha é relatada ao usuário para nova tentativa.

Solução de Problemas

Erro: "PERPLEXITY_API_KEY not set"

Execute a verificação de configuração:

bash ./scripts/check-setup.sh

Ele mostrará como definir a chave. Geralmente:

export PERPLEXITY_API_KEY="sua-chave-aqui"

Erro: "curl: command not found"

Instale curl:

macOS: brew install curl
Ubuntu/Debian: sudo apt-get install curl
Windows (WSL): sudo apt-get install curl

Erro: "jq: command not found"

Instale jq:

macOS: brew install jq
Ubuntu/Debian: sudo apt-get install jq
Windows (WSL): sudo apt-get install jq

Relatório parece truncado

Verifique o sumário no relatório em relação ao corpo real
Se as seções estiverem faltando, veja a Etapa 4 acima para o fluxo de recuperação
Para a próxima execução, considere reduzir o escopo ou usar múltiplas chamadas (Etapa 2.6)

Perguntar na sua IA favorita

Documentação