/cja-funnel-health-check

name: cja-funnel-health-check
description: >
  Analyzes a multi-step conversion funnel to find where users drop off and which
  steps have the worst leakage. Use this skill when someone describes a journey
  or funnel and asks about conversion rates, drop-off, fallout, or step completion.
  Trigger for phrases like "analyze our onboarding funnel," "where are users
  dropping off," "what's our checkout conversion rate," "funnel analysis,"
  "show me fallout between these steps," or "which step loses the most users."
license: Apache-2.0
metadata:
  author: Adobe
  version: "1.0"

Funnel Health Check (Customer Journey Analytics)

Turn a plain-English funnel description into a quantified step-by-step conversion analysis. The output identifies the biggest leakage point in the funnel and provides dimension-based breakdowns to show which audience or channel has the worst drop-off.

Funnel health checks are most valuable when a team suspects a specific step is broken but hasn't quantified it. This skill does the quantification in a single conversation turn.

---

CJA MCP Tools Used

• `findDimensions` — resolve page name, event, or other dimensions for step filtering
• `findMetrics` — get the base metric to measure (sessions, visitors, events)
• `searchDimensionItems` — find exact dimension values for step names
• `runReport` (with `adhocSegments`) — measure visitor counts at each funnel step
• `findSegments` — use existing segments as funnel step filters if applicable
• `describeSegment` — understand segment logic before applying as a funnel step

---

Phase 0 — Setup

1. Call `findDataViews` to list available data views. 2. If the user hasn't specified a data view, present the list and ask which to use. 3. Call `setDefaultSessionDataViewId` with the chosen ID. 4. Ask the user to define the funnel stages if not already specified (e.g., "What are the steps in the funnel you want to analyze?").

Phase 1 — Define Funnel Steps

1.1 Parse the user's funnel description

Extract the step sequence from the user's plain-English description:

• "Homepage → Product Page → Cart → Purchase"
• "Registration → Onboarding Step 1 → Onboarding Step 2 → Activated"
• "Landing Page → Lead Form → Thank You Page"

Each step must resolve to a measurable condition in CJA. A step can be:

• **Page view**: user viewed a specific page (resolved via page name dimension)
• **Event/metric**: user triggered a specific action (e.g., "Added to Cart")
• **Segment membership**: user meets a pre-built segment condition

1.2 Clarify ambiguous steps

If any step is vague (e.g., "checkout" without a page name), ask one question: > "For the 'Checkout' step — should I look at people who visited a page > containing 'checkout' in the URL, or those who triggered a specific event > like 'Cart Add'?"

Do not ask more than one clarifying question at a time.

1.3 Resolve page names to dimension values

For page-based steps, call `searchDimensionItems` to find the exact dimension values that match the step name. First call `findDimensions` with a semantic search like `"page name url"` to confirm the correct dimension ID — in most CJA data views this is `variables/web.webPageDetails.name`, not `variables/page`:

searchDimensionItems(
  dimensionId: "variables/web.webPageDetails.name",
  searchAnd: "<step page name>",
  startDate: "<period start>",
  endDate: "<period end>",
  page: 0,
  limit: 10
)

Present matches to the user if there are multiple candidates: > "I found these pages matching 'checkout': /checkout/start, /checkout/payment, > /checkout/review. Should I use '/checkout/start' as the entry to the checkout > step?"

---

Phase 2 — Measure Each Step

For each funnel step, construct an ad hoc segment that filters to visitors/sessions that reached that step. Then run a report measuring the base metric (usually Unique Visitors or Sessions) with that segment applied.

2.1 Construct ad hoc segments for each step

A "reached step N" ad hoc segment is:

• Container: Visit or Person (use Visit for session-level funnels, Person for

cross-visit journeys)

• Condition: Page Name equals "<step page value>" OR Event occurred

2.2 Run reports for each step

Run one `runReport` per step with the ad hoc segment applied. The `adhocSegments` parameter takes fully-formed CJA segment definition objects — NOT a simplified shorthand. The correct structure is:

runReport(
  dimensionIds: "variables/web.webPageDetails.name",
  metricIds: "metrics/visitors",
  startDate: "<period start>",
  endDate: "<period end>",
  page: 0,
  limit: 1,
  adhocSegments: [{
    "func": "segment",
    "version": [1, 0, 0],
    "container": {
      "func": "container",
      "context": "visitors",
      "pred": {
        "func": "streq",
        "val": { "func": "attr", "name": "variables/web.webPageDetails.name" },
        "str": "<step page value>"
      }
    }
  }]
)

Use `context: "visitors"` (person-level) for cross-visit funnels. Use `context: "visits"` (session-level) for within-session funnels. The metric value comes from `summaryData.filteredTotals[0]` in the response.

The dimension and value used in the predicate should match what was found via `searchDimensionItems` in Phase 1 — use the exact `value` string returned.

**Important**: Each step uses a cumulative filter — measure "visitors who EVER reached this step in the period," not "visitors who ONLY visited this page." This produces the classic funnel waterfall.

Capture `stepCount[i]` for each step i from 1 to N.

---

Phase 3 — Compute Funnel Metrics

For each step-to-step transition:

• `stepConversionRate[i→i+1]` = stepCount[i+1] / stepCount[i] × 100
• `dropOff[i→i+1]` = stepCount[i] − stepCount[i+1]
• `dropOffRate[i→i+1]` = 100 − stepConversionRate[i→i+1]

Overall funnel:

• `overallConversionRate` = stepCount[N] / stepCount[1] × 100
• `biggestDropOffStep` = argmax(dropOff[i→i+1]) — the step with the most

visitors lost

---

Phase 4 — Optional: Se