ref-researcher

リファレンスリサーチャー (ref-researcher)

概要

ref-researcher は、生のインスピレーション（ライブWebサイト、デザインギャラリー、アプリの録画、UIスクリーンショット、または保存されたHTML）を、デザインやコーディングを始める前に、実践的な .md デザイン＆プロダクトプレイブック に変換します。

このスキルは、モバイルアプリの機能、Webアプリのフロー、またはマーケティングサイトを対象としており、外部リファレンスからビジュアルクラフト、モーションキュー、コピーパターン、アンチパターンを深く調査する必要がある場合に使用します。プロジェクトの実際のブランドトークン、プラットフォームルール、出荷範囲に対する忠実度を損なうことなく実行できます。

依存関係

以下のインストール済みスキルを調整して使用し、責任を重複させないでください。

• uv — Python CLIスクリプトを uv run でクリーンに確認・実行します（uv がインストールされておらず、厳密にオフライン/stdlibのみで実行する場合のみ python3 にフォールバック）。
• chrome-devtools — JSヘビーなSPAをレンダリングし、ライブのレイアウト/アニメーション動作を検査し、静的HTTPフェッチがクライアントサイドシェル（needs_browser_capture: true）やゲート付きサイトにヒットした場合に、フルページスクリーンショットまたはインタラクティブなブラウザセッションをキャプチャします。
• frontend-design — Webアプリやマーケティングサイトの合成時に、視覚的な視点、タイポグラフィのペアリング、空間の抑制、アンチテンプレート批評をガイドします。
• apple-hig-designer — モバイルアプリ機能やネイティブAppleデバイスのショーケースを合成する際に、ネイティブのiOS/iPadOS/watchOSコンポーネントの忠実度、セーフエリア、シート、Dynamic Type、アクセシビリティを検証します。

クイックスタート

ライブURLから（公開HTML/アセットを取得しブラウザスクリーンショットをキャプチャ）、または既存のローカルリファレンスフォルダから開始します。

# 1. 保存されたHTMLリファレンスを構造化JSONに抽出
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. 超高解像度スクリーンショットをスライス + ビデオキーフレームをスクラッチに抽出（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"

ユーティリティスクリプト

プログラムによる抽出、スライス、ポリトなHTTPフェッチ、リンク監査はすべて scripts/ref_researcher.py にあります。すべてのコマンドは明示的な制限と --output <file.json> が必要で、簡潔なステータスのみをstdoutに書き込みます。

1. fetch-page — ポリトな公開URL＆アセットフェッチャー

ログインウォール、ボットチャレンジ、クライアントサイドJSシェル（needs_browser_capture: true）を検出しながら、公開URLから静的HTMLとトップスタイルシート/画像をダウンロードします。

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 — コード、コピー、タイポグラフィ＆トークン抽出

保存された .html および .css ファイルを --limit まで解析し、タイトル、ナビリンク、H1–H3階層、CTA、本文コピーのサンプル、16進数カラー、font-family 宣言、アニメーションライブラリのキュー（@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 — 縦長スクリーンショット＆ビデオキーフレームスライサー

実際の画像ピクセル寸法を読み取り（JPEGが .webp として保存されているなど、誤った拡張子を処理）、縦長のフルページスクリーンショットをシャープな 1024px 幅のビューポートスライスに分割し、ffmpeg を使用してMP4/MOV/WebMから均等に間隔を空けたキーフレームを抽出します。

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"

ワークスペースの衛生: 常に --scratch-dir を会話のスクラッチディレクトリ（または /tmp/）に向けてください。ユーザーのリポジトリワークスペースには決して向けないでください。

4. verify-links — プレイブックアセットリンク監査

生成された .md ファイル内のすべての相対マークダウンリンクをディスクに対して検証し、パスが壊れている場合はコード 1 で終了します。

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"

ワークフロー

1. まずターゲットプロダクトと制約を監査

インスピレーションリンクを開く前に、ターゲットプロジェクトの信頼できる情報源（PRD、ブランドカラー/トークン、デザインシステム、プラットフォーム制約）を読みます。以下を記録します。

• ターゲットサーフェス: モバイルアプリ機能、Webアプリフロー、またはマーケティングサイト。
• ビジュアルトークンとコントラストトラップ: 正確な16進数値とWCAG AA最小値（例：低コントラストのダークモードアクセント）。
• プロダクトトゥルースマトリックス: 今日出荷するものとロードマップ/禁止された主張を分離します。

2. リファレンスを収集（ライブフェッチ、ブラウザキャプチャ、または既存フォルダ）

