marketing-social-pulse

前文（最初に実行）

_KS_REPO=""
_KS_REAL_SKILL="$(cd "$HOME/.claude/skills/marketing-social-pulse" 2>/dev/null && pwd -P || true)"
for _candidate in \
  "${KAITO_SKILLS_DIR:-}" \
  "$( [ -n "$_KS_REAL_SKILL" ] && cd "$_KS_REAL_SKILL/../.." 2>/dev/null && pwd -P || true )" \
  "$HOME/kaito-skills" \
  "$HOME/.kaito-skills/repo"
do
  [ -n "$_candidate" ] || continue
  if [ -f "$_candidate/skills.json" ] && [ -x "$_candidate/bin/kaito-skills-update-check" ]; then
    _KS_REPO="$_candidate"
    break
  fi
done

if [ -n "$_KS_REPO" ]; then
  echo "KAITO_SKILLS_REPO $_KS_REPO"
  _UPD=$("$_KS_REPO/bin/kaito-skills-update-check" 2>/dev/null || true)
  [ -n "$_UPD" ] && echo "$_UPD" || true
fi

出力に KAITO_SKILLS_REPO <path> が表示された場合は、そのパスを KAITO_SKILLS_REPO として記憶してください。

出力に UPGRADE_AVAILABLE <old> <new> が表示された場合は、<KAITO_SKILLS_REPO>/docs/update-kaito-skills.md を読み、続行する前に「インラインアップグレードフロー」に従ってください。ユーザーが更新チェックを延期または無効にした場合は、現在のスキルで続行してください。

出力に JUST_UPGRADED <from> <to> が表示された場合は、ユーザーに Running kaito-skills v{to} (just updated!) と伝えて続行してください。

ソーシャルパルス

特定のエンティティについて、認知度やセンチメント、より広範なソーシャル指標をユーザーが尋ねた場合に、このスキルを使用してください。特に、回答に期間別の異常値、12か月間のコンテキスト、掘り下げた説明を含める場合に使用します。

入力

• token：プロジェクト名、ティッカー、または解決済みの Kaito トークン値です。上流のワークフローから unresolved_string と確認済みの official_handle がすでに渡されている場合に限り、省略できます
• official_handle：token を明確に解決できない場合に、shared-entity-resolution に渡す任意の事前ヒントです。未解決モードで処理を完了する場合は必須です
• unresolved_string：shared-entity-resolution が事前に作成した任意のキーワード文字列です。確認済みの official_handle とともにすでに渡されている場合に限り使用してください
• affiliate_handles：正規の除外セットに統合する必要があることがすでにわかっている場合に使用する、任意のカンマ区切りハンドルです
• duration：7d、30d、90d、または start と end を指定した過去の期間です（デフォルトは 30d）

ワークフロー

ワークフローを「エンティティの解決」「データ収集」「分析」「出力」の4つの段階に分けて進めます。

1. エンティティの解決

メトリクスを取得する前に、エンティティの識別情報、除外対象、分析期間を正確に確定します。

上流のワークフローから確認済みの未解決 ID パッケージがすでに渡されている場合を除き、まず shared-entity-resolution を使用します。

• unresolved_string が確認済みの official_handle とともにすでに提供されている場合、そのペアを shared-entity-resolution からの未解決 ID パッケージとして扱い、再構築しないでください。
• それ以外の場合は、トークンの曖昧さへの対処、公式ハンドルの調査、ハンドルの確認、未解決キーワード文字列の作成について、../shared-entity-resolution/SKILL.md に従ってください。
• shared-entity-resolution から返された ID パッケージを引き継いでください。
  • 解決済みモード：RESOLUTION_MODE = resolved、RESOLVED_TOKEN = <kaito token>。さらに、kaito_twitter_official_account から取得できる場合は OFFICIAL_HANDLE と AFFILIATE_HANDLES も引き継ぎます。
  • 未解決モード：RESOLUTION_MODE = unresolved、OFFICIAL_HANDLE = <confirmed official handle>、UNRESOLVED_STRING = <keyword string>
• 未解決モードで続行する前に、OFFICIAL_HANDLE が必ず設定されていることを確認してください。
• 再利用可能なエンティティ検索フィルターを作成します。
  • 解決済みモード：ENTITY_SEARCH_FILTER = tokens=<RESOLVED_TOKEN>
  • 未解決モード：ENTITY_SEARCH_FILTER = keyword=<UNRESOLVED_STRING>
