# Aa Top Movers Watchlist > Identifies which dimension items (pages, campaigns, products, channels, regions) had the biggest increases or decreases for a key metric between two time periods. - Skill: `adobe/aa-top-movers-watchlist` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add adobe/aa-top-movers-watchlist` - Raw SKILL.md: https://api.skillmd.com/api/skills/adobe/aa-top-movers-watchlist/raw - Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Data & Analytics, Marketing & Growth, Data Analysis - Tags: Adobe Analytics, Gainers, Kpi, Losers, Movers, Reporting, Trend Analysis - License: Apache-2.0 - Author: Adobe (https://skillmd.com/u/adobe), verified publisher - Updated: 2026-07-06 - Page: https://skillmd.com/skills/adobe/aa-top-movers-watchlist --- # 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%)."