Update to Adobe CJA

{
  "description": "Compares the performance of two or more audience segments across key metrics side by side. Use this skill when someone wants to compare audiences, cohorts, or groups — for example, \"how do mobile users compare to desktop users on conversion,\" \"compare new vs. returning visitors,\" \"show me the difference between these two segments,\" \"compare these audiences on our KPIs,\" or \"which segment performs better.\" Also trigger for \"segment comparison,\" \"audience comparison,\" or \"cohort comparison.\"\n",
  "included_files": [
    {
      "relative_path": "evals/evals.json",
      "size_in_bytes": 2763
    },
    {
      "relative_path": "template.html",
      "size_in_bytes": 12445
    }
  ],
  "name": "cja-segment-performance-comparator",
  "skill_md_contents": "---\nname: cja-segment-performance-comparator\ndescription: >\n  Compares the performance of two or more audience segments across key metrics\n  side by side. Use this skill when someone wants to compare audiences, cohorts,\n  or groups — for example, \"how do mobile users compare to desktop users on\n  conversion,\" \"compare new vs. returning visitors,\" \"show me the difference\n  between these two segments,\" \"compare these audiences on our KPIs,\" or\n  \"which segment performs better.\" Also trigger for \"segment comparison,\"\n  \"audience comparison,\" or \"cohort comparison.\"\nlicense: Apache-2.0\nmetadata:\n  author: Adobe\n  version: \"1.0\"\n---\n\n# Segment Performance Comparator (Customer Journey Analytics)\n\nCompare 2–5 audience segments across a set of key metrics in a side-by-side\nmatrix. The output tells the user not just what each segment looks like in\nisolation, but which segment wins or loses on each metric — and which\ndifferences are large enough to act on.\n\nThis skill answers the question \"which audience should we focus on?\" with data.\nSegment comparisons drive product decisions, personalization strategy, and\nbudget allocation — so clarity and actionability matter more than exhaustive data.\n\n---\n\n## CJA MCP Tools Used\n\n- `findSegments` — search for segments by name or keyword\n- `describeSegment` — understand the logic of candidate segments before using them\n- `findMetrics` — resolve base metric IDs\n- `findCalculatedMetrics` — include custom KPIs in the comparison\n- `listComponentUsage` — identify the most-used metrics as default comparison set\n- `runReport` (with `segmentIds` or `adhocSegments`) — pull metric values per segment\n\n---\n\n## Phase 0 — Setup\n\n1. Call `findDataViews` to list available data views.\n2. If the user hasn't specified a data view, present the list and ask which to use.\n3. Call `setDefaultSessionDataViewId` with the chosen ID.\n4. Ask the user which segments to compare if not already specified. Confirm the metrics to compare them on.\n\n---\n\n## Phase 1 — Identify Segments to Compare\n\n### 1.1 From user description\n\nIf the user named specific segments, resolve them:\n```\nfindSegments(search: \"<segment name>\")\n```\n\nFor each match, call `describeSegment` to verify it is the correct one:\n```\ndescribeSegment(segmentId: \"<id>\")\n```\n\nShow the segment definition summary to the user if there is ambiguity:\n> \"I found two segments matching 'mobile users': **Mobile Visitors (All Devices)**\n> and **Mobile App Users**. Which do you want to compare?\"\n\n### 1.2 From plain-English descriptions\n\nIf the user says \"compare mobile vs desktop users\" but there are no matching\nsegments, offer to create ad hoc segments inline for the comparison:\n> \"I don't see pre-built segments for mobile and desktop. I can create\n> temporary ad hoc segments for this comparison using device type. Should I\n> proceed with ad hoc segments, or would you like to create permanent segments\n> first?\"\n\nAd hoc segments are constructed using `adhocSegments` in `runReport` — no\nsave required for the comparison itself.\n\n### 1.3 Segment count limit\n\nMaximum 5 segments for a single comparison. More than 5 creates a matrix\nthat is too wide to read meaningfully. If the user requests more, say:\n> \"I'll limit to the 5 most relevant segments for readability. Would you like\n> me to prioritize by usage count or stick with your list order?\"\n\n---\n\n## Phase 2 — Identify Metrics to Compare\n\n### 2.1 From user specification\n\nResolve named metrics via `findMetrics` and `findCalculatedMetrics`.\n\n### 2.2 Default metric discovery\n\nIf the user did not specify metrics, pull the top metrics by usage. The\n`listComponentUsage` tool does not support a `limit` parameter — it returns all\ncomponents ranked by usage count; take the top 6–8 from the result:\n```\nlistComponentUsage(componentType: \"metric\")\nlistComponentUsage(componentType: \"calculatedMetric\")\n```\n\nPrefer calculated metrics over raw base metrics when they measure the same\nthing — calculated metrics reflect intentional KPI definitions.\n\n### 2.3 Metric selection for a comparison\n\nGood comparison metrics should be meaningful across all segments. For example,\n\"Revenue\" is meaningful for both mobile and desktop users; \"App Installs\" is\nonly meaningful for mobile. Remove metrics that would be trivially zero for\none segment.\n\nIf unsure, ask: \"Should I use your standard KPI set, or focus on specific\nmetrics like conversion rate, revenue, and engagement?\"\n\n---\n\n## Phase 3 — Run the Comparison\n\nFor each segment, run a `runReport` with that segment applied and all\ncomparison metrics included. Note that `runReport` takes `metricIds` as a\ncomma-separated string, `startDate`/`endDate` (not `dateRange`), and a\n`dimensionIds` (required even for summary-only reports — use a low-cardinality\ndimension like `variables/daterangeday` or `variables/web.webPageDetails.name`).\nThe summary totals for all metrics are in `summaryData.filteredTotals`:\n\n```\nrunReport(\n  dimensionIds: \"variables/web.webPageDetails.name\",\n  metricIds: \"metrics/visits,metrics/revenue_1,metrics/orders_1_1\",\n  startDate: \"<period start>T00:00:00\",\n  endDate: \"<period end>T23:59:59\",\n  page: 0,\n  limit: 1,\n  segmentIds: \"<segment id>\"\n)\n```\n\nFor ad hoc segments, use the full CJA segment definition object:\n```\nrunReport(\n  dimensionIds: \"variables/web.webPageDetails.name\",\n  metricIds: \"metrics/visits,metrics/orders_1_1\",\n  startDate: \"<period start>T00:00:00\",\n  endDate: \"<period end>T23:59:59\",\n  page: 0,\n  limit: 1,\n  adhocSegments: [{\n    \"func\": \"segment\",\n    \"version\": [1, 0, 0],\n    \"container\": {\n      \"func\": \"container\",\n      \"context\": \"visitors\",\n      \"pred\": {\n        \"func\": \"streq\",\n        \"val\": { \"func\": \"attr\", \"name\": \"variables/device_type\" },\n        \"str\": \"Mobile Phone\"\n      }\n    }\n  }]\n)\n```\n\nRead metric totals from `summaryData.filteredTotals[i]` where `i` is the\n0-based index of the metric in the `metricIds` string.\n\nRun one report per segment. Collect all results into a matrix:\n- Rows = metrics\n- Columns = segments\n\n---\n\n## Phase 4 — Build the Comparison Matrix\n\nFor each cell (metric × segment):\n- `value[metric][segment]` = raw metric value from `runReport`\n\nFor each metric row:\n- `winner` = segment with the highest value (or lowest, for \"lower is better\" metrics)\n- `loser`  = segment with the lowest value (or highest, for inverse metrics)\n- `range`  = (max − min) / max × 100 — the spread across segments as a percentage\n- `significant` = true if range > 10% (a meaningful difference worth acting on)\n\n---\n\n## Phase 5 — Generate HTML Comparison Report\n\nGenerate the report inline and write to\n`/tmp/cja_segment_performance_comparator_report_<YYYY-MM-DD_HHMMSS>.html`.\n\n\n### HTML Template\n\nRead [`template.html`](template.html) and use it verbatim. Do not improvise the\nHTML structure or CSS — only fill in the `{PLACEHOLDER}` tokens (`{ORG_NAME}`,\n`{DATE_RANGE}`, `{DATA_VIEW}`, `{GENERATED_DATE}`, `{SEGMENT_NAMES_SUMMARY}`,\n`{SEGMENT_NAME}`, `{COLOR}`, `{VISITOR_COUNT}`, `{NUM_SEGMENTS}`, `{NUM_METRICS}`,\n`{NUM_SIGNIFICANT}`, `{OVERALL_WINNER}`, `{METRIC_NAME}`, `{VALUE}`,\n`{WINNER_SEGMENT}`, `{SPREAD}`, `{INSIGHT_TEXT}`) and repeat segment chips,\nmatrix rows, and insight boxes once per data item. Use the `cell-winner` /\n`cell-loser` classes per Phase 4 winner/loser rules.\n\n---\n\n## Phase 6 — Narrative Insights\n\nAfter building the matrix, generate 3–5 insight bullets for the Insights section:\n\n1. **Overall Winner**: \"Returning Visitors outperform New Visitors on 5 of 7\n   metrics, with the largest gap in Revenue per Session (+82%).\"\n2. **Most Significant Difference**: \"The biggest gap is Conversion Rate: Mobile\n   converts at 1.2% vs Desktop at 3.8% — a 68% gap worth prioritizing.\"\n3. **Surprising Parity**: \"New vs Returning Visitors show nearly identical\n   Bounce Rates (42% vs 44%), suggesting landing page quality is consistent.\"\n4. **Actionable Signal**: \"Paid Search visitors have 2.3× higher Revenue per\n   Session than Direct visitors — consider shifting budget toward Paid Search.\"\n5. **Anomaly**: \"One segment shows near-zero values across all metrics — verify\n   that the segment definition is correct and matches the current data view.\"\n\nInsights should be plain English, not metric IDs. Name the specific segments\nand metric values.\n\n---\n\n## Workflow Summary\n\n1. Resolve 2–5 segments (by name or ad hoc definition).\n2. Identify 5–8 comparison metrics (from user or top usage).\n3. Run one `runReport` per segment with all metrics; collect results.\n4. Build comparison matrix: rows = metrics, columns = segments.\n5. Mark winner/loser per row; compute spread; flag significant differences.\n6. Generate HTML report with matrix and insight bullets.\n7. Write to `/tmp/cja_segment_performance_comparator_report_<YYYY-MM-DD_HHMMSS>.html`.\n8. Open with `open /tmp/cja_segment_performance_comparator_report_<YYYY-MM-DD_HHMMSS>.html`.\n9. Deliver inline summary: which segment wins overall, biggest gap metric,\n   one actionable recommendation.\n\n---\n\n## Important Guardrails\n\n- **Read-only analysis.** Never delete or modify segments or calculated metrics.\n- **Always confirm segments before running.** Ambiguous segment names (e.g., \"Mobile\" could be several) should be resolved by showing the user the matched segment IDs and definitions.\n- **Use the same date range for all segments.** Comparisons across different time windows are misleading.\n- **Note overlap between segments.** If two segments share substantial audience overlap, note it — the \"difference\" may be exaggerated.\n- **Cap the number of segments compared.** Comparing more than 5–6 segments in a single report makes the output unreadable; ask the user to prioritize.\n- **Distinguish statistical significance from practical significance.** A 0.1% difference is rarely actionable — focus on differences of 5%+ unless the user specifies otherwise.\n\n---\n\n## Example Interaction\n\n> \"Compare our mobile vs. desktop segment performance for last quarter.\"\n\n1. **Setup:** Confirm data view. Call `findDataViews`, user selects. Call `setDefaultSessionDataViewId`.\n2. **Segment resolution:** Call `findSegments` to locate the \"Mobile Users\" and \"Desktop Users\" segments. Show matched names and IDs to confirm. User approves.\n3. **Metrics:** Ask \"Which metrics should I compare?\" User: \"Sessions, Conversion Rate, Revenue, and Average Order Value.\"\n4. **Analysis:** Run `runReport` for Q1 2026 with both segments applied. Tabulate results side-by-side.\n5. **Findings:** Mobile: 45% of sessions, 2.1% CVR, $0.84 RPV. Desktop: 55% of sessions, 4.8% CVR, $2.10 RPV. Desktop converts 2.3× better. Present a comparison table and 3 recommended next steps.\n"
}