--- 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: "", startDate: "", endDate: "", 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 "" 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: "", endDate: "", 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": "" } } }] ) ``` 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: Segment the Funnel If the user wants to compare funnel performance across audiences or channels, run the same step reports filtered by a dimension or segment: ``` runReport( dimensionIds: "variables/device_type", metricIds: "metrics/visitors", startDate: "", endDate: "", page: 0, limit: 10, adhocSegments: [{ /* step N filter — same structure as Phase 2 */ }] ) ``` Note: use `findDimensions` with `searchQuery: "device type mobile desktop"` to confirm the device dimension ID for the data view (often `variables/device_type`). This shows step-N visitor counts broken down by device type (or channel, or country). If one segment has a dramatically lower conversion through the worst step, that's the target for optimization. Common comparisons to suggest: - Device type (mobile vs desktop conversion often differs significantly) - Marketing channel (paid vs organic users may convert differently) - New vs returning visitors --- ## Phase 5 — Generate HTML Funnel Report Generate the funnel report inline and write to `/tmp/cja_funnel_health_check_report_.html`. ### HTML Template ```html Funnel Health Check — {ORG_NAME} — {FUNNEL_NAME}

Funnel Health Report

{ORG_NAME} Funnel Health

Step-by-step conversion for the {FUNNEL_NAME} journey across {DATE_RANGE}, with the biggest leakage point surfaced.

📅 {DATE_RANGE} 📊 {DATA_VIEW} 🕔 Prepared {GENERATED_DATE}

Funnel Summary

Entered Funnel

{STEP_1_COUNT}

Step 1 visitors

Completed Funnel

{STEP_N_COUNT}

Reached final step

Overall Conversion

{OVERALL_CVR}%

End-to-end rate

Biggest Drop-Off Step

{WORST_STEP_NAME}

▼ Worst leakage

Worst Step Drop-Off

{WORST_STEP_DROPOFF}%

Of visitors lost at this step

Funnel Visualization

Step-by-Step Analysis

▾

Step	Visitors	% of Step 1	Step Conversion	Drop-Off	Drop-Off Rate	Visual

Segment Breakdown at Worst Step

▾

Segment / Dimension	Entered Worst Step	Passed Worst Step	Conversion	vs. Average

Optimization Recommendations

▾

``` --- ## Workflow Summary 1. Parse funnel steps from user description. 2. Clarify any ambiguous steps (one question at a time). 3. Resolve page names with `searchDimensionItems`. 4. Run one `runReport` per step with ad hoc segment filter; capture visitor counts. 5. Compute step conversion rates, drop-off counts, and rates. 6. Identify the biggest drop-off step. 7. Optionally run dimension breakdown at the worst step. 8. Generate HTML report with Chart.js funnel visualization. 9. Write to `/tmp/cja_funnel_health_check_report_.html`. 10. Open with `open /tmp/cja_funnel_health_check_report_.html`. 11. Summarize inline: "Overall conversion: X%. Biggest drop-off at [Step N]: Y% of users abandon. Mobile users drop off at a 2× higher rate than desktop." --- ## Important Guardrails - **Read-only analysis.** Never modify segments, calculated metrics, or project definitions automatically. - **Confirm funnel stages before running.** Ambiguous stage definitions produce misleading results — clarify with the user first. - **Note attribution model.** Funnel conversion rates depend on the attribution model in the data view; mention it in the report. - **Flag incomplete data.** If any stage returns zero or suspiciously low counts, note possible tracking gaps before drawing conclusions. - **Cap date range.** Funnel analysis over very long date ranges (>90 days) can be slow; suggest 30-day windows as default. - **Never assume stage order.** Confirm with the user that the stages are sequential and mutually exclusive before calculating drop-off rates. ## Example Interaction > "Check the health of our checkout funnel — I want to see where people are dropping off." 1. **Setup:** Call `findDataViews`, user selects their e-commerce data view. Call `setDefaultSessionDataViewId`. 2. **Define funnel:** Ask "What are the checkout stages?" User replies: "Product View → Add to Cart → Checkout Start → Purchase." 3. **Analysis:** Run `runReport` for each stage transition over the last 30 days. Calculate drop-off rates: Product View→Cart 22%, Cart→Checkout 58%, Checkout→Purchase 71%. 4. **Findings:** Identify the Cart→Checkout step as the highest drop-off (78% fall off). Segment by device type to find mobile conversion is 40% lower than desktop. 5. **Report:** Present a funnel visualization with drop-off rates per stage, top exit segments, and 3 prioritized recommendations. ## Recommendations Logic - **Worst step drop-off > 60%**: "Critical leakage — this step is broken or the user expectation is misaligned. Prioritize UX investigation." - **Mobile drop-off > 2× desktop**: "Mobile UX at this step needs attention — consider a dedicated mobile flow or simplified form." - **Specific channel drop-off > 40% worse than average**: "Users from this channel may have mismatched intent — review landing page alignment." - **Step 1 count < 1,000**: "Funnel entry volume is too low for statistical confidence. Check the step definition or expand the date range."