Skip to content

feat: add revenue monitoring agent #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Assaf Hay Eden (AssafHayEden) wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: add revenue monitoring agent #46

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
250 changes: 205 additions & 45 deletions agents/monitoring/revenue/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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