autodoc-agent-kit 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (187) hide show
  1. package/README.md +362 -0
  2. package/package.json +49 -0
  3. package/src/core/module.yaml +5 -0
  4. package/src/modules/design/module.yaml +9 -0
  5. package/src/modules/design/skills/brand-guidelines/LICENSE.txt +202 -0
  6. package/src/modules/design/skills/brand-guidelines/SKILL.md +73 -0
  7. package/src/modules/design/skills/frontend-design/LICENSE.txt +177 -0
  8. package/src/modules/design/skills/frontend-design/SKILL.md +42 -0
  9. package/src/modules/design/skills/web-artifacts-builder/SKILL.md +229 -0
  10. package/src/modules/devops/module.yaml +10 -0
  11. package/src/modules/devops/skills/devops-helper/SKILL.md +60 -0
  12. package/src/modules/devops/skills/k8s-helm/SKILL.md +360 -0
  13. package/src/modules/devops/skills/monitoring-observability/SKILL.md +240 -0
  14. package/src/modules/devops/skills/security-auditor/SKILL.md +105 -0
  15. package/src/modules/engineering/module.yaml +22 -0
  16. package/src/modules/engineering/skills/ai-sdk/SKILL.md +314 -0
  17. package/src/modules/engineering/skills/api-designer/SKILL.md +77 -0
  18. package/src/modules/engineering/skills/code-reviewer/SKILL.md +71 -0
  19. package/src/modules/engineering/skills/db-architect/SKILL.md +50 -0
  20. package/src/modules/engineering/skills/debugger/SKILL.md +59 -0
  21. package/src/modules/engineering/skills/docs-generator/SKILL.md +51 -0
  22. package/src/modules/engineering/skills/git-workflow/SKILL.md +258 -0
  23. package/src/modules/engineering/skills/mcp-builder/LICENSE.txt +202 -0
  24. package/src/modules/engineering/skills/mcp-builder/SKILL.md +236 -0
  25. package/src/modules/engineering/skills/mcp-builder/reference/evaluation.md +602 -0
  26. package/src/modules/engineering/skills/mcp-builder/reference/mcp_best_practices.md +249 -0
  27. package/src/modules/engineering/skills/mcp-builder/reference/node_mcp_server.md +970 -0
  28. package/src/modules/engineering/skills/mcp-builder/reference/python_mcp_server.md +719 -0
  29. package/src/modules/engineering/skills/mcp-builder/scripts/connections.py +151 -0
  30. package/src/modules/engineering/skills/mcp-builder/scripts/evaluation.py +373 -0
  31. package/src/modules/engineering/skills/mcp-builder/scripts/example_evaluation.xml +22 -0
  32. package/src/modules/engineering/skills/mcp-builder/scripts/requirements.txt +2 -0
  33. package/src/modules/engineering/skills/nextjs-15/SKILL.md +312 -0
  34. package/src/modules/engineering/skills/perf-optimizer/SKILL.md +60 -0
  35. package/src/modules/engineering/skills/react-19/SKILL.md +257 -0
  36. package/src/modules/engineering/skills/refactorer/SKILL.md +60 -0
  37. package/src/modules/engineering/skills/skill-authoring-workflow/SKILL.md +183 -0
  38. package/src/modules/engineering/skills/skill-creator/LICENSE.txt +202 -0
  39. package/src/modules/engineering/skills/skill-creator/SKILL.md +356 -0
  40. package/src/modules/engineering/skills/skill-creator/references/output-patterns.md +82 -0
  41. package/src/modules/engineering/skills/skill-creator/references/workflows.md +28 -0
  42. package/src/modules/engineering/skills/skill-creator/scripts/__pycache__/quick_validate.cpython-313.pyc +0 -0
  43. package/src/modules/engineering/skills/skill-creator/scripts/init_skill.py +303 -0
  44. package/src/modules/engineering/skills/skill-creator/scripts/package_skill.py +110 -0
  45. package/src/modules/engineering/skills/skill-creator/scripts/quick_validate.py +95 -0
  46. package/src/modules/engineering/skills/typescript/SKILL.md +231 -0
  47. package/src/modules/engineering/skills/zod-4/SKILL.md +223 -0
  48. package/src/modules/product/module.yaml +51 -0
  49. package/src/modules/product/skills/acquisition-channel-advisor/SKILL.md +643 -0
  50. package/src/modules/product/skills/acquisition-channel-advisor/examples/conversation-flow.md +531 -0
  51. package/src/modules/product/skills/ai-shaped-readiness-advisor/SKILL.md +923 -0
  52. package/src/modules/product/skills/altitude-horizon-framework/SKILL.md +250 -0
  53. package/src/modules/product/skills/altitude-horizon-framework/examples/sample.md +85 -0
  54. package/src/modules/product/skills/business-health-diagnostic/SKILL.md +783 -0
  55. package/src/modules/product/skills/company-research/SKILL.md +385 -0
  56. package/src/modules/product/skills/company-research/examples/sample.md +164 -0
  57. package/src/modules/product/skills/company-research/template.md +60 -0
  58. package/src/modules/product/skills/context-engineering-advisor/SKILL.md +763 -0
  59. package/src/modules/product/skills/customer-journey-map/SKILL.md +346 -0
  60. package/src/modules/product/skills/customer-journey-map/examples/meta-product-manager-skills.md +40 -0
  61. package/src/modules/product/skills/customer-journey-map/examples/sample.md +33 -0
  62. package/src/modules/product/skills/customer-journey-map/template.md +28 -0
  63. package/src/modules/product/skills/customer-journey-mapping-workshop/SKILL.md +523 -0
  64. package/src/modules/product/skills/director-readiness-advisor/SKILL.md +351 -0
  65. package/src/modules/product/skills/director-readiness-advisor/examples/conversation-flow.md +96 -0
  66. package/src/modules/product/skills/discovery-interview-prep/SKILL.md +410 -0
  67. package/src/modules/product/skills/discovery-process/SKILL.md +504 -0
  68. package/src/modules/product/skills/discovery-process/examples/sample.md +60 -0
  69. package/src/modules/product/skills/discovery-process/template.md +39 -0
  70. package/src/modules/product/skills/eol-message/SKILL.md +348 -0
  71. package/src/modules/product/skills/eol-message/examples/sample.md +87 -0
  72. package/src/modules/product/skills/eol-message/template.md +74 -0
  73. package/src/modules/product/skills/epic-breakdown-advisor/SKILL.md +665 -0
  74. package/src/modules/product/skills/epic-hypothesis/SKILL.md +277 -0
  75. package/src/modules/product/skills/epic-hypothesis/examples/sample.md +104 -0
  76. package/src/modules/product/skills/epic-hypothesis/template.md +30 -0
  77. package/src/modules/product/skills/executive-onboarding-playbook/SKILL.md +280 -0
  78. package/src/modules/product/skills/executive-onboarding-playbook/examples/sample.md +116 -0
  79. package/src/modules/product/skills/feature-investment-advisor/SKILL.md +639 -0
  80. package/src/modules/product/skills/feature-investment-advisor/examples/conversation-flow.md +538 -0
  81. package/src/modules/product/skills/finance-based-pricing-advisor/SKILL.md +763 -0
  82. package/src/modules/product/skills/finance-metrics-quickref/SKILL.md +309 -0
  83. package/src/modules/product/skills/jobs-to-be-done/SKILL.md +370 -0
  84. package/src/modules/product/skills/jobs-to-be-done/examples/sample.md +80 -0
  85. package/src/modules/product/skills/jobs-to-be-done/template.md +65 -0
  86. package/src/modules/product/skills/lean-ux-canvas/SKILL.md +561 -0
  87. package/src/modules/product/skills/lean-ux-canvas/examples/sample.md +88 -0
  88. package/src/modules/product/skills/lean-ux-canvas/template.md +32 -0
  89. package/src/modules/product/skills/opportunity-solution-tree/SKILL.md +420 -0
  90. package/src/modules/product/skills/opportunity-solution-tree/examples/sample.md +104 -0
  91. package/src/modules/product/skills/opportunity-solution-tree/template.md +33 -0
  92. package/src/modules/product/skills/pestel-analysis/SKILL.md +376 -0
  93. package/src/modules/product/skills/pestel-analysis/examples/sample.md +143 -0
  94. package/src/modules/product/skills/pestel-analysis/template.md +53 -0
  95. package/src/modules/product/skills/pol-probe/SKILL.md +217 -0
  96. package/src/modules/product/skills/pol-probe/examples/sample.md +136 -0
  97. package/src/modules/product/skills/pol-probe/template.md +59 -0
  98. package/src/modules/product/skills/pol-probe-advisor/SKILL.md +492 -0
  99. package/src/modules/product/skills/positioning-statement/SKILL.md +230 -0
  100. package/src/modules/product/skills/positioning-statement/examples/sample.md +51 -0
  101. package/src/modules/product/skills/positioning-statement/template.md +25 -0
  102. package/src/modules/product/skills/positioning-workshop/SKILL.md +424 -0
  103. package/src/modules/product/skills/prd-development/SKILL.md +655 -0
  104. package/src/modules/product/skills/prd-development/examples/sample.md +43 -0
  105. package/src/modules/product/skills/prd-development/template.md +55 -0
  106. package/src/modules/product/skills/press-release/SKILL.md +269 -0
  107. package/src/modules/product/skills/press-release/examples/sample.md +73 -0
  108. package/src/modules/product/skills/press-release/template.md +39 -0
  109. package/src/modules/product/skills/prioritization-advisor/SKILL.md +448 -0
  110. package/src/modules/product/skills/problem-framing-canvas/SKILL.md +466 -0
  111. package/src/modules/product/skills/problem-framing-canvas/examples/sample.md +58 -0
  112. package/src/modules/product/skills/problem-framing-canvas/template.md +22 -0
  113. package/src/modules/product/skills/problem-statement/SKILL.md +246 -0
  114. package/src/modules/product/skills/problem-statement/examples/sample.md +82 -0
  115. package/src/modules/product/skills/problem-statement/template.md +37 -0
  116. package/src/modules/product/skills/product-strategy-session/SKILL.md +426 -0
  117. package/src/modules/product/skills/product-strategy-session/examples/sample.md +67 -0
  118. package/src/modules/product/skills/product-strategy-session/template.md +38 -0
  119. package/src/modules/product/skills/proto-persona/SKILL.md +326 -0
  120. package/src/modules/product/skills/proto-persona/examples/sample.md +97 -0
  121. package/src/modules/product/skills/proto-persona/template.md +45 -0
  122. package/src/modules/product/skills/recommendation-canvas/SKILL.md +375 -0
  123. package/src/modules/product/skills/recommendation-canvas/examples/sample.md +94 -0
  124. package/src/modules/product/skills/recommendation-canvas/template.md +86 -0
  125. package/src/modules/product/skills/roadmap-planning/SKILL.md +505 -0
  126. package/src/modules/product/skills/roadmap-planning/examples/sample.md +62 -0
  127. package/src/modules/product/skills/roadmap-planning/template.md +30 -0
  128. package/src/modules/product/skills/saas-economics-efficiency-metrics/SKILL.md +694 -0
  129. package/src/modules/product/skills/saas-economics-efficiency-metrics/examples/cash-trap.md +365 -0
  130. package/src/modules/product/skills/saas-economics-efficiency-metrics/examples/healthy-unit-economics.md +279 -0
  131. package/src/modules/product/skills/saas-economics-efficiency-metrics/template.md +263 -0
  132. package/src/modules/product/skills/saas-revenue-growth-metrics/SKILL.md +630 -0
  133. package/src/modules/product/skills/saas-revenue-growth-metrics/examples/healthy-saas.md +131 -0
  134. package/src/modules/product/skills/saas-revenue-growth-metrics/examples/warning-signs.md +229 -0
  135. package/src/modules/product/skills/saas-revenue-growth-metrics/template.md +192 -0
  136. package/src/modules/product/skills/storyboard/SKILL.md +252 -0
  137. package/src/modules/product/skills/storyboard/examples/sample.md +71 -0
  138. package/src/modules/product/skills/storyboard/template.md +41 -0
  139. package/src/modules/product/skills/tam-sam-som-calculator/SKILL.md +392 -0
  140. package/src/modules/product/skills/tam-sam-som-calculator/examples/sample.md +142 -0
  141. package/src/modules/product/skills/tam-sam-som-calculator/scripts/market-sizing.py +95 -0
  142. package/src/modules/product/skills/tam-sam-som-calculator/template.md +35 -0
  143. package/src/modules/product/skills/user-story/SKILL.md +272 -0
  144. package/src/modules/product/skills/user-story/examples/sample.md +110 -0
  145. package/src/modules/product/skills/user-story/scripts/user-story-template.py +65 -0
  146. package/src/modules/product/skills/user-story/template.md +32 -0
  147. package/src/modules/product/skills/user-story-mapping/SKILL.md +285 -0
  148. package/src/modules/product/skills/user-story-mapping/examples/sample.md +77 -0
  149. package/src/modules/product/skills/user-story-mapping/template.md +41 -0
  150. package/src/modules/product/skills/user-story-mapping-workshop/SKILL.md +477 -0
  151. package/src/modules/product/skills/user-story-mapping-workshop/template.md +28 -0
  152. package/src/modules/product/skills/user-story-splitting/SKILL.md +303 -0
  153. package/src/modules/product/skills/user-story-splitting/examples/sample.md +147 -0
  154. package/src/modules/product/skills/user-story-splitting/template.md +37 -0
  155. package/src/modules/product/skills/vp-cpo-readiness-advisor/SKILL.md +409 -0
  156. package/src/modules/product/skills/vp-cpo-readiness-advisor/examples/conversation-flow.md +95 -0
  157. package/src/modules/product/skills/workshop-facilitation/SKILL.md +87 -0
  158. package/src/modules/productivity/module.yaml +9 -0
  159. package/src/modules/productivity/skills/doc-coauthoring/SKILL.md +375 -0
  160. package/src/modules/productivity/skills/internal-comms/LICENSE.txt +202 -0
  161. package/src/modules/productivity/skills/internal-comms/SKILL.md +32 -0
  162. package/src/modules/productivity/skills/internal-comms/examples/3p-updates.md +47 -0
  163. package/src/modules/productivity/skills/internal-comms/examples/company-newsletter.md +65 -0
  164. package/src/modules/productivity/skills/internal-comms/examples/faq-answers.md +30 -0
  165. package/src/modules/productivity/skills/internal-comms/examples/general-comms.md +16 -0
  166. package/src/modules/productivity/skills/technical-writing/SKILL.md +266 -0
  167. package/src/modules/qa/module.yaml +9 -0
  168. package/src/modules/qa/skills/test-strategy/SKILL.md +263 -0
  169. package/src/modules/qa/skills/test-writer/SKILL.md +57 -0
  170. package/src/modules/qa/skills/webapp-testing/LICENSE.txt +202 -0
  171. package/src/modules/qa/skills/webapp-testing/SKILL.md +96 -0
  172. package/src/modules/qa/skills/webapp-testing/examples/console_logging.py +35 -0
  173. package/src/modules/qa/skills/webapp-testing/examples/element_discovery.py +40 -0
  174. package/src/modules/qa/skills/webapp-testing/examples/static_html_automation.py +33 -0
  175. package/src/modules/qa/skills/webapp-testing/scripts/with_server.py +106 -0
  176. package/tools/autodoc-npx-wrapper.js +34 -0
  177. package/tools/cli/autodoc-cli.js +55 -0
  178. package/tools/cli/commands/install.js +36 -0
  179. package/tools/cli/commands/status.js +35 -0
  180. package/tools/cli/commands/uninstall.js +60 -0
  181. package/tools/cli/installers/lib/core/installer.js +164 -0
  182. package/tools/cli/installers/lib/core/manifest.js +49 -0
  183. package/tools/cli/installers/lib/ide/manager.js +112 -0
  184. package/tools/cli/installers/lib/ide/platform-codes.yaml +207 -0
  185. package/tools/cli/installers/lib/modules/manager.js +59 -0
  186. package/tools/cli/lib/ui.js +199 -0
  187. package/tools/cli/lib/welcome.js +82 -0
