visual-qna

ビジュアルQ&A

概要

構造化された質問をインタラクティブなフォームとしてPlaywright制御のブラウザーに表示し、ユーザーが回答（単一選択または複数選択。「その他」の選択肢と各質問ごとの自由記述メモ付き）をクリックして選べるようにしてから、回答を構造化データとして読み取ります。ネイティブの一問ずつ進めるターミナル形式では時間がかかる、まとめて行う意思決定に適しています。

基本的な考え方：Playwright MCPを介して、再利用可能なフォームエンジンをabout:blankに注入します。サーバーもファイルもポートも不要です。

使用する場面

• 複数選択式の質問をまとめて行う場合（目安として3問以上）：ブレインストーミングでの意思決定、選択肢選び、アンケート、A/B/Cの選択など。
• 固定の選択肢に加えて、質問ごとのメモ欄や「その他」の選択肢が必要な場合。
• 回答を構造化データとして受け取り、次の作業に活用したい場合。

使用しない場面

• モックアップ、ワイヤーフレーム、図、ビジュアルデザインの比較 → それはビジュアルコンパニオンの役割であり、この機能の役割ではありません。このスキルは質問に回答するためのもので、画像を見るためのものではありません。
• 簡単な質問が1、2問の場合 → ターミナルで尋ねるか、ネイティブのAskUserQuestionツールを使ってください。
• Playwright MCPを利用できない場合 → 「要件」を参照してください。

要件（必須の依存関係）

このスキルにはPlaywright MCPのブラウザーツール（browser_navigate、browser_evaluate、browser_take_screenshot）が必要です。利用できない場合は、処理を中止し、Playwright MCPプラグインを有効にするようユーザーに伝えてください。回避策を試してはいけません。（file:// URLはPlaywrightによってブロックされ、ローカルHTTPサーバーもサンドボックスによってブロックされることが多いため、確実な代替手段はありません。このスキルは仕様上、Playwright専用です。）

手順

1. Playwright MCPが利用可能か確認します。 利用できない場合は、エラーとして終了します（「要件」を参照）。
2. browser_navigateでabout:blankに移動します。
3. 同じディレクトリにあるqa-form.jsをReadし、ファイル全体の内容をbrowser_evaluateのfunction引数として渡します。（すでに( ) => {}形式のアロー関数になっています。実行すると、ページ上にwindow.__qaInit、__qaToggle、__qaNote、__qaResultsが定義されます。）
4. browser_evaluateで() => window.__qaInit(CONFIG)を実行します。CONFIGは質問セットです（「スキーマ」を参照）。これによりフォームが表示されます。
5. browser_take_screenshotを実行し、ユーザーにフォームを見せます。
6. 参照用に質問を短いテキストリストとしてチャットに投稿し、ユーザーに**「ブラウザーで回答をクリックして選択し、終わったら返信してください。」**と伝えます。ここでターンを終了します。
7. 次のターンでbrowser_evaluateにより() => window.__qaResults()を実行し、返されたJSONを解析します。ユーザーが追加したターミナルのテキストがあれば統合します。構造化された結果を、要求元に渡します。

質問を再度行う場合や内容を変更する場合は、window.__qaInit(newConfig)を再度呼び出します（状態がリセットされます）。ユーザーが引き続き編集している場合は、結果を再度読み取るだけでかまいません。

設定スキーマ

{
  title: "Sub-project 6 — Dashboard Composition",
  questions: [
    {
      id: "q1",                       // stable, simple slug (no quotes/spaces)
      title: "Layout model",
      detail: "Optional one-line context.",
      options: [
        { letter: "A", text: "...", recommended: true },
        { letter: "B", text: "..." }
      ],
      multi: false,                   // true = allow multiple selections
      allowOther: true                // default true; appends a dashed "O — Other"
    }
  ]
}

結果の形式

window.__qaResults()はJSONを返します。

{
  selections: { q1: "B", q2: ["A", "C"], q3: "O" },  // string (single) or array (multi)
  notes:      { q3: "free text the user typed" }
}

• 選択内容がtruthy（複数選択の場合は空ではない配列）であれば、その質問は「回答済み」です。
• "O"はユーザーが**「その他」**を選んだことを示します。内容はnotes[id]から読み取ってください。

ビジュアルコンパニオンとの非干渉

このスキルは、ブレインストーミング用の「ビジュアルコンパニオン」と意図的に分離されています。

• Playwright MCPブラウザーのみを使用します。HTTPサーバーの起動、ポートの開放、.superpowers/（または他のコンパニオンのセッションディレクトリ）への書き込みは一切行いません。
• ビジュアルコンパニオンのセッションが進行中の同じターンでは実行しないでください。 異なるブラウザーでユーザーの注意を取り合うことになります。
• 役割分担：ビジュアルコンパニオン＝「このモックアップ／図を見て」；ビジュアルQ&A＝「これらの質問に回答して」。

よくある間違い

間違い	修正方法
エンジンをインラインで手書きする	常に qa-form.js を Read して、そのまま注入してください。独自に作り直さないでください。
file:// URL やローカルサーバーを使おうとする	ブロックされています（Playwright／サンドボックス）。about:blank と注入のみを使用してください。
ユーザーが返信する前に結果を読み取る	描画したらターンを終了し、ユーザーが完了したと言ってから __qaResults() を読み取ってください。
モックアップや図に使う	適切なツールではありません。ビジュアルコンパニオンを使用してください。
スペースや引用符を含む id を使う	シンプルなスラッグを使用してください。インラインの onclick ハンドラーに埋め込まれます。
selections[id] がないのに回答を推測する	ない場合は未回答です。質問するか未決定として扱い、推測しないでください。