autodoc-agent-kit 1.0.0

package/src/modules/product/skills/saas-revenue-growth-metrics/examples/healthy-saas.md

@@ -0,0 +1,131 @@
+# Example: Healthy SaaS Metrics
+
+**Company:** ProjectHub (mid-market project management SaaS)
+**Stage:** Growth stage, Series B funded
+**Customer Base:** 200 accounts, 20,000 users
+**Period:** Monthly snapshot
+
+---
+
+## Revenue Metrics
+
+### MRR/ARR
+```
+Starting MRR: $2,000,000
++ New MRR: $100,000 (10 new accounts)
++ Expansion MRR: $80,000 (upsells + usage growth)
+- Churned MRR: $30,000 (5 accounts churned)
+- Contraction MRR: $10,000 (3 accounts downgraded)
+Ending MRR: $2,140,000
+
+MRR Growth Rate: 7% MoM
+ARR: $25.7M
+```
+
+### ARPA/ARPU
+```
+ARPA = $2,140,000 / 200 accounts = $10,700/month
+ARPU = $2,140,000 / 20,000 users = $107/month
+Average seats per account = 100 users
+```
+
+### Revenue Components
+```
+New MRR: $100K (5% of total)
+Expansion MRR: $80K (4% of total)
+Churned MRR: $30K (1.5% of total)
+Contraction MRR: $10K (0.5% of total)
+```
+
+---
+
+## Retention & Expansion Metrics
+
+### Churn Rate
+```
+Logo Churn: 5 / 200 = 2.5% monthly (~26% annual)
+Revenue Churn: $30K / $2M = 1.5% monthly (~17% annual)
+```
+
+**Analysis:** Revenue churn < logo churn = losing smaller customers, which is healthy.
+
+### NRR
+```
+Starting ARR: $24M
+Expansion: $960K (annual)
+Churned: $360K (annual)
+Contraction: $120K (annual)
+Ending ARR: $24.48M
+
+NRR = $24.48M / $24M = 102%
+```
+
+### Quick Ratio
+```
+Gains = $100K + $80K = $180K
+Losses = $30K + $10K = $40K
+Quick Ratio = $180K / $40K = 4.5
+```
+
+---
+
+## Analysis
+
+### ✅ Strengths
+
+**Strong growth:**
+- 7% MoM MRR growth
+- Healthy mix: 5% new + 4% expansion
+
+**Excellent retention:**
+- 2.5% logo churn (below 5% threshold)
+- 1.5% revenue churn (better than logo)
+- 102% NRR (growing without new logos)
+
+**Efficient expansion:**
+- $80K expansion MRR (4% of base)
+- Expansion-driven NRR
+- Average expansion per account: $400/month
+
+**Sustainable growth:**
+- Quick Ratio 4.5 (gains far exceed losses)
+- Revenue churn declining (was 2% six months ago)
+- Newer cohorts retain better than older cohorts
+
+### 📊 Opportunities
+
+**Expansion room:**
+- NRR at 102% is good, but room to grow to 110-120%
+- Only 40% of customers have expanded (could push to 60%)
+- Cross-sell opportunity: 30% of customers don't use integrations add-on
+
+**ARPU optimization:**
+- $107/user is solid for mid-market, but enterprise segment shows $200/user potential
+- Could introduce premium tier for advanced features
+
+**Reduce churn:**
+- 2.5% logo churn is acceptable but not excellent
+- Analysis shows 70% of churn happens in first 90 days (onboarding problem)
+- Fix: Improve onboarding, aim for <2% logo churn
+
+---
+
+## Actions Recommended
+
+1. **Scale acquisition aggressively** — Unit economics are strong (see `saas-economics-efficiency-metrics` for CAC/LTV)
+2. **Improve onboarding** — Reduce early churn from 5% to 3% in first 90 days
+3. **Expand cross-sell** — Push integrations add-on to 30% of base without it (potential +$30K MRR)
+4. **Test premium tier** — 20 enterprise customers show willingness to pay 2x for advanced features
+5. **Monitor cohort retention** — Continue tracking that new cohorts retain better than old
+
+---
+
+## Cohort Retention Trend (Positive Signal)
+
+| Cohort | Month 6 Retention | Month 12 Retention |
+|--------|-------------------|---------------------|
+| 12 months ago | 85% | 78% |
+| 6 months ago | 88% | TBD |
+| Current | 92% (on track) | TBD |
+
+**Analysis:** Newer cohorts retaining better = product improvements working. Safe to scale acquisition.

