--- name: cja-executive-briefing description: > Generates a polished, leadership-ready performance briefing with KPI tiles, executive narrative bullets, and a driver analysis — all as a print-ready HTML document. Always use this skill when someone asks for an executive summary, performance briefing, leadership readout, stakeholder update, or business review — even if they don't say "executive" explicitly. Trigger phrases include: "write a summary of last week's performance," "create a briefing for our leadership team," "produce a monthly business review," "what should I tell executives about our metrics," "generate a performance narrative," "QBR summary," "weekly business review," "board update," "stakeholder briefing," "how did we do last week," or "give me a performance snapshot." When in doubt, use this skill — it is always better to produce a polished briefing than a raw data dump. license: Apache-2.0 metadata: author: Adobe version: "1.0" --- # 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 reads better in a narrative. Different runs picking `metrics/orders` vs `metrics/orders_1_1` produce wildly different numbers and break trust in the briefing. ### When the user specifies metrics explicitly If the user names metrics in their request ("give me a briefing on revenue, orders, and conversion rate"), resolve each name to **one** specific metric ID via `findMetrics`. If multiple metrics match a name (e.g., "Orders" matches both `metrics/orders` and a calculated metric called "Orders"), pick the one with the highest `usageCount` and document the choice. ### Always disclose the metric IDs used Include a small "Metrics included" line in the briefing artifact's footer listing the resolved metric IDs (e.g., `metrics/orders_1_1`, `metrics/visits`, `metrics/page_views`). This makes the report auditable and lets the user confirm a re-run is using the same metrics. Cap at 6 KPIs. More is noise. --- ## Phase 3 — Pull KPI Data Run both reports in parallel — current period and comparison period — with all selected metrics. Use a date dimension (e.g., `variables/daterangeday`) so the report returns summary totals across the full period. The `summaryData.totals` array in the response contains the aggregate values you need. ``` runReport( startDate: "T00:00:00", endDate: "T00:00:00", dimensionIds: "variables/daterangeday", metricIds: "metrics/visits,metrics/orders_1_1,metrics/revenue_1,...", page: 0, limit: 1 ) runReport( startDate: "T00:00:00", endDate: "T00:00:00", dimensionIds: "variables/daterangeday", metricIds: "metrics/visits,metrics/orders_1_1,metrics/revenue_1,...", page: 0, limit: 1 ) ``` Read `summaryData.filteredTotals` from each response — the values correspond to the metrics in the order they were specified in `metricIds`. Compute for each KPI: - `current` value - `prior` value - `delta` = current − prior - `pctChange` = delta / prior × 100 - `direction`: up / down / flat (using ±3% threshold) - `polarity`: positive if higher is better, negative if lower is better - `signal`: green (favorable), red (unfavorable), yellow (mixed/flat) --- ## Phase 4 — Find What Drove the Movement For the 2 KPIs with the largest absolute % change, find the top driver: Run current and prior period breakdown reports in parallel: ``` runReport( startDate: "", endDate: "", dimensionIds: "variables/marketing_channel", metricIds: "", limit: 5 ) runReport( startDate: "", endDate: "", dimensionIds: "variables/marketing_channel", metricIds: "", limit: 5 ) ``` Compare channel-level values between periods to find which dimension value's delta most closely mirrors the overall metric change. This becomes the "driven by" phrase in the narrative. Only run dimension breakdowns for the 2 most-moved metrics (by absolute % change). This constraint exists because: (a) more breakdowns add latency without adding executive value, and (b) the two largest movers are what leadership will ask about first. The remaining KPIs get context from the narrative without needing attribution. If `variables/marketing_channel` returns no useful breakdown (e.g., only one channel has data), try `variables/page_type` or `variables/product_category` as alternative driver dimensions. --- ## Phase 5 — Write the Executive Narrative Compose 3–5 bullet points as the narrative. Each bullet follows this structure: **[Signal emoji] [Metric]: [Value] ([+/-pctChange%] vs [prior period]) — [Plain-English context]** Guidelines: - Open with the most important finding (highest-impact metric, positive or negative) - Use business language: "revenue," "customers," "conversions" — not "metrics/revenue" - Name the driver when known: "driven by Paid Search," "led by Product Page improvements" - Include one forward-looking note if relevant: "This trend should be monitored..." - For negative trends: be direct but not alarming. Suggest investigation, not panic. Examples of well-written bullets: - "Revenue reached $1.24M last week, up 8.2% vs prior week — Paid Search drove the majority of the gain (+$82K)." - "Conversion Rate declined to 2.1% (−0.4pp), primarily on mobile. Desktop conversion remained stable at 3.4%." - "Sessions were flat at 540K (+1.1%) — organic and direct traffic offset a reduction in email campaign sends." - "Bounce Rate ticked up to 43% (+2pp). No single driver identified; worth monitoring through end of month." --- ## Phase 6 — Generate the HTML Briefing Document Generate the briefing inline. Write to `/tmp/cja_executive_briefing_.html`. This document should look polished enough to share with leadership — not a developer tool output. ### Rendering rules — apply consistently across runs Two runs of this skill on the same data view + period must render identically (modulo the generation timestamp). The rules below pin the formatting choices that the AI would otherwise drift on. #### Number formatting - **KPI values** (the big number in each tile) — use full digits with thousands separators (`8,160`, `77,584`, `1,250,000`). Do **NOT** use SI suffixes like `K` or `M`, even for large values. Executives want exact numbers, not abbreviations. - **Percent change** (in pills and narrative bullets) — always one decimal place, rounded **half-away-from-zero**. For example, `−23.55%` displays as `−23.6%`, never `−23.5%`. Compute on full-precision values; round only at display time. - **Percentage-point change** (for already-percentage metrics like Conversion Rate or Bounce Rate) — same rounding, suffix `pp`. Example: `+0.40 pp`. - **Currency** — `$` prefix with thousands separators and no decimals for values ≥ $100 (`$1,240,000`); cents only when value < $100 (`$45.20`). #### Null / missing data handling A KPI tile must reflect what the data view actually returned. The AI must **not** silently substitute a different metric or hide a tile to make the briefing look cleaner. - **Both periods return 0 or NULL** for a metric in the resolved set: render the tile with `kpi-value` = `Data unavailable`, pill class `flat`, pill text `⚠ N/A`, and `prior` text = `Both periods returned no data — validate instrumentation`. The tile stays in the grid; do not omit it. - **One period returns valid data, the other 0 / NULL**: render the tile with the valid value as `kpi-value`, pill class `flat`, pill text `⚠ N/A`, and `prior` text = `Prior {period_noun}: no data`. - **Never** substitute a derived metric (e.g., adding "Conversion Rate" because Revenue came back $0). The visible KPI set MUST match the resolved metric IDs disclosed in the footer. - If a Revenue / monetary metric is unavailable, surface a `.callout.note` above the KPI grid explaining the gap. Do not invent a value. ### Template variables Populate every `{PLACEHOLDER}` in the HTML template below using these rules. The briefing belongs to the customer — never substitute Adobe, CJA, or any vendor language into customer-visible fields. - **`{ORG_NAME}`** — The customer's business or brand name, derived from the data view context loaded in Phase 1.1. Strip technical/environment suffixes like ` — Prod`, ` - Demo`, ` Stage`, ` Test`, ` MCP`. If the data view name has no clean brand label, fall back to the data view display name with suffixes removed. Do **not** invent a name and do **not** substitute a vendor name. - **`{PERIOD_TYPE}`** — One of `Weekly`, `Monthly`, `Quarterly`, or `Performance` (default), chosen from the period inferred in Phase 1.2. - **`{LEDE_SENTENCE}`** — Use exactly this pattern, with no vendor names: `Leadership readout for the {period type lowercase} of {PERIOD_LABEL} compared to {COMPARISON_LABEL}.` Example: `Leadership readout for the week of May 12–18, 2026 compared to May 5–11, 2026.` - **`{DATA_VIEW}`** — Data view display name as returned by `findDataViews`. Suffixes are acceptable here — this row is the technical identifier line, not the title. - **`{PERIOD_LABEL}`** / **`{COMPARISON_LABEL}`** — Human-readable date ranges, e.g., `May 12–18, 2026`. - **`{GENERATED_DATE}`** — Today's date in the same human format, e.g., `May 23, 2026`. - **`{METRIC_LABEL}` / `{FORMATTED_VALUE}` / `{PCT_CHANGE}` / `{PRIOR_VALUE}`** — Per-KPI values from Phase 3. Use the metric's customer-facing display name, not its internal ID. ### HTML Template ```html Performance Briefing — {ORG_NAME} — {PERIOD}

