ref-researcher

Investigador de Referencias (ref-researcher)

Descripción General

ref-researcher convierte inspiración en bruto (sitios web en vivo, galerías de diseño, grabaciones de aplicaciones, capturas de pantalla de IU o HTML guardado) en un Manual de Diseño y Producto opinado y listo para ejecución en formato .md antes de que comience el diseño o la codificación.

Usa este skill para características de aplicaciones móviles, flujos de aplicaciones web o sitios web de marketing cada vez que necesites inspeccionar profundamente la artesanía visual, las señales de movimiento, los patrones de copia y los antipatrones de referencias externas, sin perder fidelidad con los tokens reales de la marca de tu proyecto, las reglas de la plataforma y el alcance del envío.

Dependencias

Coordina estos skills instalados en lugar de duplicar sus responsabilidades:

• uv — Verifica e invoca scripts de Python CLI limpiamente mediante uv run (recurre a python3 solo si se ejecuta estrictamente sin conexión/sin uv instalado).
• chrome-devtools — Renderiza SPAs con mucho JavaScript, inspecciona el diseño en vivo/el comportamiento de animación y captura capturas de pantalla de página completa o sesiones de navegador interactivas cuando la obtención HTTP estática encuentra shells del lado del cliente (needs_browser_capture: true) o sitios con acceso restringido.
• frontend-design — Guía el punto de vista visual, la combinación tipográfica, la moderación espacial y la crítica contra plantillas al sintetizar aplicaciones web o sitios web de marketing.
• apple-hig-designer — Valida la fidelidad de los componentes nativos de iOS/iPadOS/watchOS, las zonas seguras, las hojas, el tipo dinámico y la accesibilidad al sintetizar características de aplicaciones móviles o demostraciones de dispositivos Apple nativos.

Inicio Rápido

Comienza ya sea desde URL en vivo (obteniendo HTML/activos públicos y capturando capturas de pantalla del navegador) o desde una carpeta de referencia local existente:

# 1. Inspeccionar referencias HTML guardadas en JSON estructurado
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. Dividir capturas de pantalla ultra altas + extraer fotogramas clave de video en un directorio temporal (1024px de ancho)
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 de Utilidad

Toda la extracción programática, división, obtención HTTP educada y auditoría de enlaces residen en scripts/ref_researcher.py. Cada comando requiere límites explícitos y --output <archivo.json> (escribe solo estado conciso en stdout).

1. fetch-page — Obtenedor Educado de URL y Activos Públicos

Descarga HTML estático y las principales hojas de estilo/imágenes de URL públicas mientras detecta muros de inicio de sesión, desafíos de bots y shells JS del lado del 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 — Extractor de Código, Copia, Tipografía y Tokens

