ref-researcher

Researcher de Referências (ref-researcher)

Visão Geral

ref-researcher transforma inspiração bruta (sites ao vivo, galerias de design, gravações de aplicativos, capturas de tela de UI ou HTML salvo) em um Manual de Design e Produto (.md) opinativo e pronto para execução, antes mesmo do design ou da codificação começar.

Use esta skill para funcionalidades de aplicativos móveis, fluxos de web apps ou sites de marketing sempre que precisar inspecionar profundamente o acabamento visual, pistas de movimento, padrões de texto e antipadrões de referências externas — sem perder a fidelidade aos tokens reais da marca do seu projeto, regras de plataforma e escopo de entrega.

Dependências

Coordenar estas skills instaladas em vez de duplicar suas responsabilidades:

• uv — Verificar e invocar scripts Python CLI de forma limpa via uv run (recorrer a python3 apenas se estiver executando estritamente offline/stdlib sem uv instalado).
• chrome-devtools — Renderizar SPAs com muito JavaScript, inspecionar comportamento de layout/animação ao vivo e capturar capturas de tela de página inteira ou sessões interativas do navegador quando a busca HTTP estática encontrar shells do lado do cliente (needs_browser_capture: true) ou sites com acesso restrito.
• frontend-design — Orientar o ponto de vista visual, combinação de tipografia, restrição espacial e crítica anti-template ao sintetizar web apps ou sites de marketing.
• apple-hig-designer — Validar a fidelidade dos componentes nativos iOS/iPadOS/watchOS, áreas seguras, sheets, Dynamic Type e acessibilidade ao sintetizar funcionalidades de aplicativos móveis ou showcases de dispositivos Apple nativos.

Início Rápido

Comece a partir de URLs ao vivo (buscando HTML público/ativos e capturando capturas de tela do navegador) ou de uma pasta de referência local existente:

# 1. Inspecionar referências HTML salvas em JSON estruturado
uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py extract-html \
  --input-dir "./Docs/References & Inspo" \
  --limit 25 \
  --output "/tmp/ref_html_summary.json"

# 2. Fatiar capturas de tela ultra-altas + extrair keyframes de vídeo para área temporária (1024px de largura)
uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py slice-media \
  --input-dir "./Docs/References & Inspo" \
  --scratch-dir "/tmp/ref_slices" \
  --slice-height 1400 \
  --out-width 1024 \
  --max-slices 12 \
  --frames-per-video 3 \
  --output "/tmp/ref_media_manifest.json"

Scripts Utilitários

Toda extração programática, fatiação, busca HTTP educada e auditoria de links residem em scripts/ref_researcher.py. Cada comando requer limites explícitos e --output <file.json> (escrevendo apenas status conciso no stdout).

1. fetch-page — Buscador Educado de URL Pública e Ativos

Faz download de HTML estático e principais folhas de estilo/imagens de URLs públicas, detectando paredes de login, desafios de bot e shells JS do lado do cliente (needs_browser_capture: true).

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py fetch-page \
  --url "https://example.com" \
  --asset-dir "./refs/example" \
  --max-assets 20 \
  --output "/tmp/fetch_example.json"

2. extract-html — Extrator de Código, Texto, Tipografia e Tokens

Analisa arquivos .html e .css salvos até --limit, gerando títulos, links de navegação, hierarquia H1–H3, CTAs, amostras de corpo de texto, cores hex, declarações font-family e pistas de bibliotecas de animação (@keyframes, framer, gsap, lottie).

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py extract-html \
  --input-dir "./refs" \
  --limit 25 \
  --output "/tmp/html_summary.json"

3. slice-media — Fatiador de Capturas de Tela Grandes e Keyframes de Vídeo

Lê as dimensões reais de pixel da imagem (lidando com extensões mal nomeadas, como JPEG salvo como .webp), divide capturas de tela de página inteira grandes em fatias nítidas de viewport com 1024px de largura e extrai keyframes uniformemente espaçados de MP4/MOV/WebM via ffmpeg.

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py slice-media \
  --input-dir "./refs" \
  --scratch-dir "<scratch_dir>/slices" \
  --slice-height 1400 \
  --out-width 1024 \
  --max-slices 12 \
  --frames-per-video 3 \
  --output "/tmp/slice_manifest.json"

Higiene do Espaço de Trabalho: Sempre aponte --scratch-dir para o diretório temporário da sua conversa (ou /tmp/), nunca para o espaço de trabalho do repositório do usuário.

4. verify-links — Auditor de Links de Ativos do Manual

Valida cada link markdown relativo dentro de arquivos .md gerados em relação ao disco e sai com código 1 se algum caminho estiver quebrado.

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py verify-links \
  --markdown "./Docs/References & Inspo/PLAYBOOK.md" \
  --markdown "./Docs/References & Inspo/README.md" \
  --output "/tmp/verify_links.json"

Fluxo de Trabalho

1. Auditar o Produto Alvo e Restrições Primeiro

