From core
Computes and compares investment return metrics including TWR, MWR/IRR, CAGR, annualized returns; explains cash flow effects, sub-period linking, arithmetic vs geometric means for portfolio analysis.
npx claudepluginhub joellewis/finance_skills --plugin coreThis skill uses the workspace's default tool permissions.
This skill enables Claude to compute, explain, and compare investment return metrics across different methodologies and time horizons. It covers the full spectrum from simple holding-period returns through time-weighted and money-weighted returns, ensuring the appropriate metric is selected for each analytical context.
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
This skill enables Claude to compute, explain, and compare investment return metrics across different methodologies and time horizons. It covers the full spectrum from simple holding-period returns through time-weighted and money-weighted returns, ensuring the appropriate metric is selected for each analytical context.
0 — Mathematical Foundations
retrospective
The most basic measure of investment performance over a single period, capturing price change plus any income received.
$$R = \frac{V_{end} - V_{begin} + D}{V_{begin}}$$
where:
V_end = ending valueV_begin = beginning valueD = distributions (dividends, interest) received during the periodThe simple average of a series of periodic returns. Represents the expected return for any single period.
$$R_a = \frac{1}{n} \sum_{i=1}^{n} R_i$$
The arithmetic mean is always greater than or equal to the geometric mean. It is an unbiased estimator of the expected single-period return but overstates the compounded growth rate.
The constant rate that, if earned each period, would produce the same terminal wealth as the actual sequence of returns.
$$R_g = \left(\prod_{i=1}^{n}(1 + R_i)\right)^{1/n} - 1$$
The geometric mean captures the effects of compounding and volatility drag. It is always the correct choice for describing realized multi-period growth.
The natural logarithm of the wealth ratio. Log returns are time-additive, making them convenient for multi-period aggregation and statistical modeling.
$$r = \ln\left(\frac{V_{end}}{V_{begin}}\right)$$
Properties:
r_total = r_1 + r_2 + ... + r_nR_simple = e^r - 1 and r = ln(1 + R_simple)The annualized geometric return that equates the beginning value to the ending value over a given number of years.
$$CAGR = \left(\frac{V_{end}}{V_{begin}}\right)^{1/n} - 1$$
where n is measured in years. CAGR smooths out volatility and provides a single annualized growth figure.
Chain-links sub-period returns calculated between each external cash flow, thereby removing the effect of cash flow timing on the measured return. TWR measures the manager's investment skill independent of investor deposit/withdrawal decisions.
$$1 + R_{TWR} = \prod_{i=1}^{n}(1 + R_i)$$
where each sub-period return R_i is computed between consecutive cash flow dates:
$$R_i = \frac{V_{end,i}}{V_{begin,i} + CF_i}$$
In practice, exact TWR requires portfolio valuation on every cash flow date. The Modified Dietz method approximates TWR when daily valuations are unavailable.
The internal rate of return that sets the net present value of all cash flows (contributions, withdrawals, and terminal value) to zero.
$$0 = \sum_{t=0}^{T} \frac{CF_t}{(1 + r)^t}$$
MWR reflects the actual investor experience because it is sensitive to the timing and magnitude of cash flows. It rewards (penalizes) investors who add capital before good (bad) periods.
Converts a return measured over any holding period to an equivalent annual rate, assuming compounding.
$$R_{annual} = (1 + R_{period})^{periods_per_year} - 1$$
For example, a 2% quarterly return annualizes to (1.02)^4 - 1 = 8.24%.
Combines returns from contiguous sub-periods into a single cumulative return.
$$(1 + R_{total}) = \prod_{i=1}^{n}(1 + R_i)$$
This is the foundational identity behind TWR and CAGR calculations.
| Formula | Expression | Use Case |
|---|---|---|
| Holding Period Return | R = (V_end - V_begin + D) / V_begin | Single-period total return |
| Arithmetic Mean | R_a = (1/n) * sum(R_i) | Expected single-period return |
| Geometric Mean | R_g = [prod(1+R_i)]^(1/n) - 1 | Realized compound growth rate |
| Log Return | r = ln(V_end / V_begin) | Time-additive return for modeling |
| CAGR | (V_end / V_begin)^(1/n) - 1 | Annualized growth over n years |
| TWR | prod(1 + R_i) - 1 | Manager performance (cash-flow neutral) |
| MWR / IRR | sum(CF_t / (1+r)^t) = 0, solve for r | Investor-specific experience |
| Annualization | (1 + R_period)^(periods/year) - 1 | Standardize to annual basis |
| Sub-Period Linking | (1 + R_total) = prod(1 + R_i) | Combine contiguous returns |
Given: An investment of $10,000 grows to $16,105.10 over exactly 5 years with no intermediate cash flows.
Calculate: The compound annual growth rate (CAGR).
Solution:
CAGR = (V_end / V_begin)^(1/n) - 1
CAGR = (16,105.10 / 10,000)^(1/5) - 1
CAGR = (1.610510)^(0.2) - 1
CAGR = 1.10 - 1
CAGR = 0.10 = 10%
The investment grew at a compound annual rate of 10% per year.
Verification: $10,000 * (1.10)^5 = $10,000 * 1.61051 = $16,105.10
Given: A fund has the following history:
Calculate: Both TWR and MWR, and explain the divergence.
Solution:
Time-Weighted Return (TWR):
Sub-period 1 return: R_1 = (120,000 - 100,000) / 100,000 = +20%
Sub-period 2 return: R_2 = (198,000 - 220,000) / 220,000 = -10%
TWR (cumulative) = (1 + 0.20) * (1 + (-0.10)) - 1
= 1.20 * 0.90 - 1
= 1.08 - 1
= +8.0%
TWR (annualized) = (1.08)^(1/2) - 1 = 3.92%
Money-Weighted Return (MWR / IRR): Cash flows from the investor's perspective:
Solve: -100,000 + (-100,000)/(1+r) + 198,000/(1+r)^2 = 0
Testing r = -0.0051 (approximately -0.51%):
-100,000 + (-100,000)/0.9949 + 198,000/0.9899
= -100,000 - 100,512.6 + 200,020.2
approx -492.4 (close to zero; actual IRR approx -0.48%)
The MWR is approximately -0.48% annualized.
Interpretation: The TWR of +3.92% annualized reflects the manager's skill: the fund gained 20% then lost 10%, netting +8% over two years. The MWR of approximately -0.48% reflects the investor's experience: more money was at risk during the losing year (Year 2) because of the large deposit, so the investor's dollar-weighted outcome was slightly negative. This divergence highlights why TWR is preferred for evaluating manager performance, while MWR better describes the specific investor's realized result.
(1.02)^52 - 1 = 180%, which amplifies noise and is misleading. Annualization is most meaningful for periods of at least one year.V_end already includes reinvested dividends, do not add D separately in the holding period return formula.See scripts/return_calculations.py for computational helpers.