Anomaly Detector

interface AnomalyDetectorInput {
  tenantId:     string;
  reportPeriod: 'daily' | 'weekly' | 'monthly';
  periodStart:  string;   // ISO date
  periodEnd:    string;   // ISO date
 
  // The control plane computes metric comparisons and flags those outside threshold.
  // The agent receives only pre-flagged metrics — it does NOT fetch data itself.
  flaggedMetrics: FlaggedMetric[];
}
 
interface FlaggedMetric {
  metricName:    string;   // e.g. "organic_sessions", "conversion_rate", "google_ads_cpa"
  channel:       string;   // e.g. "organic", "google_ads", "meta_ads", "email", "social"
  currentValue:  number;
  previousValue: number;
  changePct:     number;   // signed: negative = decline, positive = spike
  threshold:     number;   // the % change threshold that caused this flag, e.g. 20 or -15
  direction:     'spike' | 'drop';
  rawContext?: {
    // Optional additional context the control plane may include
    // e.g. top landing pages, campaign names, keyword movements
    [key: string]: string | number;
  };
}

interface AnomalyDetectorOutput {
  processedAt: string;    // ISO timestamp
  alerts:      Alert[];
  summary: {
    criticalCount: number;
    warningCount:  number;
    infoCount:     number;
    dismissedCount: number;  // flagged metrics the agent deemed not significant
  };
}
 
interface Alert {
  alertId:        string;
  metricName:     string;
  channel:        string;
  currentValue:   number;
  previousValue:  number;
  changePct:      number;
  severity:       'critical' | 'warning' | 'info';
  isSignificant:  boolean;   // false = agent dismissed this as non-significant
  dismissReason?: string;    // if isSignificant = false, why
  likelyCauses:   string[];  // 2–4 ordered by probability
  narrative:      string;    // 2–4 sentence plain-English alert description
  recommendedAction: string; // specific next step
  urgency:        'normal' | 'high';
  requiresHITL:   boolean;
}

[
  {
    "alertId": "alert-2026-03-28-organic-drop",
    "metricName": "organic_sessions",
    "channel": "organic",
    "currentValue": 2140,
    "previousValue": 3890,
    "changePct": -44.99,
    "severity": "critical",
    "isSignificant": true,
    "likelyCauses": [
      "Google core algorithm update (multiple updates confirmed in March 2026)",
      "Manual penalty or manual action applied to site",
      "Significant technical issue — crawl block, robots.txt change, or indexing error",
      "Seasonality or industry-wide traffic drop"
    ],
    "narrative": "Organic sessions dropped 45% this week (2,140 vs. 3,890 last week) — a decline of this magnitude is unusual and warrants immediate investigation. No planned activity in the client's calendar explains this drop. The most likely cause is a Google algorithm update or a technical issue affecting crawlability or indexing.",
    "recommendedAction": "Check Google Search Console for manual actions, coverage errors, and impressions trend. Cross-reference with the known March Google algorithm update. If impressions also dropped, this is likely algorithmic. If impressions are stable but clicks dropped, check title tags and meta descriptions.",
    "urgency": "high",
    "requiresHITL": true
  },
  {
    "alertId": "alert-2026-03-28-email-openrate",
    "metricName": "email_open_rate",
    "channel": "email",
    "currentValue": 0.38,
    "previousValue": 0.33,
    "changePct": 15.15,
    "severity": "info",
    "isSignificant": false,
    "dismissReason": "15% improvement in open rate is within normal variation and consistent with the scheduled Spring Offer campaign noted in client documents. No action required.",
    "likelyCauses": [],
    "narrative": "",
    "recommendedAction": "",
    "urgency": "normal",
    "requiresHITL": false
  }
]

You are an anomaly analysis assistant for a digital marketing agency. Your job is to
evaluate pre-flagged metric changes, determine whether each is genuinely significant
given the client's business context, and write clear alert narratives for the team.

CLIENT CONTEXT:
{{CLIENT_CONTEXT}}

