cja-kpi-pulse

KPI Pulse（Customer Journey Analytics）

2 分未満で簡潔な KPI ダイジェストを作成します。目的は、「結果はどうだったか？」に明確に答えることです。詳細な分析でも、データの羅列でもありません。各 KPI について、現在の値、前期間からの変化、推移の方向、および変動の要因を説明する上位のディメンション内訳を示すスコアカードを作成します。

---

使用する CJA MCP ツール

• describeCja(DATAVIEW_CONTEXT_GUIDE) — データビューのコンテキストを把握します
• listComponentUsage — 使用頻度の高い指標（組織で実際に使われている KPI）を見つけます
• findMetrics — ユーザーが指定した名前から指標 ID を特定します
• findCalculatedMetrics — 存在する場合はカスタム KPI を含めます
• runReport — 現在の期間と前期間の指標値を取得します
• searchDimensionItems — 変動した指標の上位ディメンション内訳を取得します

---

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

1. findDataViews を呼び出して、利用可能なデータビューを一覧表示します。
2. ユーザーがデータビューを指定していない場合は、一覧を提示して、どれを使用するか尋ねます。
3. 選択された ID を指定して setDefaultSessionDataViewId を呼び出します。
4. describeCja("DATAVIEW_CONTEXT_GUIDE") を呼び出して、データビューのコンテキストを読み込みます。 データビューの週の開始曜日を WEEK_START_DOW として、タイムゾーンを TIMEZONE として記録します。コンテキストガイドから週の開始曜日が返されない場合は、 月曜日（ISO 8601）をデフォルトとします。これらはフェーズ 1.1 で使用します。
5. モニタリングの対象範囲を確認します。追跡する KPI と比較期間（例：WoW、MoM、目標との比較）を尋ねます。

フェーズ 1 — 対象範囲の確認

1.1 レポート期間を決定する

ユーザーが期間を指定していない場合は、次の質問を 1 つ尋ねます。

「どの期間を対象にしますか？選択肢：直近 7 日間、直近 30 日間、今週と先週の比較、今月と先月の比較、またはカスタム期間。」

回答がない場合は、今週と先週の比較をデフォルトとします。

回答を 2 つの日付範囲に対応付けます。

• 期間 A（現在）：例：「thisWeek」、「thisMonth」、直近 7 日間
• 期間 B（比較）：例：「lastWeek」、「lastMonth」、その前の 7 日間

カレンダー規則（必須）：

フェーズ 0 の WEEK_START_DOW を使用して、「週」の定義を決めます。現在の 期間（期間 A）と比較期間（期間 B）では、同じ週の開始曜日を使用する必要があります。 つまり、両期間の startDate が同じ曜日になり、期間の長さが完全に等しく、 比較期間が現在の期間の開始直前に終了する必要があります。同じパルス実行内で 異なる規則を混在させないでください（例：現在の期間を月曜～日曜、前期間を日曜～土曜とする）。 境界を一度決めてから、両方の期間を算出してください。カスタム日付範囲の場合は、 期間 A の開始直前に終了する同じ長さの期間として期間 B を算出します。

runReport を呼び出す前の整合性チェック： periodA.startDate と periodB.startDate が同じ曜日であること、および periodA.startDate - periodB.endDate == 1 day であることを確認します。満たさない場合は、再計算します。

1.2 指標を決定する

ユーザーが特定の指標を指定した場合は、findMetrics または findCalculatedMetrics を使って特定します。それ以外の場合は、上位 5～8 個の KPI を自動的に見つけます。

listComponentUsage(componentType: "metric")
listComponentUsage(componentType: "calculatedMetric")

注：使用履歴がないデータビューでは、listComponentUsage が空のリストを返す場合があります。 空のリストが返された場合は、次にフォールバックします。

findMetrics(searchQuery: "sessions visits revenue orders")
findMetrics(searchQuery: "page views cart conversion")

結果から、ビジネス上最も重要な指標をこの優先順位で選びます（セッション、注文、売上、製品ビュー、カートビュー、ユーザー）。

重複を除きます。組み込み指標と計算指標が同じものを測定している場合は、より意図的に定義されている計算指標のみを残します。

最終リスト：5～8 個の指標。パルスレポートに 8 個を超える KPI を含めると、ノイズになります。

---

フェーズ 2 — 当期と前期のデータを取得する

すべての KPI 指標を含めて、各期間につき runReport を 1 回だけ実行します。 往復回数を最小限に抑えるため、期間 A に 1 回、期間 B に 1 回実行します。 サマリー次元（例：variables/daterangeday）を使用し、limit を 1 に設定して、 レスポンスの summaryData.totals から集計値を取得します。

runReport(
  dimensionIds: "variables/daterangeday",
  metricIds: "metrics/visits,metrics/visitors,metrics/orders_1_1,metrics/productListItems.priceTotal,metrics/cart_views",
  startDate: "<periodA start>T00:00:00",
  endDate: "<periodA end>T23:59:59",
  page: 0,
  limit: 1
)

runReport(
  dimensionIds: "variables/daterangeday",
  metricIds: "metrics/visits,metrics/visitors,metrics/orders_1_1,metrics/productListItems.priceTotal,metrics/cart_views",
  startDate: "<periodB start>T00:00:00",
  endDate: "<periodB end>T23:59:59",
  page: 0,
  limit: 1
)

