--- name: aa-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 (Adobe Analytics) Identify which dimension items had the biggest increases and decreases for a key metric between two time periods. Surface the top gainers and losers across pages, channels, campaigns, products, or any other breakout dimension. --- ## AA MCP Tools Used - `findReportSuites` — select report suite - `setSessionDefaults` — set session context (reportSuiteId + globalCompanyId) - `describeAa(REPORT_SUITE_CONTEXT_GUIDE)` — load calendar/timezone context - `findMetrics` — resolve the key metric ID - `findDimensions` — discover available breakdown dimensions - `runReport` — period A and period B for each dimension - `searchDimensionItems` — validate specific items if needed --- ## Phase 0 — Setup 1. Confirm report suite with `findReportSuites` / `setSessionDefaults`. 2. Call `describeAa(REPORT_SUITE_CONTEXT_GUIDE)` to load report suite context. Record: - `WEEK_START_DOW` — first-day-of-week from the context guide. If the context guide returns no value, use **Monday** (ISO 8601) as the explicit deterministic default. This is not a fallback that drifts between runs: every run on the same report suite resolves to the same `WEEK_START_DOW`, either from the context guide or from the fixed Monday default. - `TIMEZONE` — report suite timezone. - `WEEK_START_DOW_SOURCE` — `"context guide"` if the value came from `describeAa`, `"default"` if the context guide was silent and Monday was used. Surface this in the artifact footer so the source is auditable. You will use these values in Phase 1 when defining Period A and Period B. ``` findReportSuites(globalCompanyId: "") setSessionDefaults(globalCompanyId: "", reportSuiteId: "") describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE") ``` --- ## Phase 1 — Confirm Parameters Ask the user: 1. **Metric** — "Which metric should I rank movers by? (visits, revenue, conversions, page views, etc.)" If not specified, default to `metrics/visits`. 2. **Dimension** — "Which dimension should I break down? - Pages - Marketing Channel - Campaigns - Products - Traffic Sources - Geographic Regions - Entry Pages" If not specified, offer the above list. 3. **Time periods** — "What two periods should I compare?" Common defaults: - This week vs. last week - This month vs. last month - Last 7 days vs. prior 7 days - Last 30 days vs. prior 30 days **Calendar rule (mandatory):** Period A and Period B MUST use the same `WEEK_START_DOW` from Phase 0 — 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. 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. 4. **Item limit** — how many top gainers and losers to show (default: 10 each). 5. **Materiality threshold** — minimum absolute value in Period A or B to be included (filters out noise from low-volume items). Default: exclude items with fewer than 100 visits (or equivalent) in both periods. Confirm: "I'll show the top 10 gainers and losers for [metric] broken down by [dimension], comparing [Period A] vs [Period B]." --- ## Phase 2 — Resolve Components ``` findMetrics(expansions: "componentType") findDimensions(page: 1, limit: 100) ``` > **Note:** `findMetrics` requires the `expansions` parameter (use `"componentType"` > or `"categories"`). `findDimensions` requires `page` and `limit`. Record `id` for the metric and dimension. --- ## Phase 3 — Run Period Reports Run the metric for the selected dimension in both periods: ``` runReport( metricIds: "", dimensionId: "", startDate: "T00:00", endDate: "T23:59", limit: 200 ) runReport( metricIds: "", dimensionId: "", startDate: "T00:00", endDate: "T23:59", limit: 200 ) ``` > **Note:** `runReport` uses `metricIds` (not `metricId`) and `startDate`/`endDate` > in ISO 8601 format (`YYYY-MM-DDTHH:mm`), not a `dateRange` parameter. Use `limit: 200` to capture enough items for a meaningful mover analysis. --- ## Phase 4 — Compute Deltas and Rank For each dimension item present in either period: 1. Period A value (or 0 if not in results) 2. Period B value (or 0 if not in results) 3. Absolute delta: Period A - Period B 4. Percent change: delta / Period B × 100 (or "+100% new" if Period B = 0) 5. Apply materiality filter: exclude items where max(Period A, Period B) < materiality threshold Sort by absolute delta descending for gainers (positive delta). Sort by absolute delta ascending for losers (negative delta). Take top N from each list. ### Special cases - **New items** (present in Period A only): flag as "New — no prior period data." Include if materiality threshold met. - **Disappeared items** (present in Period B only, 0 in Period A): flag as "Dropped — no current period data." - **Near-zero items**: items with <1% of total metric value — consider excluding from the watchlist unless they show very large percent changes. --- ## Phase 5 — Optional Multi-Dimension Watchlist If the user wants movers across multiple dimensions (e.g., both pages AND channels), repeat Phase 3–4 for each additional dimension. Each additional dimension adds 2 more `runReport` calls. ``` runReport(metricIds: "", dimensionId: "variables/marketingchannel", startDate: "T00:00", endDate: "T23:59", ...) runReport(metricIds: "", dimensionId: "variables/page", startDate: "T00:00", endDate: "T23:59", ...) ``` Group results into separate tables by dimension in the HTML report. --- ## Phase 6 — Generate HTML Report Build the movers report inline and write to `/tmp/aa_top_movers_report_.html`. ### Rendering rules — apply consistently across runs Two runs of this skill on the same report suite + metric/dimension + 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 summary tile, and per-row mover values) — 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. Stakeholders 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 or mover row must reflect what the report suite 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 the tracked metric in a summary tile: 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** substitute a different metric (e.g., switching from Revenue to Orders because Revenue came back $0). The metric being analyzed MUST be the metric rendered. ### HTML template ```html Top Movers — {ORG_NAME} — {METRIC_NAME}

