# Anomaly Escalation
Detect metric anomalies in campaign data via API and escalate them to humans through an in-session message and a follow-up email.

## When to use
- A scheduled or ad hoc campaign-monitoring check needs to run against live metrics.
- A metric (spend, CTR, conversion rate, error rate) looks like it has moved outside its normal range.
- A prior anomaly needs re-checking to confirm it has resolved or worsened.
- Stakeholders must be notified quickly once an anomaly is confirmed.

## Tools
- `http-get`: pull current campaign/metric data from the source SaaS API for comparison against baseline.
- `shell-execute`: run a small script to compute deltas, thresholds, or statistical outliers from the pulled data.
- `send-message`: notify a human or another agent in-session as soon as an anomaly is confirmed.
- `send-email`: send a detailed escalation email to the responsible human with the anomaly summary.
- `schedule-task`: register this watch on a recurring cron cadence so it reruns automatically without a human re-enqueuing it.

## Cadence

Monitoring must repeat, not run once. On first setup, use `schedule-task` to register a recurring run of this check on an appropriate cron cadence (for example `0 * * * *` hourly or `0 9 * * *` daily), passing the same monitoring instruction as the schedule prompt. The platform then reruns it automatically at each due time — you never depend on a human to re-enqueue it. Create the schedule only once; if this check is already scheduled, skip re-creating it.

## Playbook
1. Identify the metric endpoint and baseline window needed for this check.
2. Call the source REST API with `http-get` (e.g. GET https://api.<service>.com/v1/campaigns/{id}/metrics). Authentication is injected by the org's Integration row for this host — never ask for, echo, or hardcode credentials. If the call returns 401/403 or no Integration row exists, stop and message a human via `send-message` asking them to create the Integration, naming the service and required scopes.
3. If historical baseline data isn't included in the response, issue additional `http-get` calls to fetch the comparison period.
4. Use `shell-execute` to run a short script that computes the deviation (percentage change, z-score, or threshold breach) between current and baseline values.
5. If the deviation is within normal range, stop here — no escalation needed.
6. If the deviation exceeds the defined threshold, draft a concise anomaly summary: metric name, expected vs. actual value, percentage deviation, and campaign identifier.
7. Immediately notify the relevant human or agent in-session via `send-message`, including the summary so they can react without delay.
8. Send a fuller written record to the responsible human's email via `send-email`, including the same summary plus any supporting numbers computed in step 4.
9. If the anomaly implies a SaaS record needs to be corrected (e.g. pausing a campaign, editing a budget), do not attempt it — that requires PATCH/PUT/DELETE, which is not possible with these tools. Compile the recommended change into the escalation message and hand off the decision to a human via `send-message`.

## Failure modes
- 401/403 response -> missing Integration for the host; stop and escalate via `send-message` naming the service and required scopes.
- Empty or malformed result from `http-get` -> verify the endpoint, campaign ID, and query parameters before retrying.
- Rate limit hit -> back off and retry later; note the rate-limit event via `update-memory` so future runs pace requests correctly.
- Source page/API structure changed and data can't be parsed -> fall back to browser-search to confirm the service's current API documentation before retrying.

## Done when
- The anomaly has been confirmed by computed deviation data from `shell-execute`, or ruled out as noise.
- A `send-message` notification and a `send-email` escalation have both been sent for any confirmed anomaly, containing the metric, expected vs. actual values, and campaign identifier.
- Any required corrective action is documented as a recommendation for human follow-up rather than attempted directly.