{"id":8693,"plugin_id":"plugin_asdk_app_6a3ed08a777481919fe5c4b0c1bb9171","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T22:53:17.836Z","digest":"c3c6f04a450ca1196d5b59298525a575346136d46d7efb1d7b134683bd713873","against":null,"payload":{"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.\n","included_files":[{"relative_path":"evals/evals.json","size_in_bytes":1972}],"skill_md_contents":"---\nname: cja-top-movers-watchlist\ndescription: >\n Identifies which items (pages, campaigns, products, channels, regions) had the\n biggest increases or decreases for a key metric between two time periods. Use\n this skill when someone asks \"what's up and what's down,\" \"which campaigns\n moved the most,\" \"top gainers and losers,\" \"what pages are trending,\" \"show me\n what changed by channel,\" or any variation of identifying the biggest movers\n and decliners for a metric.\nlicense: Apache-2.0\nmetadata:\n author: Adobe\n version: \"1.0\"\n---\n\n# Top Movers Watchlist (Customer Journey Analytics)\n\nSurface the biggest gainers and decliners for a metric across any dimension in\ntwo time periods. The output tells the user exactly what moved, by how much, and\nwhether items appeared or disappeared entirely — which is often the most\ninteresting signal.\n\nThis skill is a faster, more targeted alternative to a full anomaly triage.\nUse it when the user wants to scan the landscape of changes rather than drill\ninto a single anomaly.\n\n---\n\n## CJA MCP Tools Used\n\n- `describeCja(DATAVIEW_CONTEXT_GUIDE)` — load data view calendar/timezone\n- `findMetrics` — resolve the metric being watched\n- `findCalculatedMetrics` — if the metric is a custom KPI\n- `findDimensions` — resolve the dimension to break down by\n- `runReport` — pull dimension-metric data for both periods\n- `searchDimensionItems` — validate dimension values if user specifies names\n\n---\n\n## Phase 0 — Setup\n\n1. Call `findDataViews` and `setDefaultSessionDataViewId` as needed.\n2. Call `describeCja(\"DATAVIEW_CONTEXT_GUIDE\")` to load data view context.\n Record the first-day-of-week as `WEEK_START_DOW` and timezone as\n `TIMEZONE`. If the context guide does not return a week-start value,\n default to **Monday** (ISO 8601). You will use both in Phase 1.3.\n\n---\n\n## Phase 1 — Clarify Inputs\n\n### 1.1 Metric\n\nIf the user specified a metric, resolve it:\n```\nfindMetrics(search: \"\")\n```\n\nIf not specified, suggest the top 3 metrics from usage:\n> \"Which metric would you like to track? I can suggest: Sessions, Revenue,\n> Orders based on what your team uses most.\"\n\n### 1.2 Dimension (what to break down by)\n\nCommon dimension choices and their typical use cases:\n\n| Dimension | Use Case |\n|--------------------|-----------------------------------------|\n| Marketing Channel | \"Which channels moved?\" |\n| Page Name | \"Which pages are trending?\" |\n| Campaign | \"Which campaigns improved?\" |\n| Product | \"Which products gained/lost traction?\" |\n| Country / Region | \"Which markets moved?\" |\n| Device Type | \"Did mobile or desktop shift?\" |\n| Referring Domain | \"Which referrers changed?\" |\n\nIf the user did not specify, ask:\n> \"Which dimension should I break down by — for example, marketing channel,\n> page, campaign, country, or product?\"\n\nCall `findDimensions(search: \"\")` to resolve the dimension ID.\n\n### 1.3 Periods\n\nDefine Period A (current) and Period B (comparison). Defaults:\n- **Period A**: this week (or last 7 days)\n- **Period B**: last week (or the 7 days before that)\n\nIf the user specifies \"this month vs last month\" or a custom range, map\naccordingly. Always confirm the periods before running reports:\n> \"I'll compare **this week (Mar 13–19)** vs **last week (Mar 6–12)**. Sound right?\"\n\n**Calendar rule (mandatory):**\n\nUse `WEEK_START_DOW` from Phase 0 to define what \"week\" means. Period A and\nPeriod B MUST use the same first-day-of-week — i.e., both periods'\n`startDate` fall on the same day-of-week, both are exactly equal length,\nand Period B ends immediately before Period A starts. Never mix conventions\n(e.g., a Mon–Sun Period A with a Sun–Sat Period B) within the same run.\nPick the boundary once, then derive both periods from it. For custom date\nranges, compute Period B as the equal-length window ending immediately\nbefore Period A starts.\n\n**Sanity check before calling `runReport`:** confirm `periodA.startDate`\nand `periodB.startDate` are the same day-of-week and that\n`periodA.startDate - periodB.endDate == 1 day`. If not, recompute.\n\n---\n\n## Phase 2 — Pull Data for Both Periods\n\nRun two reports — one per period — with the same dimension breakdown:\n\n```\nrunReport(\n dimensionIds: \"\",\n metricIds: \"\",\n startDate: \"T00:00:00\",\n endDate: \"T23:59:59\",\n page: 0,\n limit: 50\n)\n```\n\n```\nrunReport(\n dimensionIds: \"\",\n metricIds: \"\",\n startDate: \"T00:00:00\",\n endDate: \"T23:59:59\",\n page: 0,\n limit: 50\n)\n```\n\nUse `limit: 50` to capture enough items to surface meaningful movers.\nIf the user's dimension has thousands of values (e.g., page names), limit to\ntop 100 by Period A volume to keep the comparison meaningful.\n\nRow data is in the `rows` array — each row has `value` (dimension item name)\nand `data[0]` (the metric value). There is no limit on dimension cardinality\nbut results default to sorted by metric descending, which is what you want.\n\nAlways verify the dimension ID with `findDimensions(searchQuery: \"\")` \nbefore running — dimension IDs can vary from what you might guess \n(e.g., `variables/marketing_channel` not `variables/marketingchannel`).\n\n---\n\n## Phase 3 — Compute Rankings\n\nBuild a unified table joining both result sets on dimension value:\n\nFor each dimension value present in either period:\n- `valueA` = metric value in Period A (0 if not present)\n- `valueB` = metric value in Period B (0 if not present)\n- `delta` = valueA − valueB\n- `pctChange` = (delta / valueB) × 100 if valueB > 0, else \"New Entry\"\n- `status`:\n - Present in A but not B → **New Entry** (appeared this period)\n - Present in B but not A → **Disappeared** (dropped out this period)\n - Both present → normal mover\n\nSort by:\n1. **Top Gainers**: sort by delta descending (biggest absolute gains first)\n2. **Top Decliners**: sort by delta ascending (biggest absolute drops first)\n3. **% Gainers**: sort by pctChange descending\n4. **% Decliners**: sort by pctChange ascending\n\nLimit each list to **Top 10**. New Entries and Disappeared items get their\nown sections regardless of count (they are always interesting signals).\n\n---\n\n## Phase 4 — Generate HTML Report\n\nGenerate the movers report inline and write to\n`/tmp/cja_top_movers_report_.html`.\n\n\n### Rendering rules — apply consistently across runs\n\nTwo runs of this skill on the same data view + metric/dimension + period must\nrender identically (modulo the generation timestamp). The rules below pin the\nformatting choices that the AI would otherwise drift on.\n\n#### Number formatting\n\n- **KPI values** (the big number in each summary tile, and per-row mover\n values) — use full digits with thousands separators (`8,160`, `77,584`,\n `1,250,000`). Do **NOT** use SI suffixes like `K` or `M`, even for large\n values. Stakeholders want exact numbers, not abbreviations.\n- **Percent change** (in pills and narrative bullets) — always one decimal\n place, rounded **half-away-from-zero**. For example, `−23.55%` displays as\n `−23.6%`, never `−23.5%`. Compute on full-precision values; round only at\n display time.\n- **Percentage-point change** (for already-percentage metrics like Conversion\n Rate or Bounce Rate) — same rounding, suffix `pp`. Example: `+0.40 pp`.\n- **Currency** — `$` prefix with thousands separators and no decimals for\n values ≥ $100 (`$1,240,000`); cents only when value < $100 (`$45.20`).\n\n#### Null / missing data handling\n\nA KPI tile or mover row must reflect what the data view actually returned.\nThe AI must **not** silently substitute a different metric or hide a tile to\nmake the report look cleaner.\n\n- **Both periods return 0 or NULL** for the tracked metric in a summary tile:\n render the tile with `kpi-value` = `Data unavailable`, pill class `flat`,\n pill text `⚠ N/A`, and `prior` text = `Both periods returned no data —\n validate instrumentation`. The tile stays in the grid; do not omit it.\n- **One period returns valid data, the other 0 / NULL**: render the tile with\n the valid value as `kpi-value`, pill class `flat`, pill text `⚠ N/A`, and\n `prior` text = `Prior {period_noun}: no data`.\n- **Never** substitute a different metric (e.g., switching from Revenue to\n Orders because Revenue came back $0). The metric being analyzed MUST be the\n metric rendered.\n\n\n### HTML Template\n\n```html\n\n\n\n\nTop Movers — {ORG_NAME} — {METRIC_NAME} by {DIMENSION_NAME}\n\n\n\n\n\n\n\n
\n
\n
Top Movers Report
\n

{ORG_NAME} Top Movers

\n

Biggest gainers and decliners for {METRIC_NAME} by {DIMENSION_NAME}, {PERIOD_A_LABEL} vs {PERIOD_B_LABEL}.

\n
\n 📅 {PERIOD_A_LABEL}\n 📊 {DATA_VIEW}\n 🕔 Prepared {GENERATED_DATE}\n
\n
\n
\n\n\n\n
\n\n \n
Watchlist Summary
\n
\n
\n
Total Items Compared
\n
{TOTAL_ITEMS}
\n Dimension values in scope\n
\n
\n
Biggest Gain
\n
{TOP_GAINER_VALUE}
\n ▲ {TOP_GAINER_NAME}\n
\n
\n
Biggest Drop
\n
{TOP_DECLINER_VALUE}
\n ▼ {TOP_DECLINER_NAME}\n
\n
\n
New Entries
\n
{NEW_ENTRIES}
\n Appeared this period\n
\n
\n
Disappeared
\n
{DISAPPEARED}
\n Dropped out this period\n
\n
\n\n \n
\n\n
\n
\n

▲ Top 10 Gainers

\n ▾\n
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n
Item{PERIOD_A_LABEL}{PERIOD_B_LABEL}Delta% Change
\n
\n
\n\n
\n
\n

▼ Top 10 Decliners

\n ▾\n
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n
Item{PERIOD_A_LABEL}{PERIOD_B_LABEL}Delta% Change
\n
\n
\n\n
\n\n \n
\n
\n

New Entries & Disappeared Items

\n ▾\n
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n
ItemStatus{PERIOD_A_LABEL}{PERIOD_B_LABEL}Notes
\n
\n
\n\n \n
\n
\n

Full Comparison Table

\n ▾\n
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n
Item{PERIOD_A_LABEL}{PERIOD_B_LABEL}Delta% ChangeStatus
\n
\n
\n\n
\n\n\n
Top Movers — {ORG_NAME} — Generated {GENERATED_DATE}
\n\n\n\n```\n\n---\n\n## Workflow Summary\n\n1. Confirm metric, dimension, and both time periods.\n2. Run `runReport` for Period A with dimension breakdown (limit 50).\n3. Run `runReport` for Period B with same parameters.\n4. Join on dimension value; compute delta, pctChange, and status.\n5. Sort into: Top 10 Gainers, Top 10 Decliners, New Entries, Disappeared.\n6. Generate HTML report inline, write to `/tmp/cja_top_movers_report_.html`.\n7. Open with `open /tmp/cja_top_movers_report_.html`.\n8. Deliver a 3-line inline summary: \"Top gainer: X (+Y%), Top decliner: Z (−W%).\n N new items entered the top 50; M items disappeared.\"\n\n---\n\n## Important Guardrails\n\n- **Read-only monitoring.** Never modify segments, metrics, or project definitions.\n- **Confirm metric and segment scope** before running. Vague requests (\"watch everything\") need narrowing — ask which dimensions and metrics matter most.\n- **Use consistent comparison windows.** \"Top movers\" must compare equal-length periods; mismatched windows produce false signals.\n- **Distinguish noise from signal.** Very low-traffic dimension values (e.g., a segment with 5 visits) can show 500% swings — apply a minimum threshold (e.g., at least 100 sessions) before flagging as a mover.\n- **Cap the watchlist size.** Surface the top 10–20 movers by default; overwhelming users with 100 dimension items defeats the purpose.\n- **Attribute changes to context.** When possible, note known business events (campaigns, releases, outages) that could explain movements.\n\n## Example Interaction\n\n> \"Which marketing channels moved the most last week vs the week before?\"\n\n1. Metric: Sessions (top usage default)\n2. Dimension: Marketing Channel\n3. Period A: last week, Period B: the week before\n4. Run both reports, join results\n5. Gainers: Paid Social +32%, Organic Search +8%\n6. Decliners: Email −18%, Direct −5%\n7. New: Affiliate (not in top 50 prior week)\n8. Generate and open report\n9. Inline summary: \"Paid Social drove the biggest gain (+32%). Email was\n the top decliner (−18%). Affiliate channel appeared for the first time\n in the top rankings.\"\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}