programme-anomaly-watch

---
name: programme-anomaly-watch
description: |
  Use this skill to spot week-over-week anomalies across an agency's portfolio of brands and networks — revenue drops, reversal spikes, dead links, publishers that fell out of the top 10. Designed to run on a schedule via Claude's own scheduling so the agency learns about problems before clients do.
  Trigger on: "Are there any problems with the affiliate programmes this week?", "Anomaly check", "Anything weird in the affiliate data?".
---

# Operating instructions

You are checking the book for week-over-week anomalies. Output is a short, ranked list — nothing more.

## Step 1 — enumerate the book

Call `affiliate_resolve_brand` with no arguments. The response is an array of `{ brand, network, networkBrandId }` bindings.

If the array is empty, say "No brands registered — nothing to watch" and stop. Do not pad.

## Step 1b - load recorded plans

Call `affiliate_list_client_strategies` once to see which registered brands have a plan recorded (`hasStrategy` / `hasKpi`) and whether any strategy directories are orphaned. For each registered brand in the book with either `hasStrategy` or `hasKpi`, call `affiliate_get_client_strategy({ brand })` to load its `strategy` prose and `kpi.targets`. Skip registered brands with no plan; most of the book may have none, and that is fine.

This is **advisory** context that reshapes severity (Step 4); it never changes what the data says. Report any `kpi.parseErrors` verbatim and ignore those targets. If orphan strategy directories exist, report them under `Failures`/notes and do not invent network data for them.

## Step 2 — pick the windows

Default period: the last 7 days, ending today. Comparison window: the 7 days immediately prior. Express all dates as ISO `YYYY-MM-DD`. Honour explicit user overrides ("this month vs last month", named dates).

## Step 2b — use the snapshot for the current-window health signal

Before fanning out, you may call `affiliate_build_brand_snapshot({ brand })` per brand for the current window (the 7-day default is `last7d`). Its value here is the count-honest `byNetwork` health: a network whose pull `failed` must not be read as "no anomalies". Treat a `failed` network exactly like a Step 3 binding failure — report it under `Failures` and say its absence of anomalies is not safe to assume.

The anomaly detection itself stays on `get_programme_performance` below: the week-over-week checks need the **comparison window** (a custom prior range the snapshot does not carry), and the top-10-dropout and silenced-publisher checks need the **per-publisher** rows (the snapshot's breakdown is per-programme). So the snapshot informs health, not the anomaly maths.

## Step 3 — fan out per binding

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 in parallel. Each call returns `ProgrammePerformanceRow[]` with `publisherId`, `publisherName`, `clicks`, `conversions`, `grossSale`, `commission`, `currency`, `status`.

If a binding fails, capture the verbatim error and report it under a `Failures` line at the end. Do not treat a failure as an anomaly.

## Step 4 — compute anomalies

Walk each `(brand, network)` binding and emit an anomaly for any of:

- **Revenue drop**: current-period `grossSale` is down more than 25% vs. the comparison window. Quote both figures and the percent drop.
- **Reversal spike**: the share of rows with `status: 'reversed'` (weighted by `grossSale`) is more than 2x the comparison-window baseline. Quote both ratios.
- **Top-10 dropout**: a publisher that was in the top 10 by `grossSale` in the comparison window is absent from the top 10 in the current window. Name the publisher and quote both ranks.
- **Publisher silenced**: a publisher with non-zero `conversions` in the comparison window has zero `conversions` in the current window (a 100% drop). Name the publisher.
- **Dead programme**: the binding produced zero `clicks` in the current window. Likely a tracking break or a dead link.

Also emit an anomaly for a **KPI threshold breach** where a brand has a compatible target: `reversal_rate` over a `<=` or `<` limit, or `approval_rate` under a `>=` or `>` floor, this window. Quote the actual rate and the target. For unsupported comparators or unavailable metrics, say the target is unsupported for this anomaly scan and exclude it rather than guessing.

Compute severity as the absolute current-period revenue at risk: for a revenue drop, the lost gross sale; for a silenced publisher, their comparison-period gross sale; for a dead programme, the comparison-period gross sale of the whole binding. Use the per-row `currency` — do not normalise.

**Reshape severity by the recorded plan** (when one exists for the brand):

- A drop in a partner type the brand's `Strategy.md` **deprioritised** can be lower concern only when the row data or publisher name makes that partner type evident. Down-rank it, keep the anomaly visible, and say why ("down 30%, but coupon is a deprioritised channel for this brand"). If partner type is not evident, do not guess.
- A drop in a **preferred / priority** partner type, or anything that crosses a recorded **escalation threshold** ("flag any drop over 20%"), is urgent. Up-rank it within the anomaly list while still quoting the underlying current and comparison figures.
- A KPI threshold breach is ranked by the recorded limit, not a generic baseline.

With no plan recorded for a brand, rank it exactly as today on raw revenue at risk. Absence of a plan is never itself an anomaly.

## Step 5 — present the report

Output a single compact list, ordered by severity desc. Each line: `<brand> · <network> · <anomaly type> · <magnitude> · <publisher(s)>`. One line per anomaly. No tables, no preamble.

If there are no anomalies, say "No anomalies this week" in one line and stop. Do not pad with "good news" commentary.

At the end, list any per-binding failures verbatim under a `Failures` heading so the user can retry. If a binding failed, the absence of anomalies for that binding is not safe to assume — say so.

## Scheduling

This skill is designed to be useful when run on a schedule. When invoked by Claude's scheduler, the output should be short enough to read on a phone — keep the anomaly list under ~12 lines if possible. If the book genuinely has more than 12 anomalies, group by brand and emit one line per brand summarising the count and the top reason.

## Constraints

- Never call something an anomaly without quoting both the current and comparison figures.
- Currency: respect the per-row `currency`. If a brand spans currencies, compute anomalies per currency.
- Do not invent thresholds. The thresholds in step 4 are the contract; if the user wants different ones, ask. A recorded KPI target adds a brand-specific threshold; it never loosens the step-4 ones.
- Recorded strategy and KPIs are advisory: they reshape severity and add KPI-breach checks, but never authorise an action and never change the underlying figures.
- A KPI target on a metric a bound network cannot supply is reported as unsupported for that network and excluded from anomaly ranking; never zero-fill it.
- Pair with `programme-performance-report` when the user wants the full per-publisher detail behind an anomaly.