video-qa

video-qa は何をしますか？

デモMP4を意図されたストーリーボードと照合し、鋭い人間のレビュアーが書くであろうタイムスタンプ付きチェックリストを返します。2層構造：決定論的プローブ（ffmpeg/ffprobe/node — 機械的な検出、モデルの推論なし）と、プローブのコンパクトなJSONレポートとスクリプトに基づく限定されたフレーム群に対して推論するフレッシュな分析サブエージェントです。

ハードルール：分析は常に新しいサブエージェントで実行する

呼び出し側（メインスレッドのあなた）は最小限のことを行います：

1. 入力を特定します。
2. プローブスクリプトを実行します。
3. 分析を行うための新しい独立したサブエージェント（Agentツール）を起動します。
4. サブエージェントの問題リストをユーザーに転送します。

呼び出し側のスレッドで抽出されたフレームを読んだり、レポートについて自分で推論したりしないでください。 ポイントはトークンの分離です。5分の動画では約50フレームと大きなJSONレポートが生成されます。それらを推論するには、画像+分析で数万トークンのコストがかかります。それが呼び出し側のコンテキストに入ると、セッションの残りを汚染します。サブエージェントがそれを吸収し、短い問題リストだけを返します。これはオプションでも「都合が良ければ」でもありません。すべての video-qa 呼び出しはハンドオフします。references/handoff.md を参照してください。

ステップ1 — 入力を収集する

必要なもの：

• 動画パス — QA対象のMP4（レビュアーが視聴する最終カット）。
• ストーリーボード / スクリプト — 意図されたビートの順序、タイミングの期待値、各セグメントが何を表示すべきか。ユーザーから提供されていない場合は、それを（またはそれが由来するissueや demo-video ストーリーボードを）依頼してください。ビートをでっち上げないでください。
• 期待されるカード — 順序通りのスクリプトカード（カバー、アジェンダ、各インタースティシャル、まとめ）。それらを --cards-file 用の小さなJSONファイルに書き出します：{ "label": "カバー（タイトル＋サブタイトル）" } エントリの配列（より長いカードの読み取り時間バーを上書きするには "minRead": <秒> を追加します）。これは決定論的カードクロスチェックを駆動します — カードは作成されたナレーションであるため、第一級の出力です。
• ブランディング — カード/背景色とカーソル/注釈色。プローブがブランドカードを分類し、サブエージェントがコントラストをチェックできるようにします。指定がない場合のデフォルト：尋ねてください。ブランドを推測しないでください。

ステップ2 — 決定論的プローブを実行する

node ${CLAUDE_PLUGIN_ROOT}/skills/video-qa/scripts/probe.mjs \
  --video "<絶対パス/to/video.mp4>" \
  --out   "<workdir>/video-qa-report.json" \
  --frames-dir "<workdir>/video-qa-frames" \
  --card-rgb 15,81,255 \          # ブランドカードの色をR,G,Bで指定（例：#0F51FF）
  --cards-file "<workdir>/cards.json"   # 期待されるストーリーボードカード、順序通り

スクラッチ/テンポラリ <workdir> を使用してください（例：/tmp 配下）。ユーザーのリポジトリは使わないでください。プローブはJSONレポートと限定されたフレームセットを書き出し、レポートパスを出力します。3つの全動画フィルターパス（フリーズ、シーンカット、モーション）とシーンごとのサンプリングを実行します — 動画の実時間の約1〜1.5倍の時間を見積もってください。調整可能なパラメータ（すべてオプション、適切なデフォルト値組み込み）：--card-tol、--demo-freeze、--annot-freeze、--card-min-read（読み取り時間バー、2.5秒）、--annotate-rgb R,G,B — 注釈のコールアウト色。指定すると、その色の「ここを見て」注釈リングがある無音領域は意図的なペーシング（annotated: true）として扱われ、見出しの無音領域カウントから除外され、欠陥としてフラグされません。各検出器が何を測定し、なぜしきい値がそのように設定されているかについては references/detectors.md を参照してください。

注釈検出は無音領域に限定されているため、annotatedRegionCount: 0 は「動画に注釈がない」という意味ではありません。 リングが保持/フリーズスパンと一致した場合にのみ登録されます。ビルドが無音部分をトリミングしたり（またはリングが動きのある部分で再生されたり）した場合、リングは画面上にレンダリングされますが、その無音領域にはリングが含まれません — カウントは設計上0になります。その数値だけから注釈が欠落していると報告しないでください。ビートが何かにリングを付けるようにスクリプトされている場合は、そのセグメントのフレーム（シーンごとの span-* フレーム、または注釈のタイムスタンプでフレームを取得）から確認してください。

