aa-kpi-pulse

KPI Pulse（Adobe Analytics）

選択した期間に主要指標がどのように変化したか、どの項目が変化を促したか、何が目立ったかを示す、簡潔で把握しやすい KPI ダイジェストを作成します。すべての KPI を 2 回の runReport 呼び出し（現期間＋比較期間）にまとめ、結果を HTML のパフォーマンスカードデッキに組み立てます。

---

使用する AA MCP ツール

• findReportSuites — 使用するレポートスイートを選択
• setSessionDefaults — セッションのコンテキストを設定（reportSuiteId + globalCompanyId）
• describeAa(REPORT_SUITE_CONTEXT_GUIDE) — 組織のコンテキスト、主要指標、カレンダー設定、タイムゾーンを読み込む
• findMetrics — 指標 ID を検出して検証
• listComponentUsage — ユーザーが指定していない場合に、使用頻度の高い指標を特定
• runReport — 期間ごとに 1 回の呼び出しで、すべての KPI をまとめて取得（現期間＋比較期間）
• searchDimensionItems — 主要な変動要因のコールアウトに使う上位の貢献項目を検索

---

フェーズ 0 — セットアップ

1. findReportSuites / setSessionDefaults でレポートスイートを確認します。
2. describeAa(REPORT_SUITE_CONTEXT_GUIDE) を呼び出して、組織のコンテキスト（主要指標、カレンダー設定、タイムゾーン）を読み込みます。レポートスイートの週の開始曜日を WEEK_START_DOW として、レポートスイートのタイムゾーンを TIMEZONE として記録します。フェーズ 2 でレポート期間を計算する際に、両方を使用します。コンテキストガイドに WEEK_START_DOW がない場合は、月曜日（ISO 8601）をデフォルトにします。

findReportSuites(globalCompanyId: "<gcid>")
setSessionDefaults(globalCompanyId: "<gcid>", reportSuiteId: "<rsid>")
describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE")

---

フェーズ 1 — KPI を選択

1.1 ユーザーが指標を指定した場合

各指標を AA の指標 ID に解決します。

findMetrics(searchTerm: "<metric name>")

焦点を絞ったパルスにするため、指標は最大 8 個にします。それ以上を要求された場合は、優先順位を付けてもらうか、複数のレポートに分けることを提案します。

1.2 ユーザーが指標を指定していない場合

listComponentUsage を使用して、レポートスイートで最も使用されている指標を見つけます。

listComponentUsage(componentType: "metric")

使用回数の多いものから上位 5～7 個を選択します。次のようにユーザーに確認します。

「使用状況に基づいて、訪問数、ページビュー、売上、注文数、コンバージョン率、直帰率を追跡します。これでよいですか？それとも調整しますか？」

---

フェーズ 2 — 期間を選択

レポート対象の期間をユーザーに尋ねるか、コンテキストから推測します。

リクエスト	現期間	比較期間
「今週」	過去 7 日間	その前の 7 日間
「今月」	月初から現在まで	先月の同じ期間
「先月」	直近の暦月全体	前年の同じ月
「今四半期」	四半期初めから現在まで	前四半期の同じ期間
「年初来」	1 月 1 日から今日まで	前年の同じ期間

次のように確認します。「[現期間] と [比較期間] を比較します。よろしいですか？」

カレンダーのルール（必須）： 現期間と比較期間では、フェーズ 0 の WEEK_START_DOW を必ず同じように使用します。週次パルスでは、両期間の startDate が同じ曜日になり、どちらも正確に 7 日間で、比較期間は現期間の開始直前に終了する必要があります。同じパルス内で異なる規則を混在させてはいけません（例：現期間を月曜～日曜、比較期間を日曜～土曜にする）。カスタムの日付範囲では、現期間と同じ長さで、現期間の開始直前に終了する期間を比較期間として計算します。

runReport 呼び出し前の整合性チェック： current.startDate と comparison.startDate が同じ曜日であり、current.startDate - comparison.endDate == 1 day であることを確認します。そうでない場合は、再計算します。

例外ケース： 今日が期間の最初の 3 日間にあたる場合は、現期間のデータが不完全で、比較結果に偏りが出る可能性があることを伝えます。

---

フェーズ 3 — KPI データの取得

