feat: add revenue monitoring agent

Monitor MRR/ARR, subscription trends, and churn with revenue anomaly
detection.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: AssafHayEden

agents/monitoring/revenue/SKILL.md

@@ -1,64 +1,224 @@
 ---
 name: revenue-monitor
-description: Monitors revenue metrics, tracks subscription changes, and alerts on revenue anomalies or threshold breaches.
-tags: [monitoring, revenue, subscriptions]
+description: "Monitor LTX Studio revenue metrics and subscription changes. Detects revenue anomalies, churn spikes, and refund issues. Use when: (1) detecting revenue drops, (2) alerting on churn rate changes, (3) investigating subscription tier movements."
+tags: [monitoring, revenue, subscriptions, churn, mrr]
 ---
 
 # Revenue Monitor
 
-## When to use
+## 1. Overview (Why?)
 
-- "Monitor revenue trends"
-- "Alert when revenue drops"
-- "Track subscription churn"
-- "Monitor MRR/ARR changes"
-- "Alert on refund spikes"
+LTX Studio revenue varies by tier (Free/Lite/Standard/Pro/Enterprise) and plan type (self-serve/contract/pilot). Revenue monitoring requires tracking both top-line metrics (MRR, ARR) and operational indicators (churn, refunds, tier movements) to detect problems early.
 
-## What it monitors
+This skill provides **autonomous revenue monitoring** with alerting on revenue drops, churn rate spikes, refund increases, and subscription changes. It monitors all segments and identifies which tiers or plan types drive changes.
 
-- **Revenue metrics**: MRR, ARR, daily revenue
-- **Subscription metrics**: New subscriptions, cancellations, churns, renewals
-- **Refunds**: Refund rate, refund amount
-- **Tier changes**: Upgrades, downgrades
-- **Enterprise contracts**: Contract value, renewals
+**Problem solved**: Detect revenue problems, churn risk, and subscription health issues before they compound — with segment-level root cause analysis.
 
-## Steps
+## 2. Requirements (What?)
 
-1. **Gather requirements from user:**
-   - Which revenue metric to monitor
-   - Alert threshold (e.g., "drop > 10%", "< $X per day")
-   - Time window (daily, weekly, monthly)
-   - Notification channel (Slack, email)
+Monitor these outcomes autonomously:
 
-2. **Read shared files:**
-   - `shared/bq-schema.md` — Subscription tables (ltxstudio_user_tiers_dates, etc.)
-   - `shared/metric-standards.md` — Revenue metric definitions
+- [ ] Revenue drops by segment (tier, plan type)
+- [ ] MRR and ARR trend changes
+- [ ] Churn rate increases above baseline
+- [ ] Refund rate spikes
+- [ ] New subscription volume drops
+- [ ] Tier movements (upgrades vs downgrades)
+- [ ] Enterprise contract renewals approaching (< 90 days)
+- [ ] Alerts fire only when changes exceed thresholds
+- [ ] Root cause identifies which tiers/plans drove changes
 
-3. **Write monitoring SQL:**
-   - Query current metric value
-   - Compare against historical baseline or threshold
-   - Flag anomalies or breaches
+## 3. Progress Tracker
 
-4. **Present to user:**
-   - Show SQL query
-   - Show example alert format
-   - Confirm threshold values
+* [ ] Read shared knowledge (schema, metrics, business context)
+* [ ] Write monitoring SQL with baseline comparisons
+* [ ] Execute query for target date range
+* [ ] Analyze results by segment (tier, plan type)
+* [ ] Identify root cause (which segments drove changes)
+* [ ] Present findings with severity and recommendations
+* [ ] Set up ongoing alerts (if requested)
 
-5. **Set up alert** (manual for now):
-   - Document SQL in Hex or BigQuery scheduled query
-   - Configure Slack webhook or notification
+## 4. Implementation Plan
 
-## Reference files
+### Phase 1: Read Alert Thresholds
 