• 解決済みモードでは、mindshare、sentiment、mentions、engagement、kaito_mindshare_entity_by_account を利用できます。
• 未解決モードでは、mentions、engagement、検索ベースの詳細分析のみを続行します。mindshare、sentiment、kaito_mindshare_entity_by_account は利用できないため、出力で明示してください。
• 除外処理に使えるよう、解決済みモードでも利用可能な場合は OFFICIAL_HANDLE を特定してください。
• 解決済みモードで、引き継いだ ID パッケージに OFFICIAL_HANDLE または AFFILIATE_HANDLES が含まれていない場合は、除外対象を作成する前に RESOLVED_TOKEN を指定して kaito_twitter_official_account を呼び出してください。
• 正規の公式ハンドル、kaito_twitter_official_account が返したアフィリエイトハンドル、ユーザーが追加で提示した確認済みの affiliate_handles から EXCLUDED_HANDLES を作成してください。
• 未解決モードでは、確認済みの公式ハンドルと、すでに確認されている追加の affiliate_handles のみを含めてください。アフィリエイトを推測してはいけません。
• エンドポイントまたはユーザー入力からアフィリエイトハンドルを取得できない場合でも、公式ハンドルは除外し、アフィリエイトの除外が不完全な可能性があることを明記してください。
• 指定された期間を、正確な window_start と window_end のタイムスタンプに変換してください。
• window_end を基準にした過去12か月の開始日時として、context_start も定義してください。
• 分析と出力では、「先月」などの相対的な表現だけでなく、正確な日付を使用してください。

2. データ収集

2.1 現在のウィンドウと直近12か月の指標を並行して取得する

モードに応じた一式を実行します。

1. 解決済みモード：
   • 指定された分析ウィンドウの kaito_mindshare_entity
   • window_end を末日とする直近12か月の kaito_mindshare_entity
   • 指定された分析ウィンドウの kaito_sentiment_entity
   • window_end を末日とする直近12か月の kaito_sentiment_entity
   • sources="Twitter" を指定した、分析ウィンドウの kaito_mentions
   • sources="Twitter" を指定した、window_end を末日とする直近12か月の kaito_mentions
   • 指定された分析ウィンドウの kaito_engagement
   • window_end を末日とする直近12か月の kaito_engagement
2. 未解決モード：
   • 未解決のエンティティ表現を使用し、sources="Twitter" を指定した、分析ウィンドウの kaito_mentions
   • 未解決のエンティティ表現を使用し、sources="Twitter" を指定した、window_end を末日とする直近12か月の kaito_mentions
   • 未解決のエンティティ表現を使用した、分析ウィンドウの kaito_engagement
   • 未解決のエンティティ表現を使用した、window_end を末日とする直近12か月の kaito_engagement

解決済みモードでは、mindshare と sentiment を主要な分析軸として扱います。mentions と engagement は、変化の主な読み取りに取って代わるのではなく、認識の変化を説明するための補助的な裏付けとして使用します。

実際に実行したすべての指標について、返された時系列全体を保持し、次の点を比較できるようにします。

• 指定されたウィンドウ内の異常パターン
• ウィンドウレベルの傾向と、エンティティのより長期的な12か月の傾向

kaito_mentions では、Twitter のみを含めます。Twitter を中心とするソーシャル指標の変化を説明するうえで、Twitter 以外のソースは関係しないため、mentions の分析から他のすべてのソースタイプを除外します。

3. 分析

3.1 異常を検出し、12か月の傾向の中でウィンドウを位置付ける

有効な解決モードで利用できる指標のみを使い、現在のウィンドウと12か月の時系列を合わせて分析します。

以下を特定します。

• 指定されたウィンドウ内で、利用可能な各指標に見られる異常な急増や急落
• 利用可能な指標が異なる方向に動く乖離点
• 指定されたウィンドウが、エンティティの直近12か月のベースラインを上回るか、下回るか、またはその近辺にあるか
• ウィンドウの傾向が、より長期的な傾向に対して加速、減速、反転、正常化のいずれを示すか

モード別の解釈：

• 解決済みモード：まず mindshare と sentiment に注目し、次に mentions と engagement を補助的な文脈および裏付けとして使用します
• 未解決モード：mentions と engagement を合わせて分析し、mindshare と sentiment は構造化指標として利用できないことを明示します

異常の選定ルール：

