visual-debug

ビジュアルデバッグ

キャプチャ済みの参照証拠と照らし合わせ、既存の実装を構造、AE、DSSIM、実行時、トランジションの各チェックで診断します。

境界と返却契約

• 参照証拠と実装証拠がすでにある場合に、このスキルを使用します。ベースライン証拠が不足している場合は ui-capture に回し、実装、再生成、クローン全体のオーケストレーションは ui-reverse-engineering または現在の呼び出し元に回します。
• 失敗したアーティファクト、セレクターまたは領域、考えられる根本原因、推奨する修正、正確な検証コマンドを返します。呼び出し元が修正を明示的に委任した場合を除き、ソース編集は呼び出し元が担当します。
• brief/WORKER_BRIEF.md または evidence-pack.json が存在する場合は、まずそれを読み、失敗したホットスポットの診断に必要なサマリーと指定された詳細アーティファクトだけを読みます。
• 修正を委任された場合は、修正ループに入る前に ../ui-reverse-engineering/iteration-discipline.md を読みます。試行履歴と停止条件は、委任やコンテキストの圧縮後も引き継がれます。共有ツールの修正がすでに許可されている場合を除き、チェッカーの不具合は再現手順とともに報告してください。インストール済みのキャッシュは編集しないでください。
• テキスト、要素の高さ、発火したイベント、ビルドの成功が一致していても、見た目や軌跡の同等性が証明されたことにはなりません。背景と前景、メディアのフィット、途中のモーション状態を比較してください。

必須の不変条件

通常の比較では、参照画像や実装画像を読み込まないでください。 まずサマリーと AE／SSIM ツールを使用します。位置に失敗がある場合は auto-diagnose.sh を実行し、自動診断で原因が見つからなかった場合に限り、差分画像を読み込みます。Phase E は必須の例外であり、委任されたコンテキスト内で実行する必要があります。

反復作業中は参照を固定します。動的なサイトでは、比較対象が時間とともに変化するため、最初の参照キャプチャが完了した後は、証拠が実際に古くなるまで、凍結した参照クロップ（RECATCH_REF=0）を使用してください。実装を編集した後は、修正を評価する前に、必ず新しい実装証拠を生成してください。

証拠に window.scrollTo、scrollYProgress、setTimeout、速度、スクロール停止ロジックを囲む guard ref、または ScrollTrigger の pin／scrub が含まれる場合は、スクロール状態機械の initial → active/expanded → settled/returned の証明を必須とします。単一の終点フレームでは不十分です。

失敗を解消するためにしきい値を緩めたり、説明されていない領域をマスクしたりしないでください。編集する前に、各失敗を実装、参照／キャプチャ、チェッカー、不明のいずれかに分類します。

成功、失敗、中断のいずれの場合も、開いたブラウザーセッションはすべて終了してください。

agent-browser --session <session-name> close

close --all は絶対に使用しないでください。他のエージェントがセッションを所有している可能性があります。

セッションごとに一度だけ開始

必要なツールを確認します。不足しているものがあれば停止し、ブートストラップコマンドを提示してください。リモートインストーラーを自動で実行してはいけません。

miss=""
for c in agent-browser ffmpeg dssim; do command -v "$c" >/dev/null 2>&1 || miss+=" $c"; done
{ command -v magick >/dev/null 2>&1 || command -v convert >/dev/null 2>&1; } || miss+=" imagemagick"
if [ -n "$miss" ]; then
  printf 'Missing system deps:%s\nBootstrap:\n  tmp=$(mktemp) && curl -LsSf -o "$tmp" https://raw.githubusercontent.com/voidmatcha/ui-clone-skills/main/install.sh && bash "$tmp" && rm -f "$tmp"\n' "$miss"
  exit 1
fi

アクティブなプラグインまたはチェックアウトからスクリプトの場所を解決します。

SCRIPTS_DIR="${VISUAL_DEBUG_SCRIPTS_DIR:-}"
if [ -z "$SCRIPTS_DIR" ]; then
  for root in "${PLUGIN_ROOT:-}" "${CODEX_PLUGIN_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "${UI_CLONE_ROOT:-}" "$PWD" "$PWD/.." "$PWD/../.." "${INSTALL_DIR:-$HOME/.local/share/ui-clone-skills}"; do
    [ -n "$root" ] && [ -f "$root/skills/visual-debug/scripts/ae-compare.sh" ] && SCRIPTS_DIR=$(cd "$root/skills/visual-debug/scripts" && pwd) && break
  done
