aa-top-movers-watchlist

What this skill does

# 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: "<gcid>")
setSessionDefaults(globalCompanyId: "<gcid>", reportSuiteId: "<rsid>")
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: "<metricId>",
  dimensionId: "<dimensionId>",
  startDate: "<period A start>T00:00",
  endDate: "<period A end>T23:59",
  limit: 200
)

runReport(
  metricIds: "<metricId>",
  dimensionId: "<dimensionId>",
  startDate: "<period B start>T00:00",
  endDate: "<period B end>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: "<metricId>", dimensionId: "variables/marketingchannel",
          startDate: "<A>T00:00", endDate: "<A>T23:59", ...)
runReport(metricIds: "<metricId>", dimensionId: "variables/page",
          startDate: "<A>T00:00", endDate: "<A>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_<YYYY-MM-DD_HHMMSS>.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