Analiza archivos .html y .css guardados hasta --limit, generando títulos, enlaces de navegación, jerarquía H1–H3, CTA, muestras de cuerpo de texto, colores hexadecimales, declaraciones font-family y señales de bibliotecas de animación (@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 — Divisor de Capturas de Pantalla Largas y Fotogramas Clave de Video

Lee las dimensiones reales de píxeles de la imagen (manejando extensiones mal nombradas como JPEG guardado como .webp), divide capturas de pantalla largas de página completa en segmentos nítidos de viewport de 1024px de ancho y extrae fotogramas clave de MP4/MOV/WebM espaciados uniformemente a través de ffmpeg.

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

Higiene del Espacio de Trabajo: Siempre apunta --scratch-dir a tu directorio temporal de conversación (o /tmp/), nunca dentro del espacio de trabajo del repositorio del usuario.

4. verify-links — Auditor de Enlaces de Activos del Manual

Valida cada enlace relativo de markdown dentro de los archivos .md generados contra el disco y sale con código 1 si alguna ruta está rota.

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"

Flujo de Trabajo

1. Auditar Primero el Producto Objetivo y las Restricciones

Antes de abrir un solo enlace de inspiración, lee los documentos fuente de verdad del proyecto objetivo (PRD, colores/tokens de marca, sistema de diseño, restricciones de plataforma). Registra:

• Superficie objetivo: Característica de Aplicación Móvil, Flujo de Aplicación Web o Sitio Web de Marketing.
• Tokens visuales y trampas de contraste: Valores hexadecimales exactos y mínimos WCAG AA (por ejemplo, acentos de modo oscuro con bajo contraste).
• Matriz de Verdad del Producto: Separa Envío Hoy de Hoja de Ruta / Afirmaciones Prohibidas.

2. Recopilar Referencias (Obtención en Vivo, Captura del Navegador o Carpeta Existente)

• Referencias locales existentes: Ejecuta extract-html y slice-media inmediatamente en el directorio proporcionado.
• URL públicas / Investigación desde cero:
  1. Ejecuta fetch-page primero para una captura rápida de HTML estático + activos con límite de velocidad.
  2. Cuando needs_browser_capture sea true (shell CSR de React/Next/Vite) o se necesiten capturas de pantalla visuales de página completa, usa el skill chrome-devtools (o flujo de trabajo del navegador) para renderizar y capturar imágenes/DOM de página completa.
  3. Protocolo de Sitio Autenticado/Bloqueado (ESTRICTO): Si un sitio devuelve HTTP 401/403, redirige a /login o muestra un muro de pago/de bot:
     • Pide al usuario que inicie sesión primero, luego reintenta hasta 2 veces.
     • Si el acceso aún falla después de 2 reintentos, registra claramente la fuente bloqueada y pasa automáticamente a sitios/páginas públicos accesibles o alternativas equivalentes para que el impulso nunca se detenga.

3. Inspeccionar Visual y Programáticamente (Nunca Examinar Capturas Largas a Ciegas)

• Las capturas de página completa (3840w × 15000px+) se reducen a miniaturas ilegibles si se ven completas. Siempre inspecciona los segmentos secuenciales del viewport generados por slice-media en todas las referencias recopiladas, además de los tokens de copia/CSS extraídos de extract-html.
• Combina el estudio visual con la guía de la plataforma:
  • Invoca las señales de apple-hig-designer para navegación de iOS/iPadOS, hojas, Símbolos SF y ergonomía táctil/tipo dinámico.
  • Invoca las señales de frontend-design para el contraste tipográfico web, el espacio en blanco intencional y la eliminación de plantillas predeterminadas de IA.

4. Sintetizar el Manual .md

Escribe el manual entregable dentro de la carpeta de referencias del proyecto objetivo siguiendo references/playbook_template.md. Adapta el plano a la superficie objetivo, incluyendo siempre:

1. Matriz de Verdad y Restricciones del Producto (incluyendo trampas de contraste claro/oscuro)
2. Dirección Creativa y de UX Ejecutiva
3. Plano de Arquitectura / Flujo de Pantallas
4. Inventario de Estados y Casos Límite (vacío, carga/transmisión, parcial/límite alcanzado, error/permiso)
5. Matriz de Traducción de Plataforma y Adaptabilidad
6. Reglas de Tipografía, Superficie, Movimiento y Copia
7. LO QUE SE DEBE Y NO SE DEBE HACER ESTRICTO citando ejemplos positivos y negativos concretos de tu lote
8. Tabla de Referencia de Activos Indexados (enlaces relativos de markdown)
9. Lista de Verificación de Ejecución y QA Previo a la Construcción

Actualiza el README.md del directorio (si está presente) para mostrar el nuevo manual en la parte superior.

5. Verificar Todos los Enlaces Relativos

Ejecuta verify-links en el manual (y en el README.md actualizado). Corrige cualquier salida no cero antes de informar la finalización al usuario.

Límite de Velocidad

• fetch-page aplica 1.0 solicitud/segundo (REQUESTS_PER_SECOND = 1.0) en todos los procesos de agente concurrentes a través de un bloqueo de archivo (/tmp/ref_researcher_fetch.lock) y marcas de tiempo monotónicas (time.monotonic()).
• HTTP 429 activa una retroalimentación exponencial (Retry-After o 2^intentos) registrada en stderr antes de lanzar RateLimitError.
• HTTP 5xx reintenta con retroalimentación exponencial; los errores HTTP permanentes incluyen la URL y el cuerpo de respuesta truncado para un diagnóstico rápido.

Errores Comunes

• Inspeccionar capturas de pantalla de 15,000px de alto sin dividir directamente: Causa conjeturas borrosas y microinteracciones perdidas. Siempre divide primero con slice-media.
• Evitar inicios de sesión bloqueados para siempre o estancarse en un muro de pago: Pide al usuario que inicie sesión una vez, reintenta como máximo 2 veces, luego pasa limpiamente a fuentes accesibles y registra la brecha.
• Confiar en las afirmaciones de marketing de la competencia sobre tu propio código/PRD: Copiar ciegamente el "Cloud Sync" o "Mac App" de un par crea afirmaciones de marketing falsas. Siempre filtra cada patrón a través de la Matriz de Verdad del Producto.
• Dejar enlaces relativos rotos o volcar imágenes temporales dentro del repositorio del proyecto: Siempre escribe los segmentos en un directorio temporal y ejecuta verify-links antes de finalizar.