選択したすべての指標を、期間ごとに 1 回の呼び出しにまとめます。

runReport(
  metricIds: "<metricId1>,<metricId2>,<metricId3>,...",
  dimensionId: "variables/daterangeday",
  startDate: "<current period start>T00:00",
  endDate: "<current period end>T23:59"
)

runReport(
  metricIds: "<metricId1>,<metricId2>,<metricId3>,...",
  dimensionId: "variables/daterangeday",
  startDate: "<comparison period start>T00:00",
  endDate: "<comparison period end>T23:59"
)

注: metricIds にはカンマ区切りの ID を指定できます。すべての KPI を一度に渡してください。 dateRange ではなく startDate／endDate を使用してください。granularity パラメーターはありません。 日ごとの内訳には variables/daterangeday を使用してください。 summaryData.totals[0]、totals[1] などは、それぞれ順番に各指標に対応します。 権限のない指標は columnErrors に表示されますが、呼び出しの残りの部分は成功します。

指標の数にかかわらず、呼び出しは合計 2 回です。

各ペアから、次を計算します。

• 現在値（期間中の合計）
• 前期間の値（比較期間中の合計）
• 絶対差：現在値 - 前期間の値
• 変化率：（差 / 前期間の値）× 100
• 傾向：正の値なら ↑、負の値なら ↓、±2% 以内なら →

---

フェーズ 4 — 主な変動要因の背景

変化率の絶対値が最も大きい 1～2 個の指標（正負を問わず）について、 ディメンション別の内訳を取得し、主な要因を特定します。

runReport(
  metricIds: "<metricId>",
  dimensionId: "variables/marketingchannel",
  startDate: "<current period start>T00:00",
  endDate: "<current period end>T23:59",
  limit: 5
)

関連する場合は、2 つ目のディメンションについても繰り返します（例：トラフィック急増時のページ、 売上変動時の商品）。

結果を使って、要因を説明する 1～2 文を作成します。

「訪問数は前週比で 18% 増加しました。主な要因はオーガニック検索の増加（+34%）で、 ダイレクトトラフィックの減少（-12%）を相殺しました。」

---

フェーズ 5 — HTML レポートの生成

KPI パルス HTML レポートをインラインで作成し、 /tmp/aa_kpi_pulse_report_<YYYY-MM-DD_HHMMSS>.html に書き込みます。

レンダリングルール — 実行ごとに一貫して適用

同じレポートスイートと期間に対してこのスキルを 2 回実行した場合、生成時刻を除き、 同一の表示結果にする必要があります。以下のルールにより、AI が通常であれば 変えてしまう書式の選択を固定します。

数値の書式

• KPI 値（各タイルの大きな数値） — 桁区切りを付けた完全な数値を使用します （8,160、77,584、1,250,000）。大きな値であっても、K や M などの SI 接頭辞は使用しないでください。経営幹部が求めているのは略記ではなく正確な数値です。
• 変化率（ピルおよび説明文の箇条書き） — 常に小数点以下 1 桁にし、 ゼロから離れる方向に四捨五入します。たとえば、−23.55% は −23.6% と表示し、 −23.5% とは表示しません。完全な精度の値で計算し、表示時にのみ丸めてください。
• パーセンテージポイントの変化（コンバージョン率や直帰率など、すでにパーセントで表される指標） — 同じ丸め方を使用し、接尾辞に pp を付けます。例：+0.40 pp。
• 通貨 — 値が 100 ドル以上の場合は、ドル記号（$）を前置し、桁区切りを付け、小数点以下を表示しません（$1,240,000）。値が 100 ドル未満の場合のみ、セントまで表示します（$45.20）。

NULL／欠損データの処理

KPI タイルには、レポートスイートが実際に返した内容を反映する必要があります。AI は、 レポートを見栄えよく整えるために、別の指標へ黙って置き換えたり、タイルを非表示にしたりしてはいけません。

