/cja-kpi-pulse

name: cja-kpi-pulse
description: >
  Produces a compact KPI digest showing how key metrics changed over a period and
  what's driving the movement. Use this skill when someone asks for a performance
  summary, a weekly recap, a morning briefing, a KPI update, or any variation of
  "how did we do this week/month." Also trigger for requests like "give me a
  performance overview," "what moved in the last 7 days," "pull our KPI report,"
  or "summarize our metrics."
license: Apache-2.0
metadata:
  author: Adobe
  version: "1.0"

KPI Pulse (Customer Journey Analytics)

Produce a compact KPI digest in under 2 minutes. The goal is a crisp answer to "how did we do?" — not a deep-dive, not a data dump. Each KPI gets a scorecard showing current value, period-over-period change, trend direction, and the top dimension breakdown that explains any movement.

---

CJA MCP Tools Used

• `describeCja(DATAVIEW_CONTEXT_GUIDE)` — understand the data view context
• `listComponentUsage` — find the most-used metrics (the org's real KPIs)
• `findMetrics` — resolve metric IDs from user-specified names
• `findCalculatedMetrics` — include custom KPIs if present
• `runReport` — pull metric values for current and prior periods
• `searchDimensionItems` — top dimension breakdown for movers

---

Phase 0 — Setup

1. Call `findDataViews` to list available data views. 2. If the user hasn't specified a data view, present the list and ask which to use. 3. Call `setDefaultSessionDataViewId` with the chosen ID. 4. Call `describeCja("DATAVIEW_CONTEXT_GUIDE")` to load data view context. Record the data view's first-day-of-week as `WEEK_START_DOW` and timezone as `TIMEZONE`. If the context guide does not return a week-start value, default to **Monday** (ISO 8601). You will use both in Phase 1.1. 5. Clarify the monitoring scope: which KPIs to track and the comparison period (e.g., WoW, MoM, vs. target).

Phase 1 — Clarify Scope

1.1 Determine the reporting period

If the user did not specify a period, ask one question: > "What time window would you like? Options: last 7 days, last 30 days, this > week vs last week, this month vs last month, or a custom range."

Default to **this week vs last week** if no answer is given.

Map the answer to two date ranges:

• **Period A** (current): e.g., "thisWeek", "thisMonth", last 7 days
• **Period B** (comparison): e.g., "lastWeek", "lastMonth", prior 7 days

**Calendar rule (mandatory):**

Use `WEEK_START_DOW` from Phase 0 to define what "week" means. The current period (Period A) and the comparison period (Period B) MUST use the same first-day-of-week — i.e., both periods' `startDate` fall on the same day-of-week, both are exactly equal length, and the comparison period ends immediately before the current period starts. Never mix conventions (e.g., a Mon–Sun current with a Sun–Sat prior) within the same pulse run. Pick the boundary once, then derive both periods from it. For custom date ranges, compute Period B as the equal-length window ending immediately before Period A starts.

**Sanity check before calling `runReport`:** confirm `periodA.startDate` and `periodB.startDate` are the same day-of-week and that `periodA.startDate - periodB.endDate == 1 day`. If not, recompute.

1.2 Determine the metrics

If the user named specific metrics, resolve them with `findMetrics` or `findCalculatedMetrics`. Otherwise, discover the top 5–8 KPIs automatically:

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

Note: `listComponentUsage` may return an empty list for data views with no usage history. If it returns empty, fall back to:

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

Pick the most business-relevant metrics from the results (sessions, orders, revenue, product views, cart views, people — in that priority order).

Deduplicate: if a built-in metric and a calculated metric measure the same thing, keep only the calculated metric (it's more intentional).

Final list: 5–8 metrics. More than 8 KPIs in a pulse report is noise.

---

Phase 2 — Pull Current and Prior Period Data

Run a single `runReport` call per period with all KPI metrics included. Use one call for Period A and one for Period B to minimize round-trips. Use a summary dimension (e.g., `variables/daterangeday`) and limit: 1 to get aggregate totals from `summaryData.totals` in the response.

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
)

Read aggregate totals from `summaryData.totals` (not row data), which gives you the full-period sum for each metric in the order they were listed.

Capture for each metric:

• `valueA` (current period)
• `valueB` (comparison period)
• `delta` = valueA − valueB
• `pctChange` = (delta / valueB) × 100, rounded to 1 decimal

---

Phase 3 — Classify Trends

For each KPI, assign a trend indicator:

• **↑ Up** if pctChange > +3%
• **↓ Down** if pctChange < −3%
• **→ Flat** if −3% ≤ pctChange ≤ +3%

Assign a signal color:

• For "higher is better" metrics: ↑ = green, ↓ = red, → = grey
• For "lower is better" metrics (bounce rate, error rate): ↑ = red, ↓ = green

---

Phase 4 — Top Mover Drill-Down

For the 1–2 metrics with the largest absolute % change, find what's driving the movement. Run a dimension breakdown for the current period:

runReport(
  dimensionIds: "variables/marketing_channel",
  metricIds: "<moving metric