@@ -0,0 +1,630 @@
1
+ ---
2
+ name: saas-revenue-growth-metrics
3
+ description: Calculate SaaS revenue, retention, and growth metrics. Use when diagnosing momentum, churn, expansion, or product-market-fit signals.
4
+ intent: >-
5
+ Master revenue and retention metrics to understand SaaS business momentum, evaluate product-market fit, and make data-driven decisions about growth investments. Use this to calculate key metrics, interpret trends, identify problems early, and communicate business health to stakeholders.
6
+ type: component
7
+ theme: finance-metrics
8
+ best_for:
9
+ - "Understanding your key revenue and retention metrics"
10
+ - "Calculating MRR, ARR, churn, and NRR correctly"
11
+ - "Building a metrics dashboard for your SaaS product"
12
+ scenarios:
13
+ - "I need to calculate and interpret our MRR, churn rate, and NRR for a board deck"
14
+ - "Help me understand the difference between gross and net revenue retention and how to improve it"
15
+ estimated_time: "10-15 min"
16
+ ---
17
+
18
+
19
+ ## Purpose
20
+
21
+ Master revenue and retention metrics to understand SaaS business momentum, evaluate product-market fit, and make data-driven decisions about growth investments. Use this to calculate key metrics, interpret trends, identify problems early, and communicate business health to stakeholders.
22
+
23
+ This is not a business intelligence tool—it's a framework for PMs to understand which metrics matter, how to calculate them correctly, and what actions to take based on the numbers.
24
+
25
+ ## Key Concepts
26
+
27
+ ### Revenue Metrics Family
28
+
29
+ The "top-line" metrics that measure how much money the business generates.
30
+
31
+ **Revenue** — Total money earned from selling products/services before expenses. The "top line" of the income statement.
32
+ - **Why PMs care:** Every feature should connect to revenue (direct or indirect). If you can't articulate revenue impact, prioritization becomes impossible.
33
+ - **Formula:** Sum of all customer payments in a period
34
+ - **Benchmark:** Growth rate matters more than absolute number (context-dependent by stage)
35
+
36
+ **ARPU (Average Revenue Per User)** — Average revenue generated per individual user.
37
+ - **Why PMs care:** Measures per-seat monetization effectiveness. Critical for seat-based pricing models.
38
+ - **Formula:** `Total Revenue / Total Users`
39
+ - **Benchmark:** Varies by model; track trend more than absolute value
40
+ - **B2C SaaS:** $5-50/month typical; B2B: $50-500+/month
41
+
42
+ **ARPA (Average Revenue Per Account)** — Average revenue generated per customer account.
43
+ - **Why PMs care:** Measures account-level deal size. Critical for account-based pricing models.
44
+ - **Formula:** `MRR / Active Accounts`
45
+ - **Benchmark:** SMB SaaS: $100-$1K/month; Mid-market: $1K-$10K; Enterprise: $10K+
46
+
47
+ **ARPA/ARPU Analysis** — Using both metrics together to understand monetization.
48
+ - **Why PMs care:** Prevents packaging mistakes. High ARPA + low ARPU = undermonetized per seat. Low ARPA + high ARPU = small deal sizes.
49
+ - **Example:** $10K ARPA with 100 seats = $100 ARPU (reasonable). $10K ARPA with 1,000 seats = $10 ARPU (leaving money on table).
50
+
51
+ **ACV (Annual Contract Value)** — Annualized recurring revenue per contract (excludes one-time fees).
52
+ - **Why PMs care:** Compares economics across different contract structures. Enables sales compensation design and segment analysis.
53
+ - **Formula:** `Annual Recurring Revenue per Contract` (don't include setup fees, professional services)
54
+ - **Benchmark:** SMB: $5K-$25K; Mid-market: $25K-$100K; Enterprise: $100K+
55
+
56
+ **MRR/ARR (Monthly/Annual Recurring Revenue)** — Predictable recurring revenue normalized to monthly or annual.
57
+ - **Why PMs care:** The heartbeat of subscription businesses. Valued at 5-10x+ multiples. Track components (new, expansion, churn).
58
+ - **Formula:** `MRR = Sum of all recurring subscription revenue per month`; `ARR = MRR × 12`
59
+ - **Benchmark:** Growth rate and quality matter; track new MRR, expansion MRR, churned MRR, contracted MRR
60
+
61
+ **Gross vs. Net Revenue** — Gross revenue before vs. net revenue after discounts, refunds, credits.
62
+ - **Why PMs care:** Discounts and refunds can hide bad acquisition quality or product problems.
63
+ - **Formula:** `Net Revenue = Gross Revenue - Discounts - Refunds - Credits`
64
+ - **Benchmark:** Refunds >10% is a red flag; track by acquisition channel
65
+
66
+ ---
67
+
68
+ ### Retention & Expansion Metrics Family
69
+
70
+ Metrics that measure how well you keep and grow existing customers.
71
+
72
+ **Churn Rate** — Percentage of customers who cancel in a period.
73
+ - **Why PMs care:** Silent killer of SaaS. Undermines all acquisition efforts. 5% monthly churn = 46% annual churn (compounding).
74
+ - **Formula:** `Customers Lost in Period / Starting Customers`
75
+ - **Benchmark (Monthly):** <2% great, 2-5% acceptable, >5% crisis
76
+ - **Benchmark (Annual):** <10% great, 10-30% acceptable, >30% crisis
77
+ - **Note:** Logo churn (customer count) differs from revenue churn (dollar amount)
78
+
79
+ **NRR (Net Revenue Retention)** — Revenue retention from existing customers including expansion and contraction.
80
+ - **Why PMs care:** The holy grail metric. NRR >100% means you grow without new logos. Highly valued by investors.
81
+ - **Formula:** `(Starting ARR + Expansion - Churn - Contraction) / Starting ARR × 100`
82
+ - **Benchmark:** >120% excellent, 100-120% good, 90-100% acceptable, <90% problem
83
+ - **Example:** Start with $1M ARR, add $300K expansion, lose $100K to churn = $1.2M / $1M = 120% NRR
84
+
85
+ **Expansion Revenue** — Additional revenue from existing customers (upsells, cross-sells, usage growth).
86
+ - **Why PMs care:** Most capital-efficient revenue (no CAC). Should drive NRR >100%.
87
+ - **Formula:** `Sum of upsells + cross-sells + usage increases from existing customers`
88
+ - **Benchmark:** Should represent 20-30% of total revenue; drives NRR >100%
89
+
90
+ **Quick Ratio (SaaS)** — Revenue gains vs. revenue losses.
91
+ - **Why PMs care:** Shows if you're building on solid ground or running on a treadmill.
92
+ - **Formula:** `(New MRR + Expansion MRR) / (Churned MRR + Contraction MRR)`
93
+ - **Benchmark:** >4 excellent, 2-4 healthy, <2 leaky bucket
94
+
95
+ ---
96
+
97
+ ### Analysis Frameworks
98
+
99
+ **Revenue Mix Analysis** — Breakdown of revenue by product, segment, or channel.
100
+ - **Why PMs care:** Identifies which products fund the business and where to invest. Reveals concentration risk.
101
+ - **Formula:** `Product/Segment Revenue / Total Revenue × 100`
102
+ - **Benchmark:** No single product >60% ideal; diversification reduces risk
103
+
104
+ **Cohort Analysis** — Group customers by join date and track behavior over time.
105
+ - **Why PMs care:** Blended metrics hide critical trends. Shows whether business is improving or degrading.
106
+ - **Method:** Track retention, expansion, and LTV by cohort (e.g., "Jan 2024 cohort")
107
+ - **Benchmark:** Recent cohorts should perform same or better than old cohorts
108
+
109
+ ---
110
+
111
+ ### Anti-Patterns (What This Is NOT)
112
+
113
+ - **Not profit metrics:** Revenue is top-line, not bottom-line. High revenue with negative margins is a disaster.
114
+ - **Not vanity metrics:** Total revenue growth means nothing if driven by unsustainable discounting or margin-destroying deals.
115
+ - **Not blended averages:** ARPU that averages $10 SMB and $1,000 enterprise customers hides segment economics.
116
+ - **Not isolated numbers:** Churn rate alone doesn't tell the story—need to see cohort trends and NRR.
117
+
118
+ ---
119
+
120
+ ### When to Use These Metrics
121
+
122
+ **Use these when:**
123
+ - Evaluating overall business health and product-market fit
124
+ - Comparing performance across time periods or cohorts
125
+ - Prioritizing features with direct monetization paths (ARPU impact, expansion enablers)
126
+ - Communicating with leadership, board, or investors
127
+ - Assessing retention problems (churn analysis, cohort degradation)
128
+ - Measuring pricing or packaging changes (ARPU/ARPA shifts)
129
+
130
+ **Don't use these when:**
131
+ - Evaluating profitability (use margin metrics instead)
132
+ - Assessing capital efficiency (use LTV:CAC, payback period)
133
+ - Making product investment decisions without cost context (revenue alone isn't ROI)
134
+ - Comparing across wildly different business models without normalization
135
+
136
+ ---
137
+
138
+ ## Application
139
+
140
+ ### Step 1: Calculate Revenue Metrics
141
+
142
+ Use the templates in `template.md` to calculate your core revenue metrics.
143
+
144
+ #### Revenue
145
+ ```
146
+ Revenue = Sum of all customer payments in period
147
+ ```
148
+
149
+ **Example:**
150
+ - Month 1 payments: $100,000
151
+ - Revenue = $100,000
152
+
153
+ **Quality checks:**
154
+ - Is this gross or net revenue? (Clarify if discounts/refunds are included)
155
+ - Is revenue growing cohort-over-cohort, or just from new customer adds?
156
+ - What's the revenue growth rate vs. headcount/cost growth rate?
157
+
158
+ ---
159
+
160
+ #### ARPU (Average Revenue Per User)
161
+ ```
162
+ ARPU = Total Revenue / Total Users
163
+ ```
164
+
165
+ **Example:**
166
+ - Total Revenue: $100,000/month
167
+ - Total Users: 2,000
168
+ - ARPU = $100,000 / 2,000 = $50/user/month
169
+
170
+ **Quality checks:**
171
+ - Is ARPU growing or shrinking over time?
172
+ - Is ARPU growth from price increases or mix shift (losing small customers)?
173
+ - How does ARPU vary by cohort? (Are new customers less valuable?)
174
+
175
+ ---
176
+
177
+ #### ARPA (Average Revenue Per Account)
178
+ ```
179
+ ARPA = MRR / Active Accounts
180
+ ```
181
+
182
+ **Example:**
183
+ - MRR: $100,000
184
+ - Active Accounts: 200
185
+ - ARPA = $100,000 / 200 = $500/account/month
186
+
187
+ **Quality checks:**
188
+ - Is ARPA growing from expansion or just larger new deals?
189
+ - How does ARPA compare across customer segments?
190
+ - Is ARPA high but ARPU low? (Undermonetized per seat)
191
+
192
+ ---
193
+
194
+ #### ARPA/ARPU Combined Analysis
195
+ ```
196
+ ARPA = MRR / Active Accounts
197
+ ARPU = MRR / Total Users
198
+ Average Seats per Account = ARPA / ARPU
199
+ ```
200
+
201
+ **Example:**
202
+ - ARPA: $500/month
203
+ - ARPU: $50/month
204
+ - Average Seats: $500 / $50 = 10 seats/account
205
+
206
+ **Quality checks:**
207
+ - Are you monetizing per seat effectively?
208
+ - Could you charge more per seat (raise ARPU)?
209
+ - Could you expand seat count per account (raise ARPA)?
210
+
211
+ ---
212
+
213
+ #### ACV (Annual Contract Value)
214
+ ```
215
+ ACV = Annual Recurring Revenue per Contract
216
+ (Exclude one-time fees like setup, professional services)
217
+ ```
218
+
219
+ **Example:**
220
+ - Customer signs 3-year contract for $300K total
221
+ - ACV = $300K / 3 years = $100K/year
222
+
223
+ **Quality checks:**
224
+ - How does ACV vary by segment (SMB vs. Enterprise)?
225
+ - Is ACV growing over time (moving upmarket)?
226
+ - Does ACV justify sales team cost structure?
227
+
228
+ ---
229
+
230
+ #### MRR/ARR (Monthly/Annual Recurring Revenue)
231
+ ```
232
+ MRR = Sum of all recurring monthly subscriptions
233
+ ARR = MRR × 12
234
+
235
+ Track components:
236
+ - New MRR (from new customers)
237
+ - Expansion MRR (from upsells/cross-sells)
238
+ - Churned MRR (from lost customers)
239
+ - Contraction MRR (from downgrades)
240
+ ```
241
+
242
+ **Example:**
243
+ - Starting MRR: $500K
244
+ - New MRR: +$50K
245
+ - Expansion MRR: +$20K
246
+ - Churned MRR: -$15K
247
+ - Contraction MRR: -$5K
248
+ - Ending MRR: $550K
249
+ - ARR = $550K × 12 = $6.6M
250
+
251
+ **Quality checks:**
252
+ - Is MRR growth from new customers or expansion?
253
+ - Is churn/contraction increasing as you grow?
254
+ - What's the ratio of new:expansion:churn MRR? (Best: expansion > new)
255
+
256
+ ---
257
+
258
+ #### Gross vs. Net Revenue
259
+ ```
260
+ Net Revenue = Gross Revenue - Discounts - Refunds - Credits
261
+ ```
262
+
263
+ **Example:**
264
+ - Gross Revenue: $100K
265
+ - Discounts: -$10K
266
+ - Refunds: -$2K
267
+ - Net Revenue: $88K
268
+
269
+ **Quality checks:**
270
+ - Are discounts >20%? (Pricing power problem)
271
+ - Are refunds >10%? (Product quality problem)
272
+ - Do certain channels have higher discount/refund rates?
273
+
274
+ ---
275
+
276
+ ### Step 2: Calculate Retention & Expansion Metrics
277
+
278
+ #### Churn Rate
279
+ ```
280
+ Logo Churn Rate = Customers Lost / Starting Customers × 100
281
+ Revenue Churn Rate = MRR Lost / Starting MRR × 100
282
+ ```
283
+
284
+ **Example (Logo Churn):**
285
+ - Starting Customers: 1,000
286
+ - Customers Lost: 30
287
+ - Logo Churn = 30 / 1,000 = 3% monthly
288
+
289
+ **Example (Revenue Churn):**
290
+ - Starting MRR: $500K
291
+ - MRR Lost: $15K
292
+ - Revenue Churn = $15K / $500K = 3% monthly
293
+
294
+ **Quality checks:**
295
+ - Is churn rate accelerating or decelerating over time?
296
+ - Are newer cohorts churning faster than older ones? (PMF degradation)
297
+ - Is revenue churn higher than logo churn? (Losing big customers)
298
+
299
+ **Convert monthly to annual:**
300
+ - Monthly churn compounds: 3% monthly ≠ 36% annual
301
+ - Formula: `Annual Churn = 1 - (1 - Monthly Churn)^12`
302
+ - 3% monthly = ~31% annual churn
303
+
304
+ ---
305
+
306
+ #### NRR (Net Revenue Retention)
307
+ ```
308
+ NRR = (Starting ARR + Expansion - Churn - Contraction) / Starting ARR × 100
309
+ ```
310
+
311
+ **Example:**
312
+ - Starting ARR: $5M
313
+ - Expansion: +$800K
314
+ - Churn: -$300K
315
+ - Contraction: -$100K
316
+ - Ending ARR from cohort: $5.4M
317
+ - NRR = $5.4M / $5M = 108%
318
+
319
+ **Quality checks:**
320
+ - Is NRR >100%? (You grow without new logos)
321
+ - Is NRR improving or degrading cohort-over-cohort?
322
+ - What's driving NRR? (Expansion or low churn?)
323
+
324
+ ---
325
+
326
+ #### Expansion Revenue
327
+ ```
328
+ Expansion Revenue = Upsells + Cross-sells + Usage Growth (from existing customers)
329
+ ```
330
+
331
+ **Example:**
332
+ - Upsells to higher tier: $50K/month
333
+ - Cross-sells of add-ons: $20K/month
334
+ - Usage growth: $10K/month
335
+ - Total Expansion Revenue: $80K/month
336
+
337
+ **Quality checks:**
338
+ - Is expansion revenue growing as % of total revenue?
339
+ - What % of customers expand each year? (Expansion rate)
340
+ - Are certain cohorts/segments more likely to expand?
341
+
342
+ ---
343
+
344
+ #### Quick Ratio (SaaS)
345
+ ```
346
+ Quick Ratio = (New MRR + Expansion MRR) / (Churned MRR + Contraction MRR)
347
+ ```
348
+
349
+ **Example:**
350
+ - New MRR: $50K
351
+ - Expansion MRR: $20K
352
+ - Churned MRR: $15K
353
+ - Contraction MRR: $5K
354
+ - Quick Ratio = ($50K + $20K) / ($15K + $5K) = $70K / $20K = 3.5
355
+
356
+ **Quality checks:**
357
+ - Quick Ratio >4 = excellent (gains far exceed losses)
358
+ - Quick Ratio 2-4 = healthy (sustainable growth)
359
+ - Quick Ratio <2 = leaky bucket (fix retention before scaling)
360
+
361
+ ---
362
+
363
+ ### Step 3: Analyze Trends with Frameworks
364
+
365
+ #### Revenue Mix Analysis
366
+ ```
367
+ Product/Segment % = Product/Segment Revenue / Total Revenue × 100
368
+ ```
369
+
370
+ **Example:**
371
+ - Product A Revenue: $300K
372
+ - Product B Revenue: $500K
373
+ - Product C Revenue: $200K
374
+ - Total Revenue: $1M
375
+ - Product A: 30%, Product B: 50%, Product C: 20%
376
+
377
+ **Quality checks:**
378
+ - Is revenue concentration increasing? (Risk: over-reliance on one product)
379
+ - Which products are growing/shrinking?
380
+ - Does revenue mix match your strategic priorities?
381
+
382
+ ---
383
+
384
+ #### Cohort Analysis
385
+ Group customers by when they joined and track metrics over time.
386
+
387
+ **Example:**
388
+ | Cohort | Month 0 | Month 1 | Month 2 | Month 3 | Month 6 |
389
+ |--------|---------|---------|---------|---------|---------|
390
+ | Jan 2024 | 100% | 95% | 92% | 90% | 85% |
391
+ | Feb 2024 | 100% | 94% | 90% | 87% | 80% |
392
+ | Mar 2024 | 100% | 92% | 86% | 82% | - |
393
+
394
+ **Quality checks:**
395
+ - Are recent cohorts retaining better or worse than older cohorts?
396
+ - If worse: Product-market fit is degrading (fix before scaling)
397
+ - If better: Improvements are working (safe to scale)
398
+ - Track revenue retention by cohort, not just logo retention
399
+
400
+ ---
401
+
402
+ ### Step 4: Quality Checks & Benchmarks
403
+
404
+ Before reporting metrics, validate:
405
+
406
+ **Revenue metrics:**
407
+ - ✅ Gross vs. net revenue clearly labeled
408
+ - ✅ Revenue growth rate > cost growth rate
409
+ - ✅ ARPU/ARPA trends analyzed by cohort (not just blended)
410
+
411
+ **Retention metrics:**
412
+ - ✅ Logo churn and revenue churn both tracked
413
+ - ✅ Cohort-over-cohort trends analyzed (not just blended churn)
414
+ - ✅ NRR tracked with components (expansion, churn, contraction)
415
+
416
+ **Analysis:**
417
+ - ✅ Cohort analysis shows retention trends
418
+ - ✅ Revenue mix shows concentration risk
419
+ - ✅ Quick ratio shows growth sustainability
420
+
421
+ ---
422
+
423
+ ## Examples
424
+
425
+ See `examples/` folder for detailed scenarios. Mini examples below:
426
+
427
+ ### Example 1: Healthy SaaS Metrics
428
+
429
+ **Company:** Mid-market project management SaaS
430
+
431
+ **Revenue Metrics:**
432
+ - MRR: $2M (growing 10% month-over-month)
433
+ - ARR: $24M
434
+ - ARPA: $1,200/month (200 accounts)
435
+ - ARPU: $120/month (20,000 users)
436
+ - Average seats: 100 per account
437
+
438
+ **Retention Metrics:**
439
+ - Monthly logo churn: 2%
440
+ - Revenue churn: 1.5% (losing smaller customers)
441
+ - NRR: 115% (strong expansion)
442
+ - Expansion revenue: $200K/month (10% of MRR)
443
+ - Quick Ratio: 5.0
444
+
445
+ **Analysis:**
446
+ - ✅ Strong growth (10% MoM MRR)
447
+ - ✅ Excellent retention (2% logo churn, 115% NRR)
448
+ - ✅ Healthy expansion (NRR >100%)
449
+ - ✅ Sustainable (Quick Ratio 5.0)
450
+ - ✅ Revenue churn < logo churn (losing smaller customers, good signal)
451
+
452
+ **Action:** Scale acquisition. Unit economics are strong.
453
+
454
+ ---
455
+
456
+ ### Example 2: Warning Signs
457
+
458
+ **Company:** SMB marketing automation SaaS
459
+
460
+ **Revenue Metrics:**
461
+ - MRR: $500K (growing 15% month-over-month)
462
+ - ARR: $6M
463
+ - ARPA: $250/month (2,000 accounts)
464
+ - ARPU: $50/month (10,000 users)
465
+
466
+ **Retention Metrics:**
467
+ - Monthly logo churn: 6% (increasing from 4% six months ago)
468
+ - Revenue churn: 7% (losing larger customers)
469
+ - NRR: 85% (contracting)
470
+ - Expansion revenue: $5K/month (1% of MRR)
471
+ - Quick Ratio: 1.2
472
+
473
+ **Cohort Analysis:**
474
+ | Cohort | Month 6 Retention |
475
+ |--------|-------------------|
476
+ | 6 months ago | 75% |
477
+ | 3 months ago | 65% |
478
+ | Current | 58% |
479
+
480
+ **Analysis:**
481
+ - ⚠️ High churn (6% monthly = ~50% annual)
482
+ - 🚨 Revenue churn > logo churn (losing bigger customers)
483
+ - 🚨 NRR <100% (contracting, not expanding)
484
+ - 🚨 Cohort degradation (newer customers churn faster)
485
+ - 🚨 Quick Ratio 1.2 (leaky bucket)
486
+
487
+ **Action:** STOP scaling acquisition. Fix retention first. Investigate:
488
+ - Why are newer cohorts churning faster?
489
+ - Why is expansion revenue only 1% of MRR?
490
+ - What's causing customer contraction?
491
+
492
+ ---
493
+
494
+ ### Example 3: Blended Metrics Hiding Problems
495
+
496
+ **Company:** Multi-product SaaS platform
497
+
498
+ **Blended Metrics Look Great:**
499
+ - MRR: $3M (growing 20% MoM)
500
+ - Blended churn: 3%
501
+ - Blended NRR: 110%
502
+
503
+ **But Revenue Mix Analysis Shows:**
504
+ | Product | Revenue | % of Total | Growth | Churn | NRR |
505
+ |---------|---------|------------|--------|-------|-----|
506
+ | Legacy Product | $2M | 67% | -5% MoM | 8% | 75% |
507
+ | New Product | $1M | 33% | +80% MoM | 1% | 150% |
508
+
509
+ **Analysis:**
510
+ - 🚨 Legacy product (67% of revenue) is dying: -5% growth, 8% churn, 75% NRR
511
+ - ✅ New product is stellar: +80% growth, 1% churn, 150% NRR
512
+ - ⚠️ Blended metrics hide the fact that 2/3 of revenue is contracting
513
+ - ⚠️ High dependency on one product (67% concentration risk)
514
+
515
+ **Action:** Accelerate migration from legacy to new product. Plan for legacy product sunset.
516
+
517
+ ---
518
+
519
+ ## Common Pitfalls
520
+
521
+ ### Pitfall 1: Confusing Revenue with Profit
522
+ **Symptom:** "We grew revenue 50% this year, we're crushing it!"
523
+
524
+ **Consequence:** Revenue is the top line, not bottom line. You might be growing at a loss, destroying margins, or scaling unprofitable products.
525
+
526
+ **Fix:** Always pair revenue metrics with margin metrics (see `saas-economics-efficiency-metrics`). $1M revenue at 80% margin >> $2M revenue at 20% margin.
527
+
528
+ ---
529
+
530
+ ### Pitfall 2: Celebrating ARPU Growth from Mix Shift
531
+ **Symptom:** "ARPU increased 30%!" (but customer count dropped 40%)
532
+
533
+ **Consequence:** ARPU rose because you lost all your small customers, not because you improved monetization.
534
+
535
+ **Fix:** Analyze ARPU by cohort and segment. True ARPU improvement = same customers paying more, not losing cheap customers.
536
+
537
+ ---
538
+
539
+ ### Pitfall 3: Ignoring Cohort Degradation
540
+ **Symptom:** "Blended churn is stable at 3%"
541
+
542
+ **Consequence:** Blended metrics can hide that new cohorts churn at 6% while old cohorts churn at 1%. Product-market fit is degrading.
543
+
544
+ **Fix:** Always analyze retention by cohort. If newer cohorts perform worse, stop scaling and fix the product.
545
+
546
+ ---
547
+
548
+ ### Pitfall 4: Logo Churn vs. Revenue Churn Confusion
549
+ **Symptom:** "Logo churn is only 2%, we're great!"
550
+
551
+ **Consequence:** You might be losing 2% of customers but 10% of revenue if you're churning large customers.
552
+
553
+ **Fix:** Track both logo churn AND revenue churn. If revenue churn > logo churn, you're losing high-value customers.
554
+
555
+ ---
556
+
557
+ ### Pitfall 5: Treating All Churn Equally
558
+ **Symptom:** "We lost 50 customers this month" (no context on who)
559
+
560
+ **Consequence:** Losing 50 small customers ($10/month) is different from losing 50 enterprise customers ($10K/month).
561
+
562
+ **Fix:** Segment churn analysis by customer size, cohort, and reason. Weight by revenue impact, not just logo count.
563
+
564
+ ---
565
+
566
+ ### Pitfall 6: Forgetting Compounding Churn
567
+ **Symptom:** "3% monthly churn is fine, that's only 36% annually"
568
+
569
+ **Consequence:** Churn compounds. 3% monthly = 31% annual churn, not 36%. Math: `1 - (1 - 0.03)^12 = 31%`.
570
+
571
+ **Fix:** Use the correct formula when converting monthly to annual churn. Don't just multiply by 12.
572
+
573
+ ---
574
+
575
+ ### Pitfall 7: Celebrating Gross Revenue While Net Contracts
576
+ **Symptom:** "Gross revenue is up 20%!" (but discounts/refunds doubled)
577
+
578
+ **Consequence:** Net revenue might be flat or shrinking. Discounts hide pricing power problems; refunds hide product quality issues.
579
+
580
+ **Fix:** Always track gross AND net revenue. If discounts >20% or refunds >10%, investigate why.
581
+
582
+ ---
583
+
584
+ ### Pitfall 8: NRR >100% from Low Churn, Not Expansion
585
+ **Symptom:** "NRR is 105%, we're expanding!"
586
+
587
+ **Consequence:** NRR can be >100% just from very low churn, without meaningful expansion. True expansion-driven NRR is >120%.
588
+
589
+ **Fix:** Break down NRR into components: expansion MRR vs. churned/contracted MRR. Aim for expansion-driven NRR, not just low churn.
590
+
591
+ ---
592
+
593
+ ### Pitfall 9: Revenue Concentration Risk
594
+ **Symptom:** "We're at $10M ARR!" (but $5M is from one customer)
595
+
596
+ **Consequence:** Losing that one customer cuts revenue in half. Roadmap becomes hostage to one customer's requests.
597
+
598
+ **Fix:** Track revenue concentration. Ideal: Top customer <10% of revenue, Top 10 customers <40%. Diversify early.
599
+
600
+ ---
601
+
602
+ ### Pitfall 10: Averaging ARPU/ARPA Across Segments
603
+ **Symptom:** "Our ARPU is $100" (average of $10 SMB and $1,000 enterprise)
604
+
605
+ **Consequence:** Blended ARPU hides segment economics. Can't make smart acquisition or product decisions.
606
+
607
+ **Fix:** Calculate ARPU/ARPA by segment (SMB, mid-market, enterprise). Optimize each segment independently.
608
+
609
+ ---
610
+
611
+ ## References
612
+
613
+ ### Related Skills
614
+ - `saas-economics-efficiency-metrics` — Unit economics (CAC, LTV, margins, burn rate)
615
+ - `finance-metrics-quickref` — Fast lookup for all metrics
616
+ - `feature-investment-advisor` — Uses revenue metrics to evaluate feature ROI
617
+ - `finance-based-pricing-advisor` — Uses ARPU/ARPA to evaluate pricing changes
618
+ - `business-health-diagnostic` — Uses revenue/retention metrics to diagnose business health
619
+
620
+ ### External Frameworks
621
+ - **Bessemer Venture Partners:** "SaaS Metrics 2.0" — Definitive guide to SaaS metrics
622
+ - **David Skok (Matrix Partners):** "SaaS Metrics" blog series — Deep dive on unit economics
623
+ - **Tomasz Tunguz (Redpoint):** SaaS benchmarking research
624
+ - **Tien Tzuo:** *Subscribed* — Subscription business model fundamentals
625
+ - **ChartMogul, Baremetrics, ProfitWell:** SaaS analytics platforms with metric definitions
626
+
627
+ ### Provenance
628
+ - Adapted from `research/finance/Finance for Product Managers.md`
629
+ - Consolidated from `research/finance/Finance_QuickRef.md`
630
+ - Common mistakes from `research/finance/Finance_Metrics_Additions_Reference.md`