ChaoticSurfer/seo-suite

Analytics: medir, diagnosticar, relatar

Transforme dados primários (Search Console, Bing Webmaster, GA4, logs de servidor) em decisões. Diagnostique quedas com uma árvore de decisão fixa em vez de palpites, e meça mudanças de forma honesta.

Quando usar / não usar

Use para:

• Exportações do Search Console, Bing Webmaster e GA4.
• Quedas de tráfego e perguntas sobre atualizações de algoritmo.
• Metas de otimização de CTR.
• Canibalização.
• Análise de logs de rastreamento.
• Painéis de KPI.
• Testes antes/depois.

Não use para:

• Encontrar defeitos no site → seo-technical, seo-audit. Esta habilidade chama eles quando a árvore de quedas aponta para lá.
• Ideias de palavras-chave para novas páginas → seo-keywords.
• Visibilidade de concorrentes → seo-competitors.

Entradas a reunir

• Exportação(ões) de desempenho do Search Console.
  • Exportação da interface: Queries.csv / Pages.csv (apenas 1.000 primeiras linhas).
  • Exportação da API ou Looker Studio com linhas de consulta+página: necessária para canibalização. Limite da API: 25k linhas/solicitação, ~50k linhas/dia/tipo (google-rules §11).
  • Para comparações: duas janelas de igual duração, alinhadas por dia da semana, com os últimos 2–3 dias excluídos (os dados do GSC atrasam).
• Regex da marca. Nome da marca mais erros de digitação, ex. acme|acme ?corp|აკმე.
• Opcionais:
  • Exportação do Bing Webmaster (mesmo formato; funciona com gsc_analyze).
  • Relatório de páginas de entrada orgânicas do GA4.
  • Logs de acesso do servidor (.log / .gz).
  • As datas de mudanças, implantações e migrações do site.
• Para quedas: quando começou, qual seção/país/dispositivo, e se as conversões também caíram.

Fluxo de trabalho

A. Análise de oportunidades (exportação GSC/Bing)

1. Execute a análise:

   mkdir -p seo-work
   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/gsc_analyze.py" Queries.csv --brand "marca|mrca" --min-impressions 50 > seo-work/gsc.json
   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/gsc_analyze.py" query_page.csv --brand "marca" > seo-work/gsc-qp.json   # canibalização
   

   Flags: --striking-from 4 --striking-to 20 (padrões); aumente --min-impressions em sites grandes.

2. Leia striking_distance (posições 4–20, ordenadas por est_extra_clicks_at_pos3 [estimativa]). Estas são as páginas a melhorar primeiro. Encaminhe cada uma para seo-onpage / seo-content com sua consulta.

3. Leia ctr_underperformers. As 10 principais consultas cujo CTR está abaixo da metade da mediana de CTR do próprio site para aquela posição (ctr_curve_used; usa padrões quando há poucos dados).

   • Causas: título/snippet fraco, um recurso SERP ou AI Overview acima do resultado, ou incompatibilidade de intenção.
   • Inspecione a SERP ao vivo com WebSearch antes de reescrever.

4. question_queries: material para seções de FAQ e passagens com resposta em primeiro lugar (seo-content, seo-ai-search).

5. brand_split: relate cliques não-marca separadamente. A demanda da marca não é desempenho de SEO.

6. cannibalization: uma consulta onde 2+ páginas têm cada uma ≥10% das impressões. Decida por caso: mesclar + 301, diferenciar a intenção, ou apontar links internos para a página principal. Nem toda divisão é um problema: se ambas as páginas classificam bem, deixe-as.

B. Comparação de períodos e diagnóstico de quedas de tráfego

1. Execute a comparação:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/gsc_analyze.py" ultimos_28d.csv --compare anteriores_28d.csv > seo-work/gsc-compare.json
   

   Cada perdedor recebe um likely_cause:

   • "rankings dropped"
   • "fewer impressions at similar rank" (demanda, ou um recurso SERP)
   • "CTR fell at similar rank"

   Estas são heurísticas: apresente-as como "consistente com".

