aa-executive-briefing

What this skill does

# Executive Briefing (Adobe Analytics)

Generate a concise, executive-ready performance summary with narrative
context, metric highlights, and key drivers. Designed for leadership
audiences — no raw data dumps, just clear signals and business implications.

> **Key parameter facts validated during implementation:**
> - `runReport` → `metricIds` (plural), not `metricId`; dates as `YYYY-MM-DDTHH:mm:ss`
> - `findMetrics` → `expansions` is a **required** parameter (use `"componentType"`)
> - `describeAa` → parameter is `guideType`, not `guide`; `REPORT_SUITE_CONTEXT_GUIDE`
>   may return empty for some report suites — skip gracefully and proceed
> - `metrics/uniquevisitors` is often unauthorized — use `metrics/visits` instead
> - `setSessionDefaults` is the correct tool name (not `setDefaultReportSuite`)

---

## AA MCP Tools Used

- `findReportSuites` — select report suite
- `setSessionDefaults` — set session context (reportSuiteId + globalCompanyId)
- `describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE")` — load org context;
  note: may return no output for some report suites — proceed without it
- `findMetrics(expansions: "componentType")` — resolve metric IDs (expansions
  parameter is **required**)
- `listComponentUsage(componentType: "metric")` — identify most-used metrics
  if not specified by the user
- `runReport` — current and comparison period with all metrics batched in one
  call (`metricIds` accepts comma-separated IDs); dimension breakdowns for top movers
- `searchDimensionItems` — validate dimension values for driver callouts

---

## Phase 0 — Setup

1. Confirm report suite.
2. Load organizational context:

```
findReportSuites()
setSessionDefaults(reportSuiteId: "<rsid>", globalCompanyId: "<companyId>")
describeAa(guideType: "REPORT_SUITE_CONTEXT_GUIDE")   # may return empty — proceed if so
```

Use the context guide to understand:
- The organization's name and industry
- Which metrics are most used (top KPIs)
- **Calendar conventions and timezone.** Record these values — they are
  inputs to every date computation in Phase 1:
  - `WEEK_START_DOW` — day of week each week starts on. Default: **Monday**
    (ISO 8601).
  - `FISCAL_YEAR_START_MONTH` — month the fiscal year begins. Default:
    **January** (calendar year).
  - `TIMEZONE` — for example, `America/Los_Angeles`.
  - `CALENDAR_SOURCE` — one of `"context guide"`, `"default fallback"`, or
    `"user override"`.
- Any active report suite segments

---

## Phase 1 — Clarify the Briefing

Ask the user:

1. **Period** — "What time period should this briefing cover?"
   - Last week
   - Last month
   - Month-to-date (MTD)
   - This quarter / QTD
   - Last quarter
   - Custom date range

#### The principle

Two runs of this skill on the same report suite, period type, and prompt MUST
produce identical `current` and `comparison` date ranges. Determinism comes
from (a) reading calendar conventions from Phase 0 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" | `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 | 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

Assumes `WEEK_START_DOW = Sunday` and `FISCAL_YEAR_START_MONTH = January`. Numbers change for other calendars — that's 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.

2. **Audience** — "Who is this briefing for?"
   - C-suite / board (highest level, fewest metrics, most context)
   - VP/Director level (more detail, some dimension context)
   - Marketing leadership (channel and campaign focus)
   Default: C-suite tone (concise, business-focused).

3. **North-star metric** — "What is the single most important metric for
   this briefing?" (e.g., revenue, conversions, retention rate)
   If not specified, use the most-used metric from `listComponentUsage`.

4. **Supporting metrics** — "What other metrics should be included? (up to 5)"

5. **Specific topic focus** — "Is there anything you want to highlight or
   investigate? (e.g., mobile performance, campaign results)"

---

## Phase 2 — Resolve Metrics

```
findMetrics(expansions: "componentType")  # expansions required
listComponentUsage(componentType: "metric")  # if metrics not specified
```

> **Important:** `findMetrics` requires the `expansions` parameter (use `"componentType"`
> as a safe default). Without it the call will fail.
>
> **Avoid `metrics/uniquevisitors`** — this metric is frequently restricted and returns
> an "unauthorized_metric" error. Prefer `metrics/visits` for audience size.
>
> **Reliable standard metrics for AA briefings:** `metrics/pageviews`, `metrics/visits`,
> `metrics/orders`, `metrics/revenue`, `metrics/bouncerate`, `metrics/occurrences`

### Deterministic selection — do not improvise

The KPI set MUST be reproducible across runs. Two runs of this skill on the same
report suite + period must produce the same metric values, which requires
selecting the **same metric IDs** every time. Follow