cja-executive-briefing

What this skill does

# Executive Briefing (Customer Journey Analytics)

Produce a polished, leadership-ready performance document. Executives do not
read data tables — they read narratives that answer "are we growing?", "what
changed?", and "what do we do about it?"

This skill converts CJA data into a briefing that a VP or C-suite leader can
read in under 3 minutes, with supporting data available for those who want to
dig deeper.

Tone: business impact, not technical metrics. Write "Revenue grew 12% driven by
a strong Paid Search week" not "metrics/revenue increased by 0.12 per metrics/sessions."

---

## CJA MCP Tools Used

- `describeCja(DATAVIEW_CONTEXT_GUIDE)` — understand the business context of the data view
- `listComponentUsage` — identify the north-star and supporting KPIs
- `findMetrics` — resolve user-specified or discovered metric IDs
- `findCalculatedMetrics` — include custom business KPIs
- `runReport` — pull KPI values for current and comparison period
- `searchDimensionItems` — identify top driver dimension values

---

## 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. Confirm the reporting period (default: last 7 days) and the audience for the briefing (executive, board, team lead).

---

## Phase 1 — Establish Context

### 1.1 Load data view context

Call `describeCja("DATAVIEW_CONTEXT_GUIDE")` to understand:
- What business the data view represents (e-commerce, media, SaaS, etc.)
- The primary conversion event and revenue metric
- **Calendar conventions and timezone.** Record these values — they are
  inputs to every date computation in 1.2:
  - `WEEK_START_DOW` — day of week each week starts on (Sunday, Monday, …).
    Default: **Monday** (ISO 8601) if the context guide doesn't specify.
  - `FISCAL_YEAR_START_MONTH` — month the fiscal year begins. Default:
    **January** (calendar year) if the context guide doesn't specify.
  - `TIMEZONE` — for example, `America/Los_Angeles`.
  - `CALENDAR_SOURCE` — one of `"context guide"` (values came from `describeCja`),
    `"default fallback"` (the context guide didn't expose them and you used the
    defaults above), or `"user override"` (the user explicitly specified them).

This context determines what counts as the "north-star metric" and what
language to use in the narrative (e.g., "subscribers" vs "customers" vs "users").

### 1.2 Determine reporting period

Infer the period type from the user's request. Do not stop to ask — proceed immediately.

#### The principle

Two runs of this skill on the same data view, period type, and prompt MUST
produce identical `current` and `comparison` date ranges. Determinism comes
from (a) reading calendar conventions from 1.1 instead of improvising, and
(b) applying the alignment rule for the period type without taste calls.

#### Period type → alignment rule

Pick exactly one period type from the user's request:

| User request | `PERIOD_TYPE` | Current period | Comparison period |
|---|---|---|---|
| "last week" / unspecified | `weekly` | Most recent full week ending before today, aligned to `WEEK_START_DOW` (exactly 7 days) | The week immediately before, same alignment |
| "this month" / "MTD" | `month-to-date` | 1st of current month → today | 1st of prior month → same day-of-month as today |
| "last month" | `monthly` | Prior full calendar month (1st → last day) | The month before that |
| "this quarter" / "QTD" | `quarter-to-date` | Start of current fiscal quarter → today; fiscal quarters derived from `FISCAL_YEAR_START_MONTH` | Same days into the prior fiscal quarter |
| "last quarter" / "Q[N]" | `quarterly` | Prior full fiscal quarter | The fiscal quarter before that |
| Custom date range | `custom` | Use as specified | Equal-length window ending the day before `current.startDate` |

#### Universal invariants (must hold for every period type)

Before calling `runReport`, verify all six:

1. `current.startDate < current.endDate`
2. `comparison.startDate < comparison.endDate`
3. `comparison.endDate < current.startDate` (no overlap)
4. The day after `comparison.endDate` equals `current.startDate` (contiguous)
5. `current` and `comparison` have the **same length in days**
6. The alignment rule for `PERIOD_TYPE` is satisfied:
   - `weekly`: both `startDate`s fall on `WEEK_START_DOW`
   - `monthly`: both `startDate`s fall on the 1st of a month
   - `month-to-date`: both `startDate`s fall on the 1st; both `endDate`s have the same day-of-month
   - `quarterly`: both `startDate`s fall on the first day of a fiscal quarter
   - `quarter-to-date`: both `startDate`s fall on a fiscal quarter start; both `endDate`s are the same number of days into the quarter
   - `custom`: lengths match; contiguity holds

If ANY invariant fails, recompute the dates. **Never** paper over a mismatch by editing the footer.

#### Worked examples — today is Tuesday, May 26, 2026

These examples assume the data view's context guide returns `WEEK_START_DOW = Sunday` and `FISCAL_YEAR_START_MONTH = January`. Numbers change for other calendars — that's exactly the point.

| User request | `PERIOD_TYPE` | Current | Comparison |
|---|---|---|---|
| "last week" | `weekly` | May 17 (Sun) – May 23 (Sat) | May 10 (Sun) – May 16 (Sat) |
| "this month" / "MTD" | `month-to-date` | May 1 – May 26 | Apr 1 – Apr 26 |
| "last month" | `monthly` | Apr 1 – Apr 30 | Mar 1 – Mar 31 |
| "this quarter" / "QTD" | `quarter-to-date` | Apr 1 – May 26 | Jan 1 – Feb 24 |
| "last quarter" | `quarterly` | Jan 1 – Mar 31 | Oct 1 – Dec 31 (2025) |
| Custom: "May 15–22" | `custom` | May 15 – May 22 (8 days) | May 7 – May 14 (8 days) |

If `WEEK_START_DOW = Monday` instead, the weekly row becomes `May 18 (Mon) – May 24 (Sun)` vs `May 11 (Mon) – May 17 (Sun)`. The other rows are unchanged.

#### A common AI failure mode

The AI may "know" from training data that weeks are Mon–Sun (ISO 8601) or that
quarters are Q1=Jan–Mar (calendar). Silently overriding the context guide with
those defaults is exactly the determinism bug this section exists to prevent.
The footer's methodology line MUST accurately describe the dates you computed
— if footer says "weeks start Sunday" but `current.startDate` is a Monday,
that's a bug to fix in the dates, not in the footer.

### 1.3 Audience assumption

Default to **internal leadership** (VPs, directors, senior managers). This means:
- Include specific dimension values (e.g., channel names) in the narrative
- Surface both positive and negative findings with equal directness
- The reader understands your business — no need to define basic terms

If the user says "external," "board," or "investors," shift to higher-level
business outcomes, remove any internal channel naming that could be sensitive,
and lead with the most positive finding.

---

## Phase 2 — Discover North-Star Metrics

Pull the most-used metrics to identify what the org actually tracks as success.
Run both calls in parallel — this is fast and sets the foundation for every KPI
decision downstream:

```
listComponentUsage(componentType: "metric")
listComponentUsage(componentType: "calculatedMetric")
```

### Deterministic selection — do not improvise

The KPI set MUST be reproducible across runs for the same data view. Two runs of
this skill on the same period must produce the same metric values, which requires
selecting the **same metric IDs** every time. Follow this algorithm exactly:

1. Combine both `listComponentUsage` results into a single ranked list.
2. Sort by `usageCount` descending. Break ties by metric ID alphabetically
   (stable secondary sort).
3. Resolve metric IDs to human-readable display names with `describeMetric` or
   `describeCalculatedMetric`.
4. Take the top **6 metric IDs** from this sorted list. That is the KPI set.

Do NOT cherry-pick by metric "type" (volume vs conversion vs revenue) and do NOT
swap in an alternative metric because its name read