KNOWLEDGE BASE CONTEXT:
{{RAG_CONTEXT}}

You have received a list of metrics that crossed automated thresholds. Your tasks:

1. For each flagged metric, decide: is this genuinely significant, or is it explained
   by known context (scheduled campaign, seasonal pattern, planned site change)?

2. If not significant: set isSignificant = false with a brief dismissReason.
   Do NOT write a narrative or recommendation for dismissed alerts.

3. If significant: assign severity (critical / warning / info), list 2–4 likely causes
   ordered by probability, write a 2–4 sentence plain-English narrative, and write one
   specific recommended action.

4. Severity guide:
   - critical: potential revenue impact or platform issue requiring same-day action
   - warning: needs attention within 48 hours; no immediate revenue impact
   - info: positive movement or minor change worth noting

5. requiresHITL = true for all critical alerts and any warning where the recommended
   action involves making changes to live campaigns or platforms.

Rules:
- Do not make up explanations — if you don't know the cause, say so and give hypotheses
- Cite specific numbers in every narrative (current value, previous value, change %)
- Recommended actions must be specific — name the tool, report, or metric to check
- If a metric spike is clearly positive (e.g. ROAS increased 40%), classify as info
  unless it suggests a tracking issue (ROAS 400x or conversion rate 90%+ suggests broken tracking)
- Match the agency's professional tone — clear, direct, not alarmist

Output as valid JSON matching the AnomalyDetectorOutput schema.

# Anomaly Triage Guide
 
## Common Causes by Metric Type
 
### Organic Sessions Drop
- Google algorithm update (check Search Console impressions — if impressions also dropped, algorithmic)
- Manual penalty (check Search Console > Manual Actions)
- Crawl/indexing issue (robots.txt change, noindex tag accidentally added, server error)
- Seasonal demand drop (expected for some industries — check year-over-year)
- Competitor outranking on key pages
 
### Organic Sessions Spike
- Viral content or backlink from high-traffic source
- Featured snippet acquired for high-volume keyword
- Ranking jump after content update
- Potential bot traffic (check bounce rate and session duration — if both abnormal, likely bots)
 
### Google Ads CPA Increase
- Auction competition increase (check impression share)
- Bid strategy change — target CPA learning phase
- Landing page degradation (check conversion rate separately)
- Ad fatigue (check CTR trend)
- Seasonal demand shift increasing CPCs
 
### Google Ads CPA Decrease
- Improved landing page conversion rate
- Negative keyword refinement removing poor-intent traffic
- Audience targeting improvement
- Confirm with conversion tracking — sudden CPA drop can indicate broken tracking
 
### Meta Ads CTR Decline
- Creative fatigue — check frequency (> 3.5 in 7 days = likely fatigued)
- Audience saturation
- Seasonal relevance decrease
- Ad copy not resonating with current market sentiment
 
### Conversion Rate Drop (site-wide)
- Technical issue on conversion page (form broken, CTA button error)
- Traffic quality change (new traffic source sending poor-intent visitors)
- Landing page change that negatively affected conversion
- Payment or checkout issue (for e-commerce)
 
### Email Open Rate Drop
- Deliverability issue — check spam placement rates
- Subject line quality decline
- List fatigue — sending frequency too high
- Segment quality degradation
 
## False Positive Scenarios (dismiss these)
- Traffic spikes on email send days — expected
- CPA improvement after launching a new ad creative — positive signal, not an alert
- Conversion rate spike immediately after a landing page A/B test starts — early data fluctuation
- Social engagement spike after a viral post — expected and positive
- Open rate increase during a promotional campaign — expected
 
## Severity Override Rules
- Any metric suggesting broken tracking (ROAS > 50x, conversion rate > 80%) → critical
  regardless of direction
- Any metric moving in positive direction → info (not warning or critical) unless it
  indicates a tracking error
- Organic traffic drop > 30% in one week → always critical
- Ad account spend stopping unexpectedly → always critical