fi
[ -n "$SCRIPTS_DIR" ] || { echo "Set VISUAL_DEBUG_SCRIPTS_DIR or PLUGIN_ROOT" >&2; exit 1; }

スクリプトは bash "$SCRIPTS_DIR/<script>.sh" ... として実行します。Skill イベントのないホスト（Codex）では、最初のこの呼び出しによって、プラグインフックにこのセッションが診断を担当することが通知されます。

大きなブラウザー JSON はファイルにパイプし、モデルのコンテキストには出力しないでください。すべての agent-browser コマンドに --session <name> を指定し、JS の eval はすべて IIFE にしてください。

ルートを選択する

1. 最初に、既存の最小限のサマリーを読みます：sections/result.txt、pipeline-state.json、_summary.json、pixel-perfect-diff.json、または失敗したゲートのアーティファクト。
2. ピクセルを確認する前に、低コストの構造チェックを実行します：実装のクロームスキャン、stray-absolute-check.sh、関連する遷移／仕様のカバレッジ、リビール／ブレークポイントのチェック、その後に対象を絞った computed-diff.sh。
3. ルーティングされた生成後の検証には section-compare.sh を使用し、単独の広範なスイープには batch-scroll.sh と batch-compare.sh を使用します。セクションコマンドでは、ゲートがその sections/result.txt を読み取るため、4 番目の ref-dir 引数が必要です。
4. 失敗した行だけを auto-diagnose.sh で診断します。解決しない失敗については、症状に応じて tree-diff.sh、layout-tree-diff.sh、hover-tree-diff.sh、または keyframes-diff.sh の順にエスカレーションします。
5. 影響を受けたチェックとその依存関係のクロージャを再実行します。反復作業中はスコープを絞った検証または標準の検証を使用します。正規の最終確認には、呼び出し元の包括的な検証全体が引き続き必要です。

正確なコマンド、ONLY_IF_CHANGED、マスキングルール、またはツールの選択が必要な場合にのみ、tool-routing.md を読みます。ドメイン固有のセレクターセットが必要な場合にのみ、common-selectors.md を読みます。単独での完全なキャプチャ／検証の仕組みが必要な場合にのみ、verification.md を読みます。修正ループに入る場合、または Phase E をディスパッチする場合にのみ、comparison-fix.md を読みます。参照資料をすべて最初から読み込まないでください。

3 軸の完了条件

すべての位置で、次の 3 軸すべてを満たす必要があります。

軸	ツール	合格条件
ピクセル	AE	画像ごとの AE ≤ 500
知覚	DSSIM / フレーム SSIM	フレームごとの SSIM ≥ 0.995
セマンティック	委任された Phase E レビュー	PASS、または既知の差異に対する明示的な承認

計算スタイルの比較は、不一致が 0 件であれば合格です。AE=500 はアンチエイリアスによる差異を許容します。動的コンテンツでは、文書化された動的ルートを通じてのみ AE=2000 を使用できます。これらのしきい値は契約であり、明示的なユーザー承認と理由の記録がない限り変更できません。

完全な検証では Phase E が必須であり、AE と DSSIM の確認後に、すべての ref/impl 位置をレビューします。ホストネイティブの visual-debug-reviewer（利用可能な場合は Codex ネイティブのサブエージェント）に委任してください。それ以外の場合は、同じ契約を適用して汎用の委任ワーカーを使用します。拒否されたロール名で再試行しないでください。コーディネーターに戻すのは判定テーブルのみです。範囲を限定した診断目的の Phase E では、早い段階で代表的な既存ペアを確認できますが、その非正規アーティファクトを最終的な全位置レビューの代わりにすることはできません。comparison-fix.md を参照してください。

3 軸すべてが一致し、必要なすべての行が測定されている場合にのみ PASS を返します。FAIL、INCOMPLETE、UNMEASURED、古くなった証拠、または不足しているアーティファクトは、未完了のままです。その後、実装と正規の最終確認のために、呼び出し元のパイプラインを再開します。