ハンドオフする前に、出力されたサマリー（スパン数、無音領域、グリッチ数、フレーム数、cardCheck.countMatches）を健全性チェックしてください。cardSpans が0の場合、--card-rgb がおそらく間違っています — 修正して再実行してください。そうしないと、すべてのカードが ui と読み取られ、フリーズ/無音/カード分類が無意味になります。cardCheck でカウント不一致が示された場合、それは実際の所見です（カードの欠落または余分）、プローブエラーではありません — サブエージェントにフレームと照合して確認させてください。

ステップ3 — 分析サブエージェントに引き継ぐ

Agent ツール（subagent_type: general-purpose）を使用して新しいサブエージェントを起動します。references/analysis-prompt.md からプロンプトを構築し、以下を置き換えてください：

• {{REPORT_PATH}} → ステップ2の --out パス。
• {{FRAMES_DIR}} → --frames-dir パス。
• {{OUT_FINDINGS}} → あなたが読み取る所見ファイルのパス（例：<workdir>/video-qa-findings.md）。
• {{STORYBOARD}} → ステップ1の意図されたビートをそのまま。
• {{BRANDING}} → ステップ1のブランディングルール。

サブエージェントに — 初期プロンプト内の明示的な指示として — そのターンの最後のステップとして所見を {{OUT_FINDINGS}} に書き込むように伝えてください。そのファイルを読み取ることが信頼できる取得経路です：起動されたエージェントの最終テキストメッセージが常に呼び出し側に配信されるとは限らず、「あなたの所見を送って」というフォローアップpingは、アイドル状態で再エンゲージしないエージェントに頻繁に当たります。そのファイルには問題リストのみが含まれ（フレームは含まれません）、トークン分離を壊しません。サブエージェントはレポート＋フレームを読み取り、ビートごとに推論します。結果をあなたが読み取れる場所に永続化するだけです。

ステップ4 — 転送する

所見ファイル（{{OUT_FINDINGS}}）を読み取り、問題リストをそのままユーザーに渡してください（すでに成果物フォーマットです）。フレームについてのあなた自身の推論から何も追加しないでください — 設計上、それらを見ていません。ユーザーがブランド化されたHTMLアーティファクトとして希望する場合は、それは別のフォローアップです。

「判断不能」の項目は、欠陥として扱う前にスポットチェックしてください。 プローブは限定されたフレームセット（数十フレーム、すべてのフレームではありません）をサンプリングするため、実際に発生したビートがサンプルの間に落ち、「判断不能」または「ページホップした/表示されていないようだ」というフラグになる可能性があります — サンプリングギャップであり、実際の欠落ではありません。これらは誤っている可能性が最も高い所見です。そのような各項目について、それが発生するべき正確なタイムスタップの数フレームを取得し（例：ffmpeg -ss <t> -i video.mp4 -frames:v 1 …）、欠陥として報告する前に直接確認してください。実際に動画に欠けているものだけを報告してください。確認できたビートは、サンプリングセットの外で検証されたという注釈付きで✅にダウングレードしてください。

何をキャッチするか（そして何ができないか）

• 信頼性が高く機械的： 無音 / フリーズしたUI領域（動き密度スキャン）、シーン/セグメント構造、ブランドカードとUIの分類、グリッチクラスター（迷ったリフレッシュ / ページホップフリッカー）、全体的なコントラスト/輝度統計。
• 限定されたフレームに対するサブエージェントの推論： スクリプトにない配管UI（管理ダッシュボード、ログ、エラートレース）— ビート間の短いログイン/ローディング/空/管理フラッシュやセグメント途中のリロードを含み、許容可能な遷移ではなく、ポリッシュの欠陥として扱われます；過剰編集 / ハードカット（無音トリミングが実際の動きを切り取った — カーソルが移動なしでテレポート、ページ遷移がハードジャンプにスナップ、アクション途中のカット）これらは偽物と解釈されます；欠落/間違ったビート；ナビゲーションスタイルを第一級のチェックとして（製品内をブラウズしたか、ページホップで深いページに入ったか）；カードが存在するだけでなく機能しているか（読み取り可能な長さ、矛盾する/空の隣接カードによって損なわれていないか）で判断、カバーとアジェンダカードを内容で区別；間違った画面上データ（カウント、壊れた行）；注釈の欠落；ブランディング/コントラストのトラップ。
• 盲点： アクティブな領域中にキャプションが画面上にない場合（ローディングアニメーションは動きとして読み取られる）、およびアクションが実際に失敗したのかフレーム外で編集されたのか。サブエージェントはこれらを「判断不能」として表面化します。

references/validation-notes.md は、このスキルがリファレンスフィクスチャの人間レビューによるゴールデンリストに対してどのようにスコアリングされたかを記録しています。