• データが裏付ける場合は、複数の異常ウィンドウを残します。
• 異常なバケットが隣接している場合は、1つの調査ウィンドウとして扱います。
• 実際に実行した指標における複合的な規模、持続性、関連性に基づいて異常を順位付けします。
• 明確な異常がない場合は、その期間はイベント主導ではなく傾向主導だったと述べ、異常の詳細調査の手順を省略します。

3.2 異常の詳細調査に必要な証拠を収集する

各異常ウィンドウについて、以下の手順を実行します。

1. kaito_advanced_search
   • Resolve Entity のエンティティ検索フィルターを使用します。
     • 解決済みモード：tokens=<RESOLVED_TOKEN>
     • 未解決モード：keyword=<UNRESOLVED_STRING>
   • sources="Twitter"
   • sort_by="smart_engagement"
   • size=100
   • min_created_at=<anomaly_start>
   • max_created_at=<anomaly_end>
   • EXCLUDED_HANDLES が利用可能な場合は、必ず exclude_handles=<EXCLUDED_HANDLES> を指定します。
   • 目的：異常ウィンドウ中の対象エンティティに関する、外部ユーザーによる上位 100 件のツイートを取得します。
2. 貢献者の特定
   • 解決済みモード：
     • エンドポイントが期間の指定に対応している場合は、異常ウィンドウを指定して RESOLVED_TOKEN の kaito_mindshare_entity_by_account を実行します。
     • エンドポイントが近い期間のプリセット範囲にしか対応していない場合は、利用できる中で最も近い範囲を使用し、その旨を記載します。
     • これを使って、マインドシェアに最も定量的に貢献したアカウントを特定します。
   • 未解決モード：
     • kaito_mindshare_entity_by_account はスキップします。
     • 繰り返し登場する頻度、スマートエンゲージメント、異常に関する議論での注目度などのシグナルを使い、異常ウィンドウの Twitter コーパスから最も関連性の高い外部の発信者を直接特定します。
   • どちらのモードでも、最も関連性の高い貢献者のハンドルについて、利用可能な場合は kaito_twitter_account_type を呼び出し、異常の要因が KOL、研究者、トレーダー、ビルダー、コミュニティアカウントのいずれかを特徴付けられるようにします。
3. アカウントの追加検索
   • 上記の貢献者の特定手順で選んだ、最も関連性の高い貢献者ハンドルを対象に kaito_advanced_search を実行します。
   • Resolve Entity と同じエンティティ検索フィルターを使用します。
   • usernames=<top contributor handles> を追加します。
   • 同じ異常の期間を指定します。
   • 実用上可能な場合はページネーションを行い、異常ウィンドウ中に該当アカウントが投稿したコンテンツをすべて取得します。
   • 目的：異常を主に引き起こしたアカウントが具体的に何を発言したのかを確認します。

アカウントの追加検索を行う貢献者ハンドルを選ぶ際は、異常を説明するために必要な最小限の集合を調べます。通常は上位 5～10 人の貢献者、またはその期間で明らかに大きな割合を占めるアカウント群です。

3.3 Summary and Conclusions のナラティブを特定する

Summary and Conclusions を作成する前に、簡易的なナラティブの確認を行います。

• kaito_narratives を呼び出し、Kaito の正式なナラティブ一覧を取得します。
• Summary and Conclusions に、その一覧のナラティブが含まれているか確認します。
• 言及されているナラティブが Kaito の正式なナラティブに一致する場合は、返された narrative の値をそのまま使って構造化ナラティブトークンを表示します。ただし、要点を述べている既存の文の中に自然に組み込んでください。
• Summary and Conclusions のテーマが正式なナラティブ一覧に一致しない場合は、平易な表現のみで言及し、構造化ナラティブトークンを創作しないでください。

4. 出力

以下の4セクション構成を優先してください。ユーザーが具体的な質問をした場合は、特に Summary and Conclusions で、その構成の中でより直接的に回答してください。ユーザーが具体的な質問をしていない場合は、デフォルトの要約またはレポートとして同じ構成を使用してください。

次の順序で、4つのセクションを正確に出力してください。

• Summary and Conclusions
  • ユーザーの依頼に対する最も直接的な回答から始め、指定された期間のソーシャル全体の動向と主な結論を要約してください。
