cja-kpi-pulse

What this skill does

# 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 id>",
  startDate: "<periodA start>T00:00:00",
  endDate: "<periodA end>T23:59:59",
  page: 0,
  limit: 5
)
```

Note: Use `variables/marketing_channel` (not `variables/marketingchannel`) — 
verify the exact dimension ID with `findDimensions(searchQuery: "marketing channel")`
if unsure.

Compare dimension values between Period A and Period B to identify the top
contributor to the change. This becomes the "What drove it" entry in the report.

---

## Phase 5 — Generate HTML Report

Generate the KPI Pulse HTML report INLINE — do not use a Python script.
Build the HTML string directly from the collected data and output it as a
code block the user can save, or write it to `/tmp/cja_kpi_pulse_report_<YYYY-MM-DD_HHMMSS>.html`
using a one-line bash command.


### Rendering rules — apply consistently across runs

Two runs of this skill on the same data view + period must render identically
(modulo the generation timestamp). The rules below pin the formatting choices
that the AI would otherwise drift on.

#### Number formatting

- **KPI values** (the big number in each tile) — use full digits with
  thousands separators (`8,160`, `77,584`, `1,250,000`). Do **NOT** use SI
  suffixes like `K` or `M`, even for large values. Executives want exact
  numbers, not abbreviations.
- **Percent change** (in pills and narrative bullets) — always one decimal
  place, rounded **half-away-from-zero**. For example, `−23.55%` displays as
  `−23.6%`, never `−23.5%`. Compute on full-precision values; round only at
  display time.
- **Percentage-point change** (for already-percentage metrics like Conversion
  Rate or Bounce Rate) — same rounding, suffix `pp`. Example: `+0.40 pp`.
- **Currency** — `$` prefix with thousands separators and no decimals for
  values ≥ $100 (`$1,240,000`); cents only when value < $100 (`$45.20`).

#### Null / missing data handling

A KPI tile must reflect what the data view actually returned. The AI must
**not** silently substitute a different metric or hide a tile to make the
report look cleaner.

- **Both periods return 0 or NULL** for a KPI being rendered: render the tile
  with `kpi-value` = `Data unavailable`, pill class `flat`, pill text
  `⚠ N/A`, and `prior` text = `Both periods returned no data — validate
  instrumentation`. The tile stays in the grid; do not omit it.
- **One period returns valid data, the other 0 / NULL**: render the tile with
  the valid value as `kpi-value`, pill class `flat`, pill text `⚠ N/A`, and
  `prior` text = `Prior {period_noun}: no data`.
- **Never** substi