cja-funnel-health-check

What this skill does

# 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: 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: "<range start>",
  endDate: "<range end>",
  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_<YYYY-MM-DD_HHMMSS>.html`.


### HTML Template

```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Funnel Health Check &mdash; {ORG_NAME} &mdash; {FUNNEL_NAME}</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Playfair+Display:wght@700;900&family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/chart.umd.min.js"></script>
<style>
  * { box-sizing: border-box; margin: 0; padding: 0; }
  :root {
    --bg: #f5f4f1;
    --surface: #ffffff;
    --ink: #1a1a1a;
    --ink-muted: #6b6b6b;
    --border: #e5e2dc;
    --header-bg: #0e0e10;
    --header-warm: #3a1010;
    --accent-red: #c8312f;
    --accent-red-bright: #ff6b68;
    --accent-red-soft: #fdecea;
    --accent-green: #1f7a4d;
    --accent-yellow: #d4a017;
  }
  body { font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
         background: var(--bg); color: var(--ink); line-height: 1.5;
         -webkit-font-smoothing: antialiased; }

  /* === Header === */
  header { background: linear-gradient(120deg, var(--header-bg) 0%, #1a0d0d 55%, var(--header-warm) 100%);
           color: #fff; padding: 56px 56px 44px; position: relative; overflow: hidden; }
  header::after { content: ""; position: absolute; right: -140px; top: -140px;
                  width: 460p