• レンダリング対象の KPI について、両期間とも値が 0 または NULL の場合：kpi-value を Data unavailable、ピルのクラスを flat、ピルのテキストを ⚠ N/A にし、prior のテキストを Both periods returned no data — validate instrumentation にします。タイルはグリッドに残し、省略しないでください。
• 一方の期間は有効なデータを返し、もう一方の期間は 0 または NULL の場合：有効な値を kpi-value とし、ピルのクラスを flat、ピルのテキストを ⚠ N/A にし、prior のテキストを Prior {period_noun}: no data にします。
• 導出した指標（例：売上が $0 だったため「コンバージョン率」を追加すること）への置き換えは決して行わないでください。表示する KPI のセットは、この実行で選択した指標と必ず一致させてください。

HTML テンプレート

template.html を読み込み、そのまま使用してください。HTML 構造や CSS を独自に変更せず、{ORG_NAME}、{PERIOD_LABEL}、{COMPARISON_LABEL}、{REPORT_SUITE}、{GENERATED_DATE}、{METRIC_NAME}、{FORMATTED_VALUE_A}、{FORMATTED_VALUE_B}、{PCT_CHANGE}、{VALUE_A}、{VALUE_B}、{DELTA}、{ARROW} の {PLACEHOLDER} トークンのみを埋めてください。また、KPI タイル／詳細行／変動項目の各ブロックは、データ項目ごとに 1 回ずつ繰り返してください。Phase 3 のトレンドルールに従い、.up | .down | .flat および .green | .red | .yellow | .grey の修飾クラスを保持してください。

セクションタイトル — フェーズ番号は付けません：HTML レポートのセクション見出しに、フェーズ番号を含めないでください。セクション名のみを使用してください（例：「Phase 2 — KPI Scorecards」ではなく「KPI Scorecards」、「Phase 4 — Top Movers」ではなく「Top Movers」）。

完成した HTML を /tmp/aa_kpi_pulse_report_<YYYY-MM-DD_HHMMSS>.html に書き込み、次に開いてください：

open /tmp/aa_kpi_pulse_report_<YYYY-MM-DD_HHMMSS>.html

---

KPI カードの色分けルール

• 変化が +2% 以上の場合、差分バッジは緑
• 変化が -2% 以下の場合、差分バッジは赤
• 変化が -2% から +2% の間の場合、差分バッジはグレー（横ばい）
• カード上部の境界線：プラスの変動は緑、マイナスの変動は赤、横ばいはグレー

---

インライン要約（必ず提供）

HTML レポートに加えて、短いインラインテキスト要約を必ず提供してください：

KPI Pulse — [Period] vs [Comparison]
Report Suite: [Name]

Metric              Current   Change
─────────────────   ───────   ──────
Visits              124,500   ▲ 18%
Revenue             $42,800   ▲  9%
Conversion Rate       2.4%    ▼  0.3pp
Page Views          398,200   ▲ 11%
Bounce Rate          48.2%    ▼  1.8pp

Key driver: Visits growth led by Paid Search (+34%).
Revenue up on strong Mobile performance (+22%).

---

ガードレール

• データを取得する前に、必ずユーザーに対象期間を確認してください。期間の誤りは、最もよくある混乱の原因です。
• 部分期間は明確に示してください（例：「今月はデータがあるのは 5 日分のみです」）。
• 割合指標（コンバージョン率、直帰率）では、変化を変化率ではなくパーセンテージポイント（pp）で報告してください。
• 適切な呼び出し回数に収めるため、指標は最大 8 件にしてください。追加の指標が必要な場合は、2 回目のパルスレポートを提案してください。

---

やり取りの例

「先週の KPI の最新情報を教えてください。」

1. findReportSuites と setSessionDefaults でレポートスイートを確認します。
2. describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE") でコンテキストを読み込みます。
3. listComponentUsage(componentType: "metric") またはユーザーの入力から、上位 6 件の指標を特定します。
4. 「直近 7 日間と、その前の 7 日間」を確認します。
5. runReport を 12 回実行します（指標ごとに 2 回）。metricIds、startDate、endDate、dimensionId: "variables/daterangeday" を使用します。各期間の合計値には summaryData.totals[0] を合計します。
6. 変動の大きい 2 件について、ディメンション別の内訳を実行します（dimensionId: "variables/marketingchannel" を使用）。
7. HTML レポートを生成して開き、インライン要約を提供します。
8. 説明：「有料検索を主な要因として、訪問数は前週比で 18% 増加しました。モバイルが伸びをけん引し、売上は 9% 増加しました。直帰率は 1.8pp 改善しました。」