ae-analysis-intent

TE 分析スキル

目標

• イベント、プロパティ、指標、レポート、ダッシュボード、モデルなど、適切なデータアセットを見つけられるよう支援します。
• まずコマンドを実行して、再現可能なクエリ結果を提供します。
• トレンドの解釈、異常の評価、根拠、実行可能な次のステップを提示します。

必須ルール

1. ツールの優先順位

   • 最優先：ae-cli。
   • 次点：te-mcp。ae-cli に該当する機能がない場合、またはパラメーター以外の理由で繰り返し失敗する場合に限ります。
   • Builder の検証エラー、パラメーター不足、need_clarification はフォールバックの理由になりません。

2. project_id の確認

   • プロジェクトを対象とするクエリを実行する前に、project_id を確認します。
   • ユーザーが指定せず、検証済みのプロジェクトコンテキストも存在しない場合は、まず確認してください。推測してはいけません。

3. アドホック分析の QP ルーティング

   • event、retention、funnel、prop_analysis では、まず該当する QP builder を使用します。
   • これらの builder を呼び出す前に、get_analysis_query_schema、list_events、list_properties、list_metrics、get_metric を呼び出してはいけません。
   • builder が status=generated を返した場合に限り、query_adhoc を呼び出します。
   • builder が need_clarification、invalid_argument、unsupported_feature、validation_error を返した場合は、処理を停止し、構造化された問題を確認または報告します。これら4つのモデルについて、QP を手作業で作成してはいけません。
   • distribution、attribution、heat_map、interval、path、rank_list、sql では、QP を構築する前に従来のスキーマ／メタデータの手順を使用します。

4. 既存アセットを優先

   • アドホック分析の前に、依頼が保存済みのビジネスアセットに該当する可能性がある場合は、既存のレポート／ダッシュボードを検索します。
   • 該当するレポート／ダッシュボードが見つかった場合は、重複するアドホッククエリを作成せず、それをクエリします。
   • ユーザーがカスタムのアドホックな調査を明示的に依頼している場合、または保存済みアセットで必要なフィルター／グルーピングに対応できない場合に限り、この手順を省略します。

5. 書き込み操作前の事前チェック

   • 作成／更新操作では、可能な限りまず --dry-run を付けて実行します。
   • 書き込みの成功後、リソース ID が利用可能であれば、analysis_common +get_resource_url を使ってリソースリンクを生成し、返します。

6. 絶対寄与による要因分析

   • 必須：指標の変化をディメンションに帰属させる際は、絶対寄与の分解を使用します。相対変化率だけで主要因を判断してはいけません。
   • 完全なアルゴリズムとワークフローについては、ae-analysis スキルの F. ABSOLUTE_CONTRIBUTION_ATTRIBUTION を参照してください。
   • 加法的な指標：delta_dim_i / baseline ではなく、|delta_dim_i| の順に並べます。
   • 比率指標：率の効果と構成の効果を分離し、階層的に報告します。
   • セルフチェック：出力前に、ディメンションの寄与の合計が約100%になることを確認します。

機能ルーティングルール

1. ae-cli に該当するコマンドがあるか確認します。
2. ある場合は、ae-cli で実行します。
3. パラメーター不足、フィールド型の不一致、時刻形式の不正、権限、タイムアウト、無効なペイロードが原因で ae-cli が失敗した場合は、まず修正して ae-cli で再試行します。
4. command-not-found、not-supported／not-implemented、明らかな機能不足、またはパラメーター以外の理由による繰り返しの失敗の場合に限り、te-mcp にフォールバックします。
5. フォールバックする場合は、ae-cli ではその機能を実現できない理由を簡潔に説明します。

ae-cli の主な機能一覧

コマンド形式：

ae-cli <service> +<command> [options]

プロジェクトとリソース

• プロジェクト一覧：ae-cli analysis_common +list_projects
• リソースリンクの生成：ae-cli analysis_common +get_resource_url -p <project_id> --resource_type <type> --resource_id <id>

メタデータの検索

