ref-researcher

Référence Researcher (ref-researcher)

Vue d'Ensemble

ref-researcher transforme l'inspiration brute (sites web en direct, galeries de design, enregistrements d'applications, captures d'écran UI ou HTML sauvegardé) en un .md Playbook de Design & Produit prêt à être exécuté, avant même de commencer le design ou le codage.

Utilisez ce skill pour les fonctionnalités d'applications mobiles, les flux d'applications web ou les sites web marketing chaque fois que vous avez besoin d'inspecter en profondeur le travail visuel, les indices de mouvement, les modèles de rédaction et les anti-modèles à partir de références externes, sans perdre la fidélité aux véritables tokens de marque, aux règles de plateforme et au périmètre de livraison de votre projet.

Dépendances

Coordonnez ces skills installés au lieu de dupliquer leurs responsabilités :

• uv — Vérifie et exécute proprement les scripts Python CLI via uv run (replier sur python3 uniquement en mode strictement hors ligne/stdlib sans uv installé).
• chrome-devtools — Rendre les SPA lourds en JS, inspecter le comportement de mise en page/d'animation en direct, et capturer des captures d'écran plein écran ou des sessions de navigateur interactives lorsque la récupération HTTP statique rencontre des shells côté client (needs_browser_capture: true) ou des sites payants.
• frontend-design — Guide le point de vue visuel, l'appariement typographique, la retenue spatiale et la critique anti-template lors de la synthèse d'applications web ou de sites web marketing.
• apple-hig-designer — Valide la fidélité des composants natifs iOS/iPadOS/watchOS, les zones de sécurité, les feuilles, la typographie dynamique et l'accessibilité lors de la synthèse de fonctionnalités d'applications mobiles ou de présentations d'appareils Apple natifs.

Démarrage Rapide

Commencez soit à partir d'URL en direct (récupération du HTML public/public/assets et capture de captures d'écran du navigateur) soit à partir d'un dossier de référence local existant :

# 1. Inspecter les références HTML sauvegardées en JSON structuré
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. Découper les captures d'écran ultra-hautes + extraire les images clés vidéo dans un dossier temporaire (largeur 1024px)
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 Utilitaires

Toute l'extraction programmatique, le découpage, la récupération polie HTTP et l'audit de liens résident dans scripts/ref_researcher.py. Chaque commande nécessite des limites explicites et --output <file.json> (écrivant un statut concis uniquement sur stdout).

1. fetch-page — Récupérateur Poli d'URL Publique & d'Assets

Télécharge le HTML statique et les feuilles de style/images principales à partir d'URL publiques tout en détectant les murs de connexion, les défis de bot et les shells JS côté client (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 — Extracteur de Code, Copie, Typographie & Tokens

