agency-portfolio-rollup

name	agency-portfolio-rollup
description	Use this skill when an agency operator wants a single headline view of revenue across every brand and every network in their book — the agency's home dashboard. Trigger on: "How is the whole book doing this week?", "Show me revenue across all clients", "Portfolio summary", "Which brands are trending down this month?".

Operating instructions

You are producing a portfolio-wide rollup across every brand the agency has bound, on every network those brands are bound to.

Step 1 — enumerate the book

Call affiliate_resolve_brand with no arguments. The response is an array of { brand, network, networkBrandId } bindings — one row per (brand, network) pair.

If the array is empty, tell the user no brands are registered and point them at affiliate-networks-mcp setup. Stop.

Step 1b - load recorded plans

Call affiliate_list_client_strategies once. It returns one row per slug with hasStrategy / hasKpi / registered / orphan. For each registered brand in the book with either hasStrategy or hasKpi, call affiliate_get_client_strategy({ brand }) to load its kpi.targets and strategy framing. Skip registered brands with no plan.

Keep a count of how many registered brands in the book have no plan recorded; it drives the coverage line in Step 5. If affiliate_list_client_strategies returns orphan rows, mention them in the coverage line and do not invent network data for them. This context is advisory: it adds a verdict and a coverage prompt; it never changes the figures.

If kpi.parseErrors is non-empty for a loaded brand, report each malformed line verbatim in the coverage/failures area and exclude it from verdicts. Never guess what the target meant.

Step 2 — pick the windows

Default period: the last 7 days, ending today. Honour explicit user windows ("this month", "Q1", named dates).

Compute a comparison window of the same length immediately prior. Express all dates as ISO YYYY-MM-DD. Surface both windows in the final report so the user can confirm.

Step 2b — prefer per-brand snapshots for the standard windows

When the requested window is one of the snapshot windows (yesterday, last 7 days, last 30 days, year-to-date — the 7-day default is last7d), call affiliate_build_brand_snapshot({ brand }) once per brand instead of fanning out get_programme_performance per binding. Each brand's snapshot already aggregates across that brand's networks into the four windows with per-currency totals and a count-honest byNetwork health block, so you skip the manual per-network fan-out and the Step 4 by-brand aggregation. Take the per-brand headline straight from snapshot.windows.<window>.totals (per currency), and surface any byNetwork entry that is not ok on that brand's line so a brand whose book is missing a network is never silently under-counted.

Fall back to the per-network fan-out below for custom windows the four fixed windows do not cover, and to compute the comparison window (a custom prior range the snapshot does not carry).

Step 3 — fan out the performance calls

For each (brand, network) binding, call the network's performance tool twice — current window and comparison window. Tool names follow affiliate_<network>_get_programme_performance:

• Impact advertiser: affiliate_impact-advertiser_get_programme_performance({ brand, from, to })

Issue these in parallel — the chassis resolves brand to the correct networkBrandId per call. Do not serialise unless rate limits force it.

Each call returns ProgrammePerformanceRow[] with publisherId, publisherName, clicks, conversions, grossSale, commission, currency, status.

If a binding fails, capture the verbatim error (network, operation, message, httpStatus). Do not treat a failure as zero. Continue with the rest and report the gap under the affected brand's line.

Step 4 — aggregate by brand, not by network

The user thinks in brands. Sum each brand's bindings together for the headline. If a brand spans multiple currencies across its networks, keep each currency on its own sub-line — do not invent FX.

For each brand:

• Current-period grossSale, commission, conversions, clicks.
• Comparison-period grossSale.
• Delta in absolute currency and percent.

Step 5 — present the report

Output in this order:

1. Windows: current from YYYY-MM-DD to YYYY-MM-DD and comparison from YYYY-MM-DD to YYYY-MM-DD (each with day count).
2. Per-brand headline: one row per brand, sorted by current-period grossSale desc. Each row: brand name, gross sale, commission, conversions, delta (currency and percent). For a brand with a revenue target, add a short verdict against the plan (on track / behind / ahead). When the target has a period, show pace to target, for example "behind: GBP 268k of GBP 400k quarter, about 7% short on run-rate". When the target has no period, compare the current-window total and say no period was recorded. Where a target's metric is unsupported on a brand's bound network, say so rather than guess. If a brand had errors on one or more networks, append the per-network errors verbatim at the end of its row; never silently drop data.
3. Needs attention: a subsection listing every brand whose grossSale is down more than 20% vs. the comparison window, or that is behind a recorded KPI target. One line each: brand, current vs. comparison figure (or target gap), percent delta. A brand down in a channel its strategy deprioritised can be noted as lower concern only when the row data or publisher name makes that partner type evident.
4. Strategy coverage: if any registered brands have no plan recorded, one line: "N of M brands have no strategy recorded; reports for them judge on bare deltas. Want to set them up?" If orphan strategy directories exist, add "Also found orphan strategy records: <slug...>; they have no registered brand binding." Omit when every registered brand has a plan and there are no orphans.
5. Portfolio totals: totals across every brand. Per-currency if the book spans currencies.
6. Long tail: if there are more than 12 brands, show the top 12 in full and collapse the remainder under one Others (N brands, <total>, <percent delta>) line per currency.
7. Failures (if any): per (brand, network) verbatim error block, in case the user wants to retry.

Matter-of-fact tone, UK spelling. Keep the table compact.

Constraints

• Never invent figures. If a binding returned no rows, say "no data" — don't backfill zeros.
• Currency: respect the per-row currency. Per-brand totals stay in the currency of their underlying rows. Across-brand totals stay per-currency.
• Do not normalise across networks or across brands. The agency runs reports in the currencies its clients invoice in.
• Recorded strategy and KPIs are advisory: they add a per-brand verdict and a coverage prompt, but never authorise an action or change the figures. Report KPI parse errors verbatim and exclude those targets.
• A KPI target on a metric a bound network cannot supply is reported as unsupported for that network and left out of its verdict; never zero-fill it or silently merge partial coverage into a cross-brand total.
• Pair with client-onboarding to record a plan for a brand surfaced by the coverage line.
• Pair with programme-performance-report when the user drills into a single brand from the rollup.
• Pair with affiliate_resolve_brand({ network: "<slug>" }) if the user wants to scope the rollup to a single network.