{ORG_NAME} Top Movers

Biggest gainers and decliners for {METRIC_NAME} between {PERIOD_A} and {PERIOD_B}.

📅 {PERIOD_A} vs {PERIOD_B} 📊 {REPORT_SUITE} 🕔 Prepared {GENERATED_DATE}

Metric: {METRIC_NAME} | Period A: {PERIOD_A} | Period B: {PERIOD_B} | Materiality: ≥{THRESHOLD} {METRIC_UNIT}

{DIMENSION_NAME}

▲ Top Gainers

#	Item	Period A	Period B	Delta	% Change

▼ Top Losers

#	Item	Period A	Period B	Delta	% Change

``` **Section titles — no phase prefix**: Section headings in the HTML report must **not** include the phase number. Use the plain section name only (e.g., "Top Movers" not "Phase 3 — Top Movers", "Dimension Breakdown" not "Phase 4 — Dimension Breakdown"). Write to `/tmp/aa_top_movers_report_.html` and open: ```bash open /tmp/aa_top_movers_report_.html ``` --- ## Inline Summary (Always Deliver) Always follow the HTML report with a brief text callout: ``` Top Movers: [Metric] — [Period A] vs [Period B] GAINERS (by [Dimension]) 1. [Item A] +12,400 visits (+34%) 2. [Item B] +8,200 visits (+21%) 3. [Item C] +5,100 visits (+18%) LOSERS 1. [Item X] -9,800 visits (-41%) 2. [Item Y] -4,200 visits (-18%) 3. [Item Z] -2,900 visits (-12%) Key takeaway: [1 sentence explanation of the story] ``` --- ## Guardrails - Always apply a materiality threshold to suppress noise from items with negligible volume. - Flag new items (no prior period) and disappeared items (no current period) explicitly — they often tell a significant story. - For percent-change ranking, use absolute delta (not percent) as primary sort to avoid surfacing low-volume items with misleading large percentages. - Cap dimension list at 6 for call efficiency. Offer to run additional dimensions on request. --- ## Example Interaction > "What pages were up and down the most last week?" 1. Confirm report suite. 2. Confirm metric: page views. Dimension: page name. Period: last 7 days vs prior 7 days. Limit: top 10 each. 3. Run 2 reports for page × visits. 4. Compute deltas, apply materiality (min 500 page views in either period). 5. Generate HTML report and deliver inline summary. 6. "Top gainer: /products/new-feature with +18,200 page views (+312%). Top loser: /promo/expired-campaign with -9,400 page views (-88%)."