/cja-top-movers-watchlist

name: cja-top-movers-watchlist
description: >
  Identifies which items (pages, campaigns, products, channels, regions) had the
  biggest increases or decreases for a key metric between two time periods. Use
  this skill when someone asks "what's up and what's down," "which campaigns
  moved the most," "top gainers and losers," "what pages are trending," "show me
  what changed by channel," or any variation of identifying the biggest movers
  and decliners for a metric.
license: Apache-2.0
metadata:
  author: Adobe
  version: "1.0"

Top Movers Watchlist (Customer Journey Analytics)

Surface the biggest gainers and decliners for a metric across any dimension in two time periods. The output tells the user exactly what moved, by how much, and whether items appeared or disappeared entirely — which is often the most interesting signal.

This skill is a faster, more targeted alternative to a full anomaly triage. Use it when the user wants to scan the landscape of changes rather than drill into a single anomaly.

---

CJA MCP Tools Used

• `describeCja(DATAVIEW_CONTEXT_GUIDE)` — load data view calendar/timezone
• `findMetrics` — resolve the metric being watched
• `findCalculatedMetrics` — if the metric is a custom KPI
• `findDimensions` — resolve the dimension to break down by
• `runReport` — pull dimension-metric data for both periods
• `searchDimensionItems` — validate dimension values if user specifies names

---

Phase 0 — Setup

1. Call `findDataViews` and `setDefaultSessionDataViewId` as needed. 2. Call `describeCja("DATAVIEW_CONTEXT_GUIDE")` to load data view context. Record the 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.3.

---

Phase 1 — Clarify Inputs

1.1 Metric

If the user specified a metric, resolve it:

findMetrics(search: "<user's metric name>")

If not specified, suggest the top 3 metrics from usage: > "Which metric would you like to track? I can suggest: Sessions, Revenue, > Orders based on what your team uses most."

1.2 Dimension (what to break down by)

Common dimension choices and their typical use cases:

| Dimension | Use Case | |--------------------|-----------------------------------------| | Marketing Channel | "Which channels moved?" | | Page Name | "Which pages are trending?" | | Campaign | "Which campaigns improved?" | | Product | "Which products gained/lost traction?" | | Country / Region | "Which markets moved?" | | Device Type | "Did mobile or desktop shift?" | | Referring Domain | "Which referrers changed?" |

If the user did not specify, ask: > "Which dimension should I break down by — for example, marketing channel, > page, campaign, country, or product?"

Call `findDimensions(search: "<dimension keyword>")` to resolve the dimension ID.

1.3 Periods

Define Period A (current) and Period B (comparison). Defaults:

• **Period A**: this week (or last 7 days)
• **Period B**: last week (or the 7 days before that)

If the user specifies "this month vs last month" or a custom range, map accordingly. Always confirm the periods before running reports: > "I'll compare **this week (Mar 13–19)** vs **last week (Mar 6–12)**. Sound right?"

**Calendar rule (mandatory):**

Use `WEEK_START_DOW` from Phase 0 to define what "week" means. Period A and 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 Period B ends immediately before Period A starts. Never mix conventions (e.g., a Mon–Sun Period A with a Sun–Sat Period B) within the same 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.

---

Phase 2 — Pull Data for Both Periods

Run two reports — one per period — with the same dimension breakdown:

runReport(
  dimensionIds: "<dimension id>",
  metricIds: "<metric id>",
  startDate: "<period A start>T00:00:00",
  endDate: "<period A end>T23:59:59",
  page: 0,
  limit: 50
)

runReport(
  dimensionIds: "<dimension id>",
  metricIds: "<metric id>",
  startDate: "<period B start>T00:00:00",
  endDate: "<period B end>T23:59:59",
  page: 0,
  limit: 50
)

Use `limit: 50` to capture enough items to surface meaningful movers. If the user's dimension has thousands of values (e.g., page names), limit to top 100 by Period A volume to keep the comparison meaningful.

Row data is in the `rows` array — each row has `value` (dimension item name) and `data[0]` (the metric value). There is no limit on dimension cardinality but results default to sorted by metric descending, which is what you want.

Always verify the dimension ID with `findDimensions(searchQuery: "<name>")` before running — dimension IDs can vary from what you might guess (e.g., `variables/marketing_channel` not `variables/marketingchannel`).

---

Phase 3 — Compute Rankings

Build a unified table joining both result sets on dimension value:

For each dimension value present in either period:

• `valueA` = metric value in Period A (0 if not present)
• `valueB` = metric value in Period B (0 if not present)
• `delta` = valueA − valueB
• `pctChange` = (delta / valueB) × 100 if valueB > 0, else "New Entry"
• `status`:
• Present in A but not B → **New Entry** (appeared this period)
• Present in B but not A → **Disappeared** (dropped out this period)
• Both present → normal mover

Sort by: 1. **Top Gainers**: sort by delta descending (biggest absolute ga