• イベント一覧：ae-cli analysis_meta +list_events -p <project_id>
• プロパティ一覧：ae-cli analysis_meta +list_properties -p <project_id>
• 指標一覧：ae-cli analysis_meta +list_metrics -p <project_id>
• テーブル列：ae-cli analysis +get_table_columns -p <project_id> --table_ref <hive.schema.table|schema.table|table>

レポート／ダッシュボードのクエリ

• レポート一覧：ae-cli analysis +list_reports -p <project_id>
• レポート定義：ae-cli analysis +get_report_definition -p <project_id> -r <report_id>
• レポートデータ：ae-cli analysis +query_report_data -p <project_id> --report_ids '[<report_id>]'
• ダッシュボード一覧：ae-cli analysis +list_dashboards -p <project_id>
• ダッシュボードの詳細：ae-cli analysis +query_dashboard_detail -p <project_id> -d <dashboard_id>
• ダッシュボードのレポートデータ：ae-cli analysis +query_dashboard_report_data -p <project_id> -d <dashboard_id>

アドホック分析

ビルダーがサポートするモデル：

• イベント QP ビルダー：ae-cli analysis +build_event_analysis_qp ...
• リテンション QP ビルダー：ae-cli analysis +build_retention_analysis_qp ...
• ファネル QP ビルダー：ae-cli analysis +build_funnel_analysis_qp ...
• プロパティ分析 QP ビルダー：ae-cli analysis +build_prop_analysis_qp ...
• クエリを実行：ae-cli analysis +query_adhoc -p <project_id> --model_type <model_type> --qp '<builder_qp>'

レガシー／手動モデル：

• スキーマ：ae-cli analysis +get_analysis_query_schema --model_type <distribution|attribution|heat_map|interval|path|rank_list|sql>
• クエリを実行：ae-cli analysis +query_adhoc -p <project_id> --model_type <model_type> --qp '<manual_qp>'

ドリルダウンと詳細

• ユーザーのドリルダウン：ae-cli analysis +drilldown_users ...
• ユーザーのイベントシーケンス：ae-cli analysis +drilldown_user_events ...
• エンティティの詳細：ae-cli analysis +query_entity_details ...
• イベントの詳細：ae-cli analysis +query_event_details ...

標準的な実行フロー

1. 分析範囲を確認します：KPI、モデルタイプ、期間、ディメンション、フィルター、比較基準。
2. project_id を確認します。
3. 既存のレポートやダッシュボードが保存済みの業務アセットに該当する可能性がある場合は、検索します。
4. 該当するアセットがある場合は、レポート／ダッシュボードのデータをクエリします。
5. 既存のアセットを使用しない場合：
   • event ／ retention ／ funnel ／ prop_analysis：ビルダー -> query_adhoc
   • distribution ／ attribution ／ heat_map ／ interval ／ path ／ rank_list ／ sql：スキーマ／メタデータ -> 手動で QP を作成 -> query_adhoc
6. 異常がある場合は、まずチャネル／バージョン／時間／コホートで分析を分割し、必要に応じてユーザーとイベントの連鎖をドリルダウンします。
   • 絶対寄与度の分解を厳密に適用します。各ディメンションの絶対変化量と寄与率を算出し、絶対変化量の大きさ順に並べます。
7. 結論、主要な根拠、考えられる原因、制約、次のアクションを提示します。

出力要件

• まず主要な結論を示します。
• 主要なデータポイントとして、時間、ディメンション、指標、値、比較基準を含めます。
• 傾向や異常の原因について、確信度または検証の必要性を説明します。
• 実行可能な次のステップを提案します。
• 生の表だけを羅列しないでください。
• データ、定義、権限が不十分な場合は、制約を明示し、不足している情報を求めます。
• アトリビューションの出力要件：
  • 主要な結論で、指標の合計変化を絶対値とパーセンテージで示します。
  • ディメンション別の寄与を絶対変化量の降順で列挙します。各ディメンションについて、ディメンション値、絶対変化量、寄与率、相対変化を示します。
  • 相対変化が最大のディメンションではなく、寄与率が最も大きいディメンションに焦点を当てて結論を述べます。
  • 各ディメンションの寄与率の合計が約 100％ になることを自己確認します。差が 5 パーセントポイントを超える場合は、その旨を明記します。