Antes de abrir um único link de inspiração, leia os documentos fonte da verdade do projeto alvo (PRD, cores/tokens da marca, sistema de design, restrições de plataforma). Registre:

• Superfície alvo: Funcionalidade de Aplicativo Móvel, Fluxo de Web App ou Site de Marketing.
• Tokens visuais e armadilhas de contraste: Valores hex exatos e mínimos WCAG AA (por exemplo, acentos de modo escuro com baixo contraste).
• Matriz de Verdade do Produto: Separe Entregando Hoje vs Roadmap / Alegações Proibidas.

2. Reunir Referências (Busca ao Vivo, Captura de Navegador ou Pasta Existente)

• Referências locais existentes: Execute extract-html e slice-media imediatamente no diretório fornecido.
• URLs públicas / Pesquisa do zero:
  1. Execute fetch-page primeiro para captura rápida e com limite de taxa de HTML estático + ativos.
  2. Quando needs_browser_capture for true (shell CSR React/Next/Vite) ou forem necessárias capturas de tela visuais de página inteira, use a skill chrome-devtools (ou fluxo de trabalho do navegador) para renderizar e capturar imagens de página inteira/DOM.
  3. Protocolo de Site Autenticado/Bloqueado (RIGOROSO): Se um site retornar HTTP 401/403, redirecionar para /login ou mostrar um paywall/parede de bot:
     • Peça ao usuário para fazer login primeiro, depois tente novamente até 2 vezes.
     • Se o acesso ainda falhar após 2 tentativas, registre claramente a fonte bloqueada e mude automaticamente para sites/páginas públicos acessíveis ou alternativas semelhantes para que o ritmo nunca pare.

3. Inspecionar Visualmente e Programaticamente (Nunca Examina Capturas Grandes às Cegas)

• Capturas de página inteira (3840w × 15000px+) são reduzidas a miniaturas ilegíveis se visualizadas inteiras. Sempre inspecione as fatias sequenciais de viewport geradas por slice-media em todas as referências coletadas, além dos tokens de texto/CSS extraídos de extract-html.
• Combine o estudo visual com orientação da plataforma:
  • Invoque dicas de apple-hig-designer para navegação iOS/iPadOS, sheets, SF Symbols e ergonomia de toque/Dynamic Type.
  • Invoque dicas de frontend-design para contraste de tipografia web, espaços em branco intencionais e corte de padrões padrão de IA.

4. Sintetizar o Manual .md

Escreva o manual entregável dentro da pasta de referência do projeto alvo seguindo references/playbook_template.md. Adapte o modelo à superfície alvo, incluindo sempre:

1. Matriz de Verdade e Restrições do Produto (incluindo armadilhas de contraste claro/escuro)
2. Direção Criativa e de UX Executiva
3. Arquitetura / Projeto de Fluxo de Telas
4. Inventário de Estados e Casos Extremos (vazio, carregando/streaming, parcial/limite de capacidade, erro/permissão)
5. Matriz de Tradução de Plataforma e Responsividade
6. Regras de Tipografia, Superfície, Movimento e Texto
7. PRÓS & CONTRAS Rigorosos citando exemplos positivos e negativos concretos do seu lote
8. Tabela de Consulta de Ativos de Referência Indexados (links markdown relativos)
9. Checklist de Execução e QA Pré-Construção

Atualize o README.md do diretório (se presente) para destacar o novo manual no topo.

5. Verificar Todos os Links Relativos

Execute verify-links no manual (e no README.md atualizado). Corrija qualquer saída não zero antes de relatar a conclusão ao usuário.

Limitação de Taxa

• fetch-page impõe 1.0 requisição/segundo (REQUESTS_PER_SECOND = 1.0) em processos de agente concorrentes por meio de um bloqueio de arquivo (/tmp/ref_researcher_fetch.lock) e timestamps monotônicos (time.monotonic()).
• HTTP 429 aciona recuo exponencial (Retry-After ou 2^tentativas) registrado no stderr antes de levantar RateLimitError.
• HTTP 5xx tenta novamente com recuo exponencial; erros HTTP permanentes incluem a URL e o corpo da resposta truncado para diagnóstico rápido.

Erros Comuns

• Inspecionar capturas de tela não fatiadas com 15.000px de altura diretamente: Causa suposições borradas e micro-interações perdidas. Sempre fatie primeiro com slice-media.
• Ignorar logins bloqueados para sempre ou parar em um paywall: Peça ao usuário para fazer login uma vez, tente novamente no máximo 2×, depois mude limpiamente para fontes acessíveis e registre a lacuna.
• Confiar em alegações de marketing de concorrentes em vez do seu próprio código/PRD: Copiar o "Cloud Sync" ou "Mac App" herói de um par cegamente cria alegações de marketing falsas. Sempre filtre cada padrão através da Matriz de Verdade do Produto.
• Deixar links relativos quebrados ou despejar imagens temporárias dentro do repositório do projeto: Sempre escreva fatias na área temporária e execute verify-links antes de finalizar.