package/src/modules/product/skills/saas-revenue-growth-metrics/examples/warning-signs.md

@@ -0,0 +1,229 @@
+# Example: Warning Signs (Leaky Bucket)
+
+**Company:** MarketingFlow (SMB marketing automation SaaS)
+**Stage:** Early growth, post-Seed
+**Customer Base:** 2,000 accounts, 10,000 users
+**Period:** Monthly snapshot
+
+---
+
+## Revenue Metrics
+
+### MRR/ARR
+```
+Starting MRR: $500,000
++ New MRR: $100,000 (200 new accounts)
++ Expansion MRR: $5,000 (minimal upsells)
+- Churned MRR: $50,000 (120 accounts churned)
+- Contraction MRR: $10,000 (40 accounts downgraded)
+Ending MRR: $545,000
+
+MRR Growth Rate: 9% MoM (but driven entirely by new customer acquisition)
+ARR: $6.5M
+```
+
+### ARPA/ARPU
+```
+ARPA = $545,000 / 2,000 accounts = $272/month
+ARPU = $545,000 / 10,000 users = $54.50/month
+Average seats per account = 5 users
+```
+
+### Revenue Components
+```
+New MRR: $100K (20% of base — very high)
+Expansion MRR: $5K (1% of base — very low)
+Churned MRR: $50K (10% of base — crisis level)
+Contraction MRR: $10K (2% of base — concerning)
+```
+
+---
+
+## Retention & Expansion Metrics
+
+### Churn Rate
+```
+Logo Churn: 120 / 2,000 = 6% monthly (~50% annual)
+Revenue Churn: $50K / $500K = 10% monthly (~69% annual)
+```
+
+**Analysis:** Revenue churn > logo churn = losing bigger customers. Crisis signal.
+
+### NRR
+```
+Starting ARR: $6M
+Expansion: $60K (annual)
+Churned: $600K (annual)
+Contraction: $120K (annual)
+Ending ARR: $5.34M
+
+NRR = $5.34M / $6M = 89%
+```
+
+**Analysis:** NRR <100% = contracting base. Losing revenue from existing customers faster than expanding them.
+
+### Quick Ratio
+```
+Gains = $100K + $5K = $105K
+Losses = $50K + $10K = $60K
+Quick Ratio = $105K / $60K = 1.75
+```
+
+**Analysis:** Quick Ratio <2 = leaky bucket. Barely outpacing losses.
+
+---
+
+## Cohort Retention Trend (Negative Signal)
+
+| Cohort | Month 3 Retention | Month 6 Retention | Month 12 Retention |
+|--------|-------------------|-------------------|---------------------|
+| 12 months ago | 82% | 75% | 68% |
+| 6 months ago | 75% | 65% | TBD |
+| Current | 68% (on track) | TBD | TBD |
+
+**Analysis:** Newer cohorts churning FASTER than older cohorts. Product-market fit is degrading.
+
+---
+
+## Analysis
+
+### 🚨 Critical Problems
+
+**Unsustainable churn:**
+- 6% monthly logo churn = ~50% annual (crisis level)
+- 10% monthly revenue churn = ~69% annual (existential threat)
+- Revenue churn > logo churn = losing high-value customers
+- Churn rate increasing (was 4% six months ago)
+
+**Cohort degradation:**
+- Newer customers churn faster than older customers
+- Month 6 retention: 75% → 65% → on track for 58%
+- This signals product-market fit is getting WORSE, not better
+
+**No expansion engine:**
+- Expansion revenue only 1% of MRR (should be 10-30%)
+- NRR at 89% (contracting, not expanding)
+- Only 5% of customers have ever expanded
+
+**Leaky bucket:**
+- Quick Ratio 1.75 (barely exceeding losses)
+- Losing $60K/month, only gaining $105K/month
+- Running on a treadmill: need 200 new customers/month just to stay flat
+
+**Revenue dependency:**
+- 90% of growth from new customer acquisition
+- If acquisition slows, revenue will shrink immediately
+- Retention is broken—scaling will just accelerate the problem
+
+---
+
+### 📊 Root Cause Investigation Needed
+
+**Why is churn increasing?**
+- Product quality degrading?
+- Wrong customer segment (poor fit)?
+- Onboarding failures?
+- Competitive pressure?
+- Pricing too high for value delivered?
+
+**Why are newer cohorts worse?**
+- Customer acquisition quality degrading?
+- Product changes breaking key use cases?
+- Support quality declining as company scales?
+
+**Why no expansion?**
+- No upsell paths in packaging?
+- Customers not reaching "aha moment" where they'd expand?
+- Product doesn't grow with customer needs?
+
+---
+
+## Actions Recommended (URGENT)
+
+### 🛑 STOP Scaling Acquisition
+
+Do NOT increase marketing spend until retention is fixed. Scaling a leaky bucket just burns cash faster.
+
+**Why:** At current churn rates, every dollar spent acquiring customers leaks out within 12 months. Fix the bucket first.
+
+---
+
+### 🔥 Priority 1: Fix Retention (Weeks 1-4)
+
+**Investigate churn:**
+1. Run churn interviews with 20-30 churned customers
+2. Segment churn by cohort, use case, customer size
+3. Identify top 3 churn reasons
+
+**Quick wins:**
+1. Improve onboarding (70% of churn happens in first 60 days)
+2. Proactive support for at-risk accounts (identify usage drop-offs)
+3. Re-engage dormant accounts before they churn
+
+**Goal:** Reduce logo churn from 6% to 4% within 8 weeks, target 3% within 16 weeks.
+
+---
+
+### 🔥 Priority 2: Build Expansion Engine (Weeks 5-8)
+
+**Create upsell paths:**
+1. Introduce premium tier (advanced features)
+2. Usage-based add-ons (additional seats, integrations)
+3. Cross-sell complementary features
+
+**Identify expansion candidates:**
+1. Which customers use product heavily? (Target for upsell)
+2. Which customers hit usage limits? (Offer expansion)
+
+**Goal:** Increase expansion MRR from 1% to 5% of base within 12 weeks.
+
+---
+
+### 🔥 Priority 3: Improve Cohort Retention (Ongoing)
+
+**Track cohorts rigorously:**
+1. Weekly cohort retention dashboards
+2. Compare new cohorts to baseline (75% at Month 6)
+3. Don't scale until new cohorts retain BETTER than old cohorts
+
+**Product improvements:**
+1. Fix onboarding (time-to-value)
+2. Improve core use cases (reduce churn reasons)
+3. Add sticky features (integrations, data accumulation)
+
+**Goal:** Reverse cohort degradation trend within 16 weeks. New cohorts should retain at 75%+ by Month 6.
+
+---
+
+### ✅ Success Criteria (Fix Before Scaling)
+
+Do NOT scale acquisition until:
+- [ ] Logo churn <4% monthly (ideally <3%)
+- [ ] Revenue churn <5% monthly
+- [ ] NRR >100% (expansion exceeds churn)
+- [ ] Quick Ratio >2.5 (ideally >4)
+- [ ] New cohorts retain same or better than old cohorts
+- [ ] Expansion MRR >5% of total MRR
+
+**Timeline:** 12-16 weeks to fix. Then reassess scaling.
+
+---
+
+## Financial Impact of Fixing Retention
+
+**Current state (bad):**
+- Need 200 new customers/month just to offset churn
+- Net growth: only 80 customers/month after churn
+- 90% of acquisition spend wasted on replacing churned customers
+
+**If churn fixed to 3% (good):**
+- Need 60 new customers/month to offset churn
+- Net growth: 140 customers/month (75% more efficient)
+- Acquisition budget goes 3x further
+
+**If NRR fixed to 110% (great):**
+- Existing base grows 10%/year without new customers
+- All new acquisition is net growth
+- Can afford higher CAC because LTV increases 2-3x
+
+**Bottom line:** Fixing retention is worth 6-12 months of paused growth. Don't skip this.