Analyse les fichiers .html et .css sauvegardés jusqu'à --limit, produisant des titres, des liens de navigation, une hiérarchie H1–H3, des CTA, des échantillons de copie de corps, des couleurs hexadécimales, des déclarations font-family et des indices de bibliothèque d'animation (@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 — Découpeuse de Captures d'Écran Hautes & d'Images Clés Vidéo

Lit les dimensions réelles des pixels de l'image (gérant les extensions mal nommées comme JPEG sauvegardé en .webp), divise les captures d'écran plein écran hautes en tranches de fenêtre d'affichage nettes de 1024px de large, et extrait des images clés équidistantes de vidéos 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"

Hygiène de l'Espace de Travail : Pointez toujours --scratch-dir vers le répertoire scratch de votre conversation (ou /tmp/), jamais dans l'espace de travail du dépôt de l'utilisateur.

4. verify-links — Vérificateur de Liens d'Assets du Playbook

Valide chaque lien relatif markdown à l'intérieur des fichiers .md générés par rapport au disque et se termine avec le code 1 si un chemin est cassé.

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"

Workflow

1. Auditer le Produit Cible et les Contraintes en Premier

Avant d'ouvrir un seul lien d'inspiration, lisez les documents sources de vérité du projet cible (PRD, couleurs/tokens de marque, système de design, contraintes de plateforme). Enregistrez :

• Surface cible : Fonctionnalité d'Application Mobile, Flux d'Application Web ou Site Web Marketing.
• Tokens visuels et pièges de contraste : Valeurs hexadécimales exactes et minima WCAG AA (par exemple, accents de mode sombre à faible contraste).
• Matrice de Vérité Produit : Séparez Livré Aujourd'hui vs Feuille de Route / Revendications Interdites.

2. Rassembler les Références (Récupération en Direct, Capture Navigateur ou Dossier Existant)

• Références locales existantes : Exécutez extract-html et slice-media immédiatement sur le répertoire fourni.
• URL publiques / Recherche à partir de zéro :
  1. Exécutez fetch-page en premier pour une capture rapide et limitée du HTML statique + assets.
  2. Lorsque needs_browser_capture est true (coque CSR React/Next/Vite) ou que des captures d'écran visuelles plein écran sont nécessaires, utilisez le skill chrome-devtools (ou le workflow navigateur) pour rendre et capturer des images/DOM plein écran.
  3. Protocole pour Sites Authentifiés / Bloqués (STRICT) : Si un site retourne HTTP 401/403, redirige vers /login ou montre un paywall/mur de bot :
     • Demandez d'abord à l'utilisateur de se connecter, puis réessayez jusqu'à 2 fois.
     • Si l'accès échoue toujours après 2 tentatives, enregistrez clairement la source bloquée et pivotez automatiquement vers des sites/publications publiques accessibles ou des alternatives équivalentes pour que l'élan ne s'arrête jamais.

3. Inspecter Visuellement et Programmatiquement (Ne Jamais Parcourir de Grandes Captures à l'Aveugle)

• Les captures plein écran (3840w × 15000px+) se réduisent à des vignettes illisibles si on les visualise en entier. Inspectez toujours les tranches de fenêtre d'affichage séquentielles générées par slice-media sur toutes les références collectées ainsi que les tokens de copie/CSS extraits de extract-html.
• Associez l'étude visuelle avec des conseils de plateforme :
  • Invoquez les conseils apple-hig-designer pour la navigation iOS/iPadOS, les feuilles, les SF Symbols, et l'ergonomie tactile/typographie dynamique.
  • Invoquez les conseils frontend-design pour le contraste typographique web, les espaces blancs intentionnels et la coupe des modèles d'IA par défaut.

4. Synthétiser le Playbook .md

Écrivez le playbook livrable dans le dossier de référence du projet cible en suivant le fichier references/playbook_template.md. Adaptez le plan à la surface cible tout en incluant toujours :

1. Matrice de Vérité Produit & Contraintes (y compris les pièges de contraste sombre/clair)
2. Direction Créative & UX Exécutive
3. Plan d'Architecture / Flux d'Écrans
4. Inventaire des États & Cas Limites (vide, chargement/streaming, partiel/limite atteinte, erreur/permission)
5. Matrice de Traduction Plateforme & Responsive
6. Règles de Typographie, Surface, Mouvement & Copie
7. À FAIRE & À NE PAS FAIRE Stricts citant des exemples concrets positifs et négatifs de votre lot
8. Table de Recherche d'Assets de Référence Indexée (liens relatifs markdown)
9. Liste de Vérification Pré-Construction & QA

Mettez à jour le README.md du répertoire (s'il est présent) pour faire apparaître le nouveau playbook en haut.

5. Vérifier Tous les Liens Relatifs

Exécutez verify-links sur le playbook (et le README.md mis à jour). Corrigez toute sortie non nulle avant de signaler la fin à l'utilisateur.

Limitation de Débit

• fetch-page applique une limite de 1.0 requête/seconde (REQUESTS_PER_SECOND = 1.0) sur les processus d'agent concurrents via un verrou de fichier (/tmp/ref_researcher_fetch.lock) et des horodatages monotones (time.monotonic()).
• HTTP 429 déclenche un backoff exponentiel (Retry-After ou 2^tentative) enregistré sur stderr avant de lever RateLimitError.
• HTTP 5xx réessaie avec un backoff exponentiel ; les erreurs HTTP permanentes incluent l'URL et le corps de réponse tronqué pour un diagnostic rapide.

Erreurs Courantes

• Inspecter des captures d'écran de 15 000px de haut non découpées : Conduit à des conjectures floues et des micro-interactions manquées. Découpez toujours d'abord avec slice-media.
• Contourner indéfiniment les connexions bloquées ou stagner sur un paywall : Demandez à l'utilisateur de se connecter une fois, réessayez au maximum 2×, puis pivotez proprement vers des sources accessibles et enregistrez l'écart.
• Faire confiance aux affirmations marketing des concurrents plutôt qu'à votre propre codebase/PRD : Copier aveuglément la « Synchronisation Cloud » ou « Application Mac » d'un pair crée de fausses affirmations marketing. Filtrez toujours chaque motif via la Matrice de Vérité Produit.
• Laisser des liens relatifs cassés ou déverser des images scratch dans le dépôt du projet : Écrivez toujours les découpes dans scratch et exécutez verify-links avant de conclure.