-| File | Read when |
-|------|-----------|
-| `shared/bq-schema.md` | Writing SQL for subscription/revenue tables |
-| `shared/metric-standards.md` | Defining revenue metrics |
+**Generic thresholds** (data-driven analysis pending):
+- Revenue drop > 15% DoD or > 10% WoW
+- Churn rate > 5% or increase > 2x baseline
+- Refund rate > 3% or spike > 50% DoD
+- New subscriptions drop > 20% WoW
+- Enterprise renewals < 90 days out
 
-## Rules
+[!IMPORTANT] These are generic thresholds. Consider creating production thresholds based on 60-day analysis (similar to usage/GPU cost monitoring).
 
-- DO use LTX Studio subscription tables from bq-schema.md
-- DO exclude is_lt_team unless explicitly requested
-- DO validate thresholds with user before setting alerts
-- DO NOT hardcode dates — use rolling windows
-- DO account for timezone differences in daily revenue calculations
+### Phase 2: Read Shared Knowledge
+
+Before writing SQL, read:
+- **`shared/product-context.md`** — LTX products, user types, business model, enterprise context
+- **`shared/bq-schema.md`** — Subscription tables (ltxstudio_user_tiers_dates, ltxstudio_subscriptions, etc.), user segmentation queries
+- **`shared/metric-standards.md`** — Revenue metric definitions (MRR, ARR, churn, LTV)
+- **`shared/event-registry.yaml`** — Feature events (if analyzing feature-driven revenue)
+
+**Data nuances**:
+- Tables: `ltxstudio_user_tiers_dates`, `ltxstudio_subscriptions`
+- Key columns: `lt_id`, `griffin_tier_name`, `subscription_start_date`, `subscription_end_date`, `plan_type`
+- Exclude `is_lt_team` unless explicitly requested
+- Revenue calculations vary by plan type (self-serve vs contract/pilot)
+
+### Phase 3: Write Monitoring SQL
+
+✅ **PREFERRED: Monitor all segments with baseline comparisons**
+
+```sql
+WITH revenue_metrics AS (
+  SELECT
+    dt,
+    griffin_tier_name,
+    plan_type,
+    COUNT(DISTINCT lt_id) AS active_subscribers,
+    SUM(CASE WHEN subscription_start_date = dt THEN 1 ELSE 0 END) AS new_subs,
+    SUM(CASE WHEN subscription_end_date = dt THEN 1 ELSE 0 END) AS churned_subs,
+    SUM(mrr_amount) AS total_mrr,
+    SUM(arr_amount) AS total_arr
+  FROM subscription_table
+  WHERE dt >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
+    AND dt <= DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY)
+    AND is_lt_team IS FALSE
+  GROUP BY dt, griffin_tier_name, plan_type
+),
+metrics_with_baseline AS (
+  SELECT
+    *,
+    AVG(total_mrr) OVER (
+      PARTITION BY griffin_tier_name, plan_type
+      ORDER BY dt ROWS BETWEEN 7 PRECEDING AND 1 PRECEDING
+    ) AS mrr_baseline_7d,
+    AVG(churned_subs) OVER (
+      PARTITION BY griffin_tier_name, plan_type
+      ORDER BY dt ROWS BETWEEN 7 PRECEDING AND 1 PRECEDING
+    ) AS churn_baseline_7d
+  FROM revenue_metrics
+)
+SELECT * FROM metrics_with_baseline
+WHERE dt = DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY);
+```
+
+**Key patterns**:
+- **Segmentation**: By tier (Free/Lite/Standard/Pro/Enterprise) and plan type (self-serve/contract/pilot)
+- **Baseline**: 7-day rolling average for comparison
+- **Time window**: Yesterday only
+
+### Phase 4: Execute Query
+
+Run query using:
+```bash
+bq --project_id=ltx-dwh-explore query --use_legacy_sql=false --format=pretty "
+<query>
+"
+```
+
+### Phase 5: Analyze Results
+
+**For revenue trends**:
+- Compare current period vs baseline (7-day avg, prior week, prior month)
+- Calculate % change and flag significant shifts (>15% DoD, >10% WoW)
+- Identify which tiers/plans drove changes
+
+**For churn analysis**:
+- Calculate churn rate = churned_subs / active_subscribers
+- Compare to baseline and flag if > 5% or increase > 2x baseline
+- Identify which tiers have highest churn
+
+**For subscription health**:
+- Track new subscription volume by tier
+- Monitor upgrade vs downgrade ratios
+- Flag enterprise renewal dates < 90 days out
+
+### Phase 6: Present Findings
+
+Format results with:
+- **Summary**: Key finding (e.g., "MRR dropped 18% yesterday")
+- **Root cause**: Which segment drove the change (e.g., "Standard tier churned 12 users")
+- **Breakdown**: Metrics by tier and plan type
+- **Recommendation**: Action to take (investigate churn reason, contact at-risk accounts)
+
+**Alert format**:
+```
+⚠️ REVENUE ALERT:
+  • Metric: MRR Drop
+    Current: $X | Baseline: $Y
+    Change: -Z%
+    Segment: Standard tier, self-serve
+
+Recommendation: Investigate recent Standard tier churns
+```
+
+### Phase 7: Set Up Alert (Optional)
+
+For ongoing monitoring:
+1. Save SQL query
+2. Set up in BigQuery scheduled query or Hex Thread
+3. Configure notification threshold
+4. Route alerts to Revenue/Growth team
+
+## 5. Context & References
+
+### Shared Knowledge
+- **`shared/product-context.md`** — LTX products, user types, business model, enterprise context
+- **`shared/bq-schema.md`** — Subscription tables, user segmentation queries
+- **`shared/metric-standards.md`** — Revenue metric definitions (MRR, ARR, churn, LTV, retention)
+- **`shared/event-registry.yaml`** — Feature events for feature-driven revenue analysis
+
+### Data Sources
+Tables: `ltxstudio_user_tiers_dates`, `ltxstudio_subscriptions`
+- Key columns: `lt_id`, `griffin_tier_name`, `subscription_start_date`, `subscription_end_date`, `plan_type`, `mrr_amount`, `arr_amount`
+- Filter: `is_lt_team IS FALSE` for customer revenue
+
+### Tiers
+- Free (no revenue)
+- Lite (lowest paid tier)
+- Standard (mid-tier)
+- Pro (high-tier)
+- Enterprise (contract/pilot)
+
+### Plan Types
+- Self-serve (automated subscription)
+- Contract (enterprise contract)
+- Pilot (enterprise pilot)
+
+## 6. Constraints & Done
+
+### DO NOT
+
+- **DO NOT** include is_lt_team users unless explicitly requested
+- **DO NOT** hardcode dates — use rolling windows
+- **DO NOT** use absolute thresholds — compare to baseline
+- **DO NOT** mix plan types without proper segmentation
+- **DO NOT** ignore timezone differences in daily revenue calculations
+
+### DO
+
+- **DO** use LTX Studio subscription tables from bq-schema.md
+- **DO** exclude is_lt_team unless explicitly requested
+- **DO** validate thresholds with user before setting alerts
+- **DO** use rolling windows (7-day, 30-day baselines)
+- **DO** account for timezone differences in daily revenue calculations
+- **DO** segment by tier AND plan type for root cause analysis
+- **DO** compare against baseline (7-day avg, prior period) for trends
+- **DO** calculate churn rate = churned / active subscribers
+- **DO** flag MRR drops > 15% DoD or > 10% WoW
+- **DO** flag churn rate > 5% or increase > 2x baseline
+- **DO** flag refund rate > 3% or spike > 50% DoD
+- **DO** flag new subscription drops > 20% WoW
+- **DO** track enterprise renewal dates < 90 days out
+- **DO** include segment breakdown in all alerts
+- **DO** validate unusual patterns with Revenue/Growth team before alerting
+
+### Completion Criteria
+
+✅ All revenue metrics monitored (MRR, ARR, churn, refunds, new subs)
+✅ Alerts fire with thresholds (generic pending production analysis)
+✅ Segment-level root cause identified
+✅ Findings presented with recommendations
+✅ Timezone handling applied to daily revenue
+✅ Enterprise renewals tracked