diff --git a/agents/monitoring/revenue/SKILL.md b/agents/monitoring/revenue/SKILL.md index 07f45b4..804d688 100644 --- a/agents/monitoring/revenue/SKILL.md +++ b/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 " + +" +``` + +### 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