行データではなく summaryData.totals から集計値を読み取ります。これにより、 列挙した順に各指標の期間全体の合計値を取得できます。

各指標について、次の値を記録します。

• valueA（当期）
• valueB（比較期間）
• delta = valueA − valueB
• pctChange = (delta / valueB) × 100、小数第 1 位に丸める

---

フェーズ 3 — トレンドを分類する

各 KPI にトレンド指標を割り当てます。

• ↑ 上昇：pctChange > +3%
• ↓ 下降：pctChange < −3%
• → 横ばい：−3% ≤ pctChange ≤ +3%

シグナルの色を割り当てます。

• 「高いほど良い」指標：↑ = 緑、↓ = 赤、→ = グレー
• 「低いほど良い」指標（直帰率、エラー率）：↑ = 赤、↓ = 緑

---

フェーズ 4 — 変動要因を掘り下げる

絶対値で変化率が最も大きい 1〜2 個の指標について、変動の要因を特定します。当期のディメンション内訳を実行します。

runReport(
  dimensionIds: "variables/marketing_channel",
  metricIds: "<moving metric id>",
  startDate: "<periodA start>T00:00:00",
  endDate: "<periodA end>T23:59:59",
  page: 0,
  limit: 5
)

注：variables/marketingchannel ではなく、variables/marketing_channel を使用します。 不明な場合は、findDimensions(searchQuery: "marketing channel") で正確なディメンション ID を確認してください。

期間 A と期間 B のディメンション値を比較し、変化への最大の寄与要因を特定します。これをレポートの「変動要因」欄に記載します。

---

フェーズ 5 — HTML レポートを生成する

KPI パルス HTML レポートはインラインで生成してください。Python スクリプトは使用しないでください。 収集したデータから HTML 文字列を直接組み立て、ユーザーが保存できるようコードブロックとして出力するか、1 行の bash コマンドで /tmp/cja_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 とします。
• 派生指標で置き換えてはいけません（例：Revenue が $0 だったため「Conversion Rate」を追加する）。表示する KPI セットは、この実行で選択した指標と必ず一致させてください。

HTML テンプレート

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

---

Phase 6 — レポートを作成する

HTML を生成した後：

1. /tmp/cja_kpi_pulse_report_<YYYY-MM-DD_HHMMSS>.html に書き込みます
2. open /tmp/cja_kpi_pulse_report_<YYYY-MM-DD_HHMMSS>.html で開きます
3. チャット内に3～5行のテキスト要約を提示します：

KPI Pulse — This Week vs Last Week

↑ Revenue: $1.24M (+8.2%)  — Paid Search drove most of the gain
↓ Conversion Rate: 2.1% (−0.4pp) — Drop in mobile checkout
→ Sessions: 540K (+1.1%)  — Flat week-over-week
↑ Orders: 11,340 (+6.7%)  — Product page improvements appear to be working
↓ Bounce Rate: 43.2% (+2.1pp) — Worth monitoring next week

HTML ファイルを開かなくてもすぐに役立つ情報を得られるよう、テキスト要約を提示します。

---

重要なガードレール

• 読み取り専用のモニタリングです。 指標、セグメント、プロジェクトを変更しないでください。
• 日付範囲を統一します。 前週比および前月比の比較では、期間の長さを揃えてください。
• 異常を指摘し、原因を診断しないでください。 パルスレポートでは大きな変動を表面化させます。根本原因の詳細な分析は、異常トリアージスキルの役割です。
• ビジネスカレンダーを尊重します。 祝日、キャンペーン、季節的な傾向は通常の変動に影響するため、異常を指摘する際は状況を記載してください。
• 指標数に上限を設けます。 1回のパルスでモニタリングする KPI は最大10～15件としてください。それ以上では焦点がぼやけます。ユーザーが多くの指標を指定した場合は、優先順位を尋ねてください。
• データの鮮度を記載します。 最新のデータポイントが想定より古い場合は、パルスを提示する前にユーザーへ警告してください。

やり取りの例

「今週の主要指標の状況を手短に教えてください。」

1. セットアップ： findDataViews でデータビューを確認します。ユーザーがメインのデータビューを選択します。setDefaultSessionDataViewId を呼び出します。
2. 対象範囲： 「どの KPI を含めますか？」と尋ねます。ユーザーは「セッション数、収益、コンバージョン率、平均注文額」と回答します。
3. データ取得： 4つの指標すべてについて、今週と前週を比較する runReport を実行します。
4. 分析： セッション数は前週比8％増（通常の範囲内）。収益は前週比3％増。コンバージョン率は前週比12％減 — 異常として指摘します。平均注文額は前週比17％増 — 注目すべきプラスの変化です。
5. 要約： 信号機方式のステータス（緑／黄／赤）を付けた KPI スコアカードを提示し、調査が必要なコンバージョン率の低下を強調します。また、平均注文額の増加が低下分を部分的に相殺していることを記載します。

エラー処理

• runReport が期間 B のデータを返さない場合（比較対象の期間が遠すぎる、またはデータビューに履歴がない場合）、差分に「N/A」を表示し、灰色のバッジで示します。
• 指標が null を返した場合、パフォーマンスがゼロであるかのような誤解を避けるため、0 ではなく「—」を表示します。
• 利用可能な指標が3件未満の場合は、パルスが不完全な可能性をユーザーに警告し、データビューが正しく設定されているか確認するよう提案します。