2. Percorra a árvore de quedas em ordem e pare no primeiro ramo que as evidências suportarem. Registre a evidência para cada ramo:

   1. A queda é real?

      • Cliques GSC vs sessões orgânicas GA4, comparando a direção da tendência (espere uma diferença de nível de 10–20%).
      • Uma queda apenas no GA4 → problema de rastreamento/consentimento/tag, não de SEO.
      • Verifique ano a ano para descartar sazonalidade.

   2. Técnico. Execute em paralelo:

      • robots_check.py
      • sitemap_check.py
      • page_audit.py nas principais URLs perdedoras
      • crawl.py na seção afetada

      Procure por:

      • noindex, mudanças de canonical, 5xx/429, bloqueios de robots, mudanças de redirecionamento, um desafio de bot (bot-challenge).
      • Implantações na data da queda.
      • Relatório de indexação de páginas do Search Console para picos em "Excluído" (seo-technical).

   3. Atualização de algoritmo. Compare a data da queda com o Painel de Status de Pesquisa do Google (https://status.search.google.com/ → incidentes de classificação; busque-o). A forma importa:

      • Uma mudança abrupta em todo o site em uma data de atualização coincide com uma reavaliação de sistemas (conteúdo útil / núcleo / spam). Veja google-rules §4.
      • Mudanças específicas de seção apontam para problemas em nível de página.
      • Nunca diga "penalizado" a menos que o Search Console mostre uma ação manual.

   4. Sazonalidade / demanda. YoY no GSC (16 meses de dados; google-rules §11), além do Google Trends para os termos principais. Impressões caindo com posição estável = demanda.

   5. Deslocamento SERP. Posição estável, mas CTR caindo. WebSearch as consultas:

      • AI Overview presente? Novos recursos (vídeo, PAA, compras, fóruns)? Anúncios?
      • O relatório "Desempenho de IA generativa de pesquisa" do Search Console está disponível? (google-rules §10)

   6. Concorrentes. Posição perdida para URLs específicos → seo-competitors (compare_pages nos vencedores). Verifique o Wayback CDX para quando a página deles mudou.

3. Use dados de log quando disponíveis:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/log_analyze.py" access.log access.log.1.gz --verify-dns --sitemap-urls seo-work/urls.txt > seo-work/logs.json
   

   Procure por:

   • Acessos do Googlebot por dia caindo (problema de capacidade de rastreamento: 5xx/429 ou servidor lento; google-rules §1).
   • Erros servidos para bots.
   • Parcela de URLs com parâmetros (desperdício de rastreamento).
   • Caminhos de sitemap nunca rastreados.
   • IPs falsos de "Googlebot" (unverified_ips).
   • Se bots de IA (OAI-SearchBot, Claude-SearchBot, PerplexityBot) alcançam o site.

C. Relatórios e painéis

• KPIs. Separe líderes de retardatários:
  • Líderes: páginas indexadas (GSC), impressões, posição média para clusters-alvo, taxa de aprovação CWV, erros de rastreamento.
  • Retardatários: cliques não-marca, conversões/receita orgânica (GA4), taxa de citação de IA (seo-ai-search).
• Painel gratuito: Looker Studio com o conector nativo do Search Console (tabelas Site + URL impression) e o conector GA4. Páginas:
  • Visão geral.
  • Tendência não-marca (filtro regex).
  • Clusters (agrupamento por caminho de URL).
  • Oportunidades (posições 4–20).
  • CWV (conector CrUX ou snapshots psi.py).
• Relatório mensal: o que mudou, porquê (com evidências etiquetadas), o que fizemos (do SEO-WORKLOG.md), o que vem a seguir.

D. Medir se uma mudança de SEO funcionou

1. Pré-registro. Antes da mudança, anote no worklog:
   • URLs alterados.
   • URLs de controle (semelhantes, inalterados).
   • Métrica (cliques/impressões/CTR/posição para as consultas-alvo).
   • Direção esperada.
   • Janela: ≥4 semanas após a indexação; verifique a data de re-rastreamento na Inspeção de URL.
2. Exporte janelas iguais antes e depois para ambos os grupos, então execute gsc_analyze.py depois.csv --compare antes.csv para cada grupo.
3. Relate a mudança do tratamento menos a mudança do controle. Com poucas páginas ou baixos cliques, diga "inconclusivo". Nunca afirme causalidade a partir de um único antes/depois.

Rank tracking (monitoramento de posições)

• Gratuito: posição média por consulta no Search Console (ponderada por impressão, todas as localizações). Bom para tendências; não é uma visão "onde estou agora".

• Pago: posições diárias para uma lista fixa de palavras-chave, por localização/dispositivo, com recursos SERP. Justifique quando:

  • classificações locais ou em várias cidades importam,
  • o contrato do cliente precisa de relatórios de rank, ou
  • você precisa monitorar palavras-chave sem impressões ainda.

  Opções: Semrush Position Tracking, Ahrefs Rank Tracker, SE Ranking, ou a API SERP DataForSEO para verificações com script (tools.md).

Verificações

Verificação	Regra	Fonte
Janelas de comparação de igual duração, alinhadas por dia da semana, últimos 2–3 dias excluídos	Dados GSC atrasam 2–3 dias	google-rules §11 [Documento Google]
Retenção do GSC	16 meses	google-rules §11 [Documento Google]
Alegações de "penalidade"	apenas com uma entrada no relatório de Ações Manuais	google-rules §4 [Documento Google]
Tráfego de AI Overviews/AI Mode	contabilizado dentro de Desempenho → Web; sem cliques separados	google-rules §10 [Documento Google]
Queda na taxa de rastreamento do Googlebot	coincide com respostas 5xx/429/lentas	google-rules §1 [Documento Google]
Expectativas de CTR	curva do próprio site primeiro; padrões são heurísticos	heurístico
Limiar de canibalização	≥2 páginas ≥10% impressões, ≥100 impressões	heurístico

Dados: gratuito vs pago

Gratuito cobre quase tudo aqui. Search Console (+API), Bing Webmaster (+ seu relatório de Desempenho de IA, se disponível; google-rules §10), GA4, Looker Studio, logs de servidor, Painel de Status da Pesquisa Google, Google Trends.

Pago adiciona (veja ${CLAUDE_PLUGIN_ROOT}/references/tools.md):

• Semrush / Ahrefs.
  • Histórico de visibilidade de concorrentes e movimento de palavras-chave (seus próprios dados são melhores no GSC).
  • Sensores de volatilidade de algoritmo (Semrush Sensor) para ver se uma queda é geral do setor.
  • Justificado para a pergunta "é só conosco?" durante uma atualização.
  • Tática de custo: verifique a página gratuita do Sensor e o histórico de Pesquisa Orgânica de um único concorrente, em vez de um projeto completo.
• Rank trackers: veja acima. Monitore apenas palavras-chave de dinheiro e limite localizações/dispositivos aos que importam. A maioria das ferramentas cobra por palavra-chave × localização × dispositivo × frequência, então prefira semanal a diário para conjuntos não voláteis.
• Screaming Frog Log File Analyser (## Screaming Frog). Útil se os logs são enormes e o usuário prefere uma GUI. log_analyze.py cobre as perguntas principais gratuitamente.

Rotule números de tráfego de terceiros como [dados do fornecedor] / [estimativa]. Eles são modelados, não medidos.

Saída

1. seo-work/gsc.json e similares, além de um resumo curto de descobertas:
   • Top 10 oportunidades a uma posição de distância: consulta, página, cliques extras estimados [estimativa].
   • Principais correções de CTR.
   • Decisões de canibalização.
2. Diagnóstico de queda: a árvore com ✅/❌ e evidências por ramo, a explicação mais provável em linguagem "consistente com", e próximas ações encaminhadas para a habilidade correta.
3. Uma especificação de KPI/painel (fontes de dados Looker Studio, campos, filtros) ou um rascunho de relatório mensal.
4. Registro de experimento (pré-registro + resultado).

Armadilhas e mitos

• Posição média é ponderada por impressão em todas as consultas/localizações. Uma nova classificação na página 2 pode baixar a média enquanto o tráfego aumenta.
• Exportações da interface limitam a 1.000 linhas e escondem consultas anonimizadas, então os totais não corresponderão ao gráfico.
• Uma queda em uma data de atualização não é prova de que a atualização a causou. Descarte causas técnicas e de rastreamento primeiro.
• YoY supera MoM para negócios sazonais.
• Cliques caindo enquanto as impressões se mantêm é frequentemente AI Overviews ou outro recurso SERP, não uma perda de classificação.
• "Orgânico" no GA4 depende do modo de consentimento e agrupamento de canal, então verifique alterações de configuração na data da queda.
• Não otimize CTR com títulos clickbait. O Google pode reescrevê-los (google-rules §3).

Registre o trabalho

Anexe a SEO-WORKLOG.md (${CLAUDE_PLUGIN_ROOT}/references/worklog.md):

• Exportações usadas (intervalos de datas).
• Scripts executados.
• Descobertas com tags de evidência.
• Veredito do diagnóstico.
• Experimentos pré-registrados.
• Uso de ferramentas pagas.
• A data para re-verificar (ex.: "re-pull GSC em 2026-11-21 para o teste de título").