package/src/modules/product/skills/saas-revenue-growth-metrics/template.md

@@ -0,0 +1,192 @@
+# SaaS Revenue & Growth Metrics Calculator
+
+Use this template to calculate your revenue and retention metrics. Fill in your numbers and calculate each metric.
+
+---
+
+## Revenue Metrics
+
+### Revenue
+```
+Period: [Month/Quarter/Year]
+Total Customer Payments: $__________
+Revenue = $__________
+```
+
+### ARPU (Average Revenue Per User)
+```
+Total Revenue: $__________
+Total Users: __________
+ARPU = Total Revenue / Total Users = $__________
+```
+
+### ARPA (Average Revenue Per Account)
+```
+MRR: $__________
+Active Accounts: __________
+ARPA = MRR / Active Accounts = $__________
+```
+
+### ARPA/ARPU Analysis
+```
+ARPA: $__________
+ARPU: $__________
+Average Seats per Account = ARPA / ARPU = __________
+```
+
+### ACV (Annual Contract Value)
+```
+Annual Recurring Revenue per Contract: $__________
+(Exclude one-time fees like setup, professional services)
+ACV = $__________
+```
+
+### MRR/ARR
+```
+Starting MRR: $__________
+
+MRR Components:
++ New MRR (new customers): $__________
++ Expansion MRR (upsells/cross-sells): $__________
+- Churned MRR (lost customers): $__________
+- Contraction MRR (downgrades): $__________
+
+Ending MRR: $__________
+ARR = MRR × 12 = $__________
+```
+
+### Gross vs. Net Revenue
+```
+Gross Revenue: $__________
+- Discounts: $__________
+- Refunds: $__________
+- Credits: $__________
+Net Revenue = $__________
+
+Discount Rate = Discounts / Gross Revenue = __________%
+Refund Rate = Refunds / Gross Revenue = __________%
+```
+
+---
+
+## Retention & Expansion Metrics
+
+### Churn Rate (Monthly)
+```
+Logo Churn:
+Starting Customers: __________
+Customers Lost: __________
+Logo Churn Rate = Customers Lost / Starting Customers = __________%
+
+Revenue Churn:
+Starting MRR: $__________
+MRR Lost: $__________
+Revenue Churn Rate = MRR Lost / Starting MRR = __________%
+```
+
+**Convert to Annual Churn:**
+```
+Monthly Churn Rate: __________%
+Annual Churn Rate = 1 - (1 - Monthly Churn)^12 = __________%
+```
+
+### NRR (Net Revenue Retention)
+```
+Starting ARR: $__________
++ Expansion Revenue: $__________
+- Churned Revenue: $__________
+- Contraction Revenue: $__________
+Ending ARR (from cohort): $__________
+
+NRR = Ending ARR / Starting ARR × 100 = __________%
+```
+
+### Expansion Revenue
+```
+Upsells (tier upgrades): $__________
+Cross-sells (add-ons): $__________
+Usage growth: $__________
+Total Expansion Revenue: $__________
+
+Expansion as % of MRR = Expansion / Total MRR = __________%
+```
+
+### Quick Ratio
+```
+New MRR: $__________
+Expansion MRR: $__________
+Churned MRR: $__________
+Contraction MRR: $__________
+
+Quick Ratio = (New MRR + Expansion MRR) / (Churned MRR + Contraction MRR)
+Quick Ratio = __________
+```
+
+---
+
+## Analysis Frameworks
+
+### Revenue Mix Analysis
+```
+Product/Segment A Revenue: $__________
+Product/Segment B Revenue: $__________
+Product/Segment C Revenue: $__________
+Total Revenue: $__________
+
+Product A % = __________
+Product B % = __________
+Product C % = __________
+```
+
+### Cohort Retention Analysis
+```
+Cohort: [Month/Quarter]
+Starting Customers: __________
+
+Month 0: 100%
+Month 1: __________%
+Month 2: __________%
+Month 3: __________%
+Month 6: __________%
+Month 12: __________%
+```
+
+---
+
+## Benchmarks & Quality Checks
+
+### Revenue Metrics
+- [ ] Gross vs. net revenue clearly labeled
+- [ ] Revenue growth rate > cost growth rate
+- [ ] ARPU/ARPA tracked by cohort (not just blended)
+- [ ] Revenue concentration: Top customer <10%, Top 10 <40%
+
+### Retention Metrics
+- [ ] Monthly churn <5% (ideally <2%)
+- [ ] Revenue churn vs. logo churn compared
+- [ ] NRR >100% (ideally >120%)
+- [ ] Quick Ratio >2 (ideally >4)
+
+### Cohort Analysis
+- [ ] Recent cohorts perform same or better than older cohorts
+- [ ] Revenue retention tracked, not just logo retention
+- [ ] Expansion analyzed by cohort
+
+---
+
+## Red Flags
+
+Check if any of these apply:
+
+- [ ] Revenue churn > logo churn (losing big customers)
+- [ ] ARPU growing but customer count shrinking (mix shift, not improvement)
+- [ ] Newer cohorts churn faster than older cohorts (PMF degradation)
+- [ ] NRR <100% (contracting, not expanding)
+- [ ] Quick Ratio <2 (leaky bucket)
+- [ ] Discounts >20% or refunds >10% (pricing/product problems)
+- [ ] Revenue concentration >50% in top 10 customers (risk)
+- [ ] Expansion revenue <10% of total MRR (monetization problem)
+
+---
+
+**If you checked any red flags, see SKILL.md Common Pitfalls section for fixes.**