• Key Observations
  • このセクションは記述的かつデータを中心にしつつ、観察結果をユーザーの依頼に結び付けてください。
  • 認識に焦点を当てます。resolved モードでは、まずマインドシェアの推移とセンチメントの推移を示し、その後、補足情報としてメンション数とエンゲージメントを示してください。unresolved モードでは、実際に利用可能な指標に焦点を当ててください。
• Key Insights
  • ユーザーの依頼に関連付けて、異常が起きた理由を説明してください。
  • 人気の高いツイートから得られる詳細な証拠、現在のモードで利用できる最適な投稿者帰属手法、該当アカウントが実際に何を述べたかを活用してください。
• Suggested Actions
  • ユーザーの依頼と、確認された認識の変化に基づく具体的な次のアクションを提示してください。
  • 確認された認識の変化と特定された要因を踏まえ、チームが取るべき対応に焦点を当ててください。

ユーザーが明示的に求めない限り、スコアカードやベンチマークのセクションを追加しないでください。

Summary and Conclusions の構造化出力ルール：

• このセクションは大まかで簡潔にしてください。異常の詳細な内訳、長いツイートの例、期間ごとの指標の詳細を繰り返さないでください。
• Summary and Conclusions でアカウントのハンドル名に言及する場合は、@handle の形式で表記してください。先頭の @ は、フロントエンドがアカウントをレンダリングするための判定シグナルです。
• Summary and Conclusions で解決済みのナラティブに言及する場合は、[[narrative:<narrative>]] の形式で表記してください。<narrative> には、kaito_narratives が返した narrative フィールドの値をそのまま使用してください。
• Matched narratives: [[narrative:AI]], [[narrative:L2]] のように、独立したラベルや文末のトークン一覧を追加しないでください。
• トークンを表示するためだけに文を分けず、「議論は [[narrative:AI]] を中心に展開しました」のように、自然な表現を優先してください。
• ユーザーが別の箇所でも同じ形式での表記を明示的に求めない限り、構造化ナラティブトークンは Summary and Conclusions のみに記載してください。

ルール

• 要求された期間は、直前の12か月間のコンテキストとあわせて常に分析してください。
• 常にユーザーの実際の依頼に沿って回答してください。4つの出力セクションは回答形式であり、ユーザーの依頼への直接的な回答に代わるものではありません。
• 解決済みモードでは、主要な動向を説明する際に、mentions や engagement よりも mindshare と sentiment を優先してください。
• 異常の根本原因を分析する際は、公式アカウントおよびアフィリエイトの投稿を自社メディア由来のノイズとして扱い、可能な限り除外してください。
• Key Observations は定量的かつ記述的な内容にしてください。そこに因果関係の推測を含めないでください。
• 解決済みモードでは、mentions と engagement は、mindshare と sentiment の変化を説明または裏付ける補助的な証拠として扱い、主要指標と同等の優先度で見出しにしないでください。
• 因果関係の解釈は Key Insights に記載し、ツイートの証拠と、現在のモードで利用できる最善のアカウントレベルの帰属判定手法に結び付けてください。
• 貢献者の分類を利用できる場合は、ハンドル名を列挙するだけでなく、それを使って変化の要因の内訳を説明してください。アカウントの役割や、裏付けのない影響力ラベルを創作しないでください。
• いずれかのエンドポイントで除外、ページネーション、または期間指定のサポートが不完全な場合は、その制限を明確に記載し、隠さないでください。
• エンティティが未解決のままの場合は、不足している構造化指標を明示し、推測で補わないでください。
• エンティティが未解決のままの場合は、ドリルダウンとトレンド分析はキーワードベースであり、エンティティ精度が解決済みトークンモードより低くなる可能性があることを明確に述べてください。
• 異常が見つからない場合は、そのことを明示し、長期的なトレンドの文脈に焦点を当ててレポートしてください。
• smart money ではなく、smart accounts と表記してください。

TODO

対応する MCP エンドポイントが利用可能になったら、以下の計画中の指標拡張を追加してください。

1. ローリング方式で集計したユニークな smart accounts
   • ローリング方式で集計した smart-account の参加状況を時系列で取得する専用の MCP エンドポイントを追加する
   • mindshare、sentiment、mentions、engagement に加え、認知品質を測る追加シグナルとして使用する
2. sentiment の内訳
   • sentiment の内訳を時系列で取得する専用の MCP エンドポイントを追加する
   • 単一の集計済み sentiment 系列を超えて、sentiment の分析を充実させるために使用する