{PERIOD_TYPE} Performance Briefing

{ORG_NAME} Performance

{LEDE_SENTENCE}

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

Key Performance Indicators

Executive Summary

Full KPI Detail

▾

Metric	{PERIOD_LABEL}	{COMPARISON_LABEL}	Change	% Change	Signal

What Drove the Movement

▾

Metric	Top Driver	Value This Period	Value Prior Period	Contribution

``` --- ## Phase 7 — Deliver the Briefing 1. Write the HTML to `/tmp/cja_executive_briefing_.html` 2. Open with `open /tmp/cja_executive_briefing_.html` 3. Output the narrative bullets directly in chat so the user can copy-paste them into an email or slide deck immediately — the HTML is the "appendix." In-chat format: ``` Performance Briefing — Last Week vs Prior Week ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📈 Revenue: $1.24M (+8.2%) — Paid Search drove the majority of the gain. 📉 Conversion Rate: 2.1% (−0.4pp) — Mobile checkout declined; desktop stable. ➡ Sessions: 540K (+1.1%) — Essentially flat; organic offset email decline. 📈 Orders: 11,340 (+6.7%) — Product page improvements appear to be contributing. ⚠️ Bounce Rate: 43% (+2pp) — No clear driver identified; monitor next week. Full briefing document: /tmp/cja_executive_briefing_.html ``` --- ## Tone and Style Rules 1. **Write outcomes, not activities.** "Revenue grew" not "metrics/revenue increased." 2. **Name the driver concisely.** "Paid Search drove the gain" not "Marketing Channel = Paid Search had a higher value in period A vs period B." 3. **One sentence per bullet.** Two at most. Executives skim. 4. **Lead with the most important finding.** Do not build to a conclusion. 5. **Be direct about bad news.** "Conversion Rate declined" not "Conversion Rate saw some movement in a downward direction." 6. **Quantify everything.** Every bullet must have a number. Opinions without data are not executive communication. 7. **Avoid jargon.** No "dimensions," "metrics IDs," "data view context," or "MCP tool calls" in the output. ## Important Guardrails - **Read-only reporting.** Never modify metrics, segments, or projects. - **Use business language, not technical IDs.** Replace dimension IDs (e.g., `variables/evar5`) with their display names. Never expose internal IDs in the narrative. - **Always state the date range prominently.** Executives need context — "last week" is ambiguous; write "April 7–13, 2026." - **Don't invent data.** If a KPI is unavailable or the report returns no data, say so explicitly rather than omitting or estimating. - **Cap the briefing to the most impactful findings.** 3–5 KPI tiles + 2–3 driver bullets is ideal; more than 8 KPIs dilutes the message. - **Note significant context.** Mention known external factors (campaigns, holidays, product releases) that affect the metrics when relevant. - **Validate numbers before presenting.** Cross-check KPI values against a second `runReport` call if they look anomalous. - **Customer-branded output, never vendor-branded.** The briefing is the customer's document about their own business. Never use "Adobe", "CJA", "Customer Journey Analytics", or any vendor/product name in the customer-visible briefing (title, lede, narrative, tables, footer, or in-chat output). The red/black header palette is the only Adobe-branded element allowed in the artifact. --- ## Example Interaction > "Write me an executive briefing for last week's performance." 1. **Setup:** Confirm data view with `findDataViews`. User selects their primary data view. Call `setDefaultSessionDataViewId`. 2. **Scope:** Confirm reporting period (last 7 days, April 7–13, 2026) and key KPIs (Revenue, Conversion Rate, Sessions, AOV). 3. **Data pull:** Run `runReport` for each KPI: current week vs. prior week and vs. same week last year. 4. **Narrative draft:** Compose 3–4 executive bullets in business language: "Revenue of $2.4M was up 8% week-over-week, driven by a 15% increase in Paid Search conversions. Conversion Rate dipped 2 points to 3.1%, consistent with the product page redesign rollout on April 9." 5. **HTML report:** Generate the print-ready HTML briefing with KPI tiles, narrative section, and driver table. Open the file. Present a 2-sentence summary to the user and offer to adjust tone or scope.