• 既存のローカルリファレンス: 提供されたディレクトリに対してすぐに extract-html と slice-media を実行します。
• 公開URL / スクラッチからの調査:
  1. 最初に fetch-page を実行して、高速でレート制限された静的HTML＋アセットキャプチャを行います。
  2. needs_browser_capture が true（React/Next/Vite CSRシェル）の場合、またはフルページのビジュアルスクリーンショットが必要な場合は、chrome-devtools スキル（またはブラウザワークフロー）を使用してレンダリングし、フルページ画像/DOMをキャプチャします。
  3. 認証/ブロックサイトプロトコル（厳守）: サイトがHTTP 401/403 を返す、/login にリダイレクトする、またはペイウォール/ボットウォールを表示する場合:
     • 最初にユーザーにログインを依頼し、その後最大2回再試行します。
     • 2回の再試行後もアクセスが失敗した場合は、ブロックされたソースを明確にログに記録し、自動的にアクセス可能な公開サイト/ページまたはピアの代替にピボットして、勢いを失わせないようにします。

3. 視覚的かつプログラム的に検査（決して縦長キャプチャを盲目的にスキミングしない）

• フルページキャプチャ（3840w × 15000px+）を全体で表示すると、判読できないサムネイルにダウンスケールされます。slice-media によって生成された連続するビューポートスライスを、収集したすべてのリファレンスと extract-html から抽出されたコピー/CSSトークンにわたって、常に検査します。
• 視覚調査をプラットフォームガイダンスと組み合わせます:
  • iOS/iPadOSのナビゲーション、シート、SFシンボル、タッチ/Dynamic Typeの人間工学については、apple-hig-designer のキューを呼び出します。
  • Webのタイポグラフィコントラスト、意図的なホワイトスペース、AIテンプレートのデフォルトを削減するためには、frontend-design のキューを呼び出します。

4. .md プレイブックを合成

references/playbook_template.md に従って、配信可能なプレイブックをターゲットプロジェクトのリファレンスフォルダ内に作成します。ブループリントをターゲットサーフェスに適合させ、常に以下を含めます。

1. プロダクトトゥルース＆制約マトリックス（ダーク/ライトコントラストトラップを含む）
2. エグゼクティブクリエイティブ＆UXディレクション
3. アーキテクチャ / 画面フローブループリント
4. 状態およびエッジケース目録（空、ローディング/ストリーミング、部分/キャップヒット、エラー/権限）
5. プラットフォーム＆レスポンシブ変換マトリックス
6. タイポグラフィ、サーフェス、モーション、コピールール
7. 厳格なDOS＆DON'TS バッチからの具体的なポジティブおよびネガティブな例を引用
8. インデックス付きリファレンスアセットルックアップテーブル（相対マークダウンリンク）
9. ビルド前実行＆QAチェックリスト

ディレクトリの README.md（存在する場合）を更新して、新しいプレイブックを上部に表示します。

5. すべての相対リンクを検証

プレイブック（および更新された README.md）に対して verify-links を実行します。完了をユーザーに報告する前に、ゼロ以外の終了コードを修正します。

レート制限

• fetch-page は、ファイルロック（/tmp/ref_researcher_fetch.lock）と単調増加タイムスタンプ（time.monotonic()）を介して、同時エージェントプロセス全体で 1.0 リクエスト/秒（REQUESTS_PER_SECOND = 1.0）を強制します。
• HTTP 429 は、RateLimitError を発生させる前に、指数バックオフ（Retry-After または 2^attempt）を stderr にログ記録します。
• HTTP 5xx は指数バックオフで再試行します。永続的なHTTPエラーには、迅速な診断のためにURLと切り詰められたレスポンス本文が含まれます。

よくある間違い

• スライスされていない 15,000px の高さのスクリーンショットを直接検査する: ぼやけた推測とマイクロインタラクションの見逃しを引き起こします。常に最初に slice-media でスライスしてください。
• ブロックされたログインを永久にバイパスしたり、1つのペイウォールで行き詰まったりする: ユーザーに1回サインインを依頼し、最大2回再試行してから、アクセス可能なソースにクリーンにピボットし、ギャップをログに記録します。
• 自分のコードベース/PRDよりも競合他社のマーケティングクレームを信頼する: ピアの「クラウド同期」や「Macアプリ」ヒーローを盲目的にコピーすると、誤ったマーケティングクレームが作成されます。常にすべてのパターンをプロダクトトゥルースマトリックスでゲートしてください。
• 壊れた相対リンクを残したり、スクラッチ画像をプロジェクトリポジトリ内にダンプしたりする: 常にスライスをスクラッチに書き込み、作業を終了する前に verify-links を実行してください。