maestro/pieces/sns-research.yaml

name: sns-research
description: |
  X (Twitter)・Reddit・Hacker News などの SNS から意見・評判・議論を収集しレポートにまとめる。
  選ぶべき場合: 「Redditで何と言われているか」「Xでの反応」など SNS の声を調べたいとき
  選ぶべきでない場合: 一般的なWeb調査、ニュース記事の収集、ドキュメント処理
triggers:
  keywords: ["Reddit", "reddit", "Twitter", "Hacker News", "HackerNews", "サブレディット", "subreddit"]
max_movements: 999
initial_movement: gather

movements:
  - name: gather
    persona: researcher
    instruction: |
      ## 実行日 {DATE}（過去の成果物の上書き防止）
      システムプロンプトの「現在日時」の日付 (YYYY-MM-DD) を {DATE} とする。
      成果物は必ず {DATE} 入りのパスに書き、**過去の実行が残したファイルは編集も削除もしない**。
      {DATE} 入りの成果物が1つでも既に存在し（output/raw/{DATE}/ だけでなく、他の調査 piece が
      作った output/report-{DATE}.md 等も含めて確認する）、それが別タスクのものなら
      {DATE}-2, {DATE}-3 ... を全ファイル共通で使う
      （このタスク内で gather に戻ってきた場合は同じディレクトリに追記してよい）。
      {DATE} を決めたら、最初の収集結果をすぐ output/raw/{DATE}/ に書き出してキーを確保する
      （並行する別タスクとの衝突の余地を減らす）。

      ## 調査計画

      着手前に調査計画を立てる:
      1. 調査対象と対象 SNS を決定する
      2. 検索クエリ案を複数考える（日本語・英語の両方を検討）
      3. verify からの差し戻しがある場合は、不足点を優先的に解消する

      計画に従って SNS から情報を収集し、Write で output/raw/{DATE}/ にテキストファイルとして書き出す。

      ## SNS 別の収集方針

      ### X (Twitter)
      - キーワードで広く拾う → XSearch
      - 特定アカウントの発言を追う → XUserPosts
      - 議論の流れ・リプライツリーまで欲しい → XPostDetail
      - ログイン中アカウントのホームタイムライン（おすすめ / フォロー中）を見る → XTimeline

      ### Reddit
      BrowseWeb で必ず **old.reddit.com** を使う（軽量でテキスト抽出しやすい）。
      - 検索: `old.reddit.com/search?q=キーワード`
      - スレッド: `old.reddit.com/r/{サブレディット}/comments/...`

      ### Hacker News
      WebFetch で Algolia API を使う。
      - 検索: `https://hn.algolia.com/api/v1/search?query=キーワード`
      - 記事詳細: `https://hn.algolia.com/api/v1/items/{id}`

      ## ファイル命名規則
      `output/raw/{DATE}/{platform}-{query-slug}.txt`
      例: output/raw/2026-07-08/reddit-ollama-vs-vllm.txt, output/raw/2026-07-08/x-ollama-review.txt

      ## SNS 調査の原則
      モデルの内部知識だけで情報を書かないこと。必ず実際の SNS データを収集する。
      検索ヒットがゼロだった場合も、その事実を raw ファイルに記録する（捏造しない）。

      ## 画像・スクリーンショットの収集
      SNS 投稿には画像・グラフが含まれることが多い。重要なビジュアルは DownloadFile で
      `output/images/{DATE}/{platform}-{slug}.png` に保存する。

      ## 終了 / 遷移方法
      - **次の analyze へ**: `transition({next_step: "analyze"})`
      - **追加収集のため同じ gather を続行**: `transition({next_step: "gather"})`
      - **対象が曖昧で確認が必要**: `complete({status: "needs_user_input", missing_info: "...", why_no_default: "..."})`
      - **技術的失敗で打ち切り**: `complete({status: "aborted", abort_reason: "..."})`
    default_next: analyze
    rules:
      - condition: 追加収集が必要（別のSNS、追加クエリ等）
        next: gather
      - condition: 十分な情報を収集した
        next: analyze

  - name: analyze
    persona: analyst
    instruction: |
      output/raw/ の収集データを読み込み、分析してレポートを作成する。

      このタスクの gather が書き出した日付ディレクトリを {DATE} とする。
      会話から分からない場合のみ、Glob output/raw/*/* でファイルを列挙し
      （ディレクトリ末尾の output/raw/*/ はファイルにマッチせず常に空になるので使わない）、
      GetFileProvenance で created_by_task_id がこのタスクのものを選ぶ。
      それでも特定できなければ親ディレクトリ名の日付と連番を数値として解釈して
      最新のキーを選ぶ（-2 は無印より新しく -10 は -9 より新しい）。
      過去の実行のファイルは編集・削除しない。

      手順:
      1. Glob で output/raw/{DATE}/ 内のファイル一覧を確認
      2. 各ファイルを Read で読み込む
      3. 重要な意見・トレンド・共通見解を抽出
      4. ポジティブ/ネガティブな意見を分類
      5. output/report-{DATE}.md にレポートを書き出す

      ## レポートの構成
      - トピック概要
      - SNS 別の主な意見（X / Reddit / HN それぞれ）
      - 共通する見解・分岐する意見
      - まとめ

      ## 画像の活用
      output/images/{DATE}/ に画像がある場合は必ずレポートに埋め込む:
      `![説明](./images/{DATE}/ファイル名.png)`

      情報が不足している場合は gather に戻る（追加の検索クエリを明示すること）。
      verify からの差し戻しがある場合は、指摘された不足点・期待する修正を優先的に解消すること。

    default_next: verify
    rules:
      - condition: output/report-{DATE}.md にレポートを書き出した
        next: verify
      - condition: 情報が不十分で追加収集が必要
        next: gather

  - name: verify
    persona: supervisor
    instruction: |
      output/ のレポートを確認する。
      審査対象はこのタスクの analyze が書いたレポート（output/report-{DATE}.md）。ここまでの
      会話で書き出したパスをそのまま使う。会話から分からない場合のみ Glob output/report-*.md で
      列挙し、GetFileProvenance で created_by_task_id がこのタスクのものを選ぶ。
      それでも特定できなければ日付と連番を数値として解釈して最新を選ぶ
      （-2 は無印より新しく -10 は -9 より新しい。拡張子込みの辞書順ソートは
      無印が -2 より後に並ぶため使わない）。
      過去の実行のレポートは対象外で、編集・削除もしない。

      確認手順:
      1. Glob で output/ 内のファイル一覧を確認する
      2. output/report-{DATE}.md がなければ「不足がある」と判断し analyze に差し戻す
      3. ファイルがあれば Read で内容を確認し、網羅性・正確性・分かりやすさをチェックする
      4. 不足があれば、`transition({next_step: "analyze", summary: ...})` で差し戻す。summary は次の形式で書く:
         [判定] needs_fix
         ## 問題点
         - [ファイル名:行番号または項目名] 何が問題か
         ## 期待する修正
         - 何をどう直すべきか
         ## 合格基準
         - 再レビューで何を確認するか
         ## 次にやること
         - 差し戻し先で最初に着手すべき具体的な作業
      5. summary は抽象論で終えず、具体的な不足点・期待する修正内容を必ず含める

      追加チェック（画像）:
      - output/images/{DATE}/ に画像があるのにレポートに `![` が一つもない場合、
        画像埋め込み漏れとして analyze に差し戻す

      ## チェックシート確認
      GetChecklist でチェックシートが存在する場合、全アイテムが完了（done/failed/skipped）していることを確認する。
      remaining が 0 でないまま完了してはならない。

      ## 合格時のユーザーへの返答（complete ツール）
      output/ の内容で合格と判断したら、`complete({status: "success", result: ...})` を呼ぶ。
      result はそのままユーザーに表示される最終回答。output/report-{DATE}.md を Read で読み、その内容をベースに整形する。
      - 「output/xxx.md を確認してください」のようなファイル参照ではなく、内容そのものを回答として返すこと
      - 【厳守】「✅ 完了」「レポートを作成しました」「確認しました」等のステータス表示・メタ説明は一切書かない。1行目からいきなり本題の内容を書き始めること
      - 調査結果・発見・結論を会話調で分かりやすく伝える
      - 表・リスト・見出しなど Markdown 書式を活用して読みやすくする

      ## 終了方法のまとめ
      - 合格: `complete({status: "success", result: "ユーザー向け最終回答"})`
      - 修正必要: `transition({next_step: "analyze", summary: "差し戻し指摘"})` (上記形式で)
      - 技術的失敗: `complete({status: "aborted", abort_reason: "..."})`
    default_next: COMPLETE
    rules:
      - condition: output/ にファイルがない、または内容に不足がある
        next: analyze