joellewis/retirement-decumulation
Turn a retirement portfolio into sustainable lifetime income: sequence-of-returns risk, the 4% rule and its assumptions, Guyton-Klinger-style guardrails, RMD calculation from the Uniform Lifetime Table, Social Security claiming math (early reduction, delayed credits, breakeven age, survivor benefits), gap-year bracket-filling with Roth conversions, bucket strategies vs total-return, and SPIA annuitization as longevity insurance. Use when the user asks about a 'safe withdrawal rate', 'when should I claim Social Security', a 'guardrails strategy', 'sequence of returns risk', or 'how much can I spend in retirement'. Also trigger on RMD amounts or missed-RMD penalties, Social Security breakeven analysis, '4% rule', 'bucket strategy', retirement paycheck design, drawdown or decumulation planning, and whether to buy an annuity. For accumulation-side savings math, see savings-goals; for asset location and tax mechanics, see tax-efficiency.
npx skills add https://github.com/JoelLewis/finance_skills --skill retirement-decumulation
Two retirees earning identical average returns can finish with very different wealth if the returns arrive in a different order while money is being withdrawn. Without withdrawals, order is irrelevant — multiplication commutes. With withdrawals, dollars sold after a decline are gone permanently and never participate in the recovery, so poor early returns do disproportionate damage. The danger zone is roughly the five to ten years on either side of the retirement date. Mitigants: flexible spending rules (guardrails), a cash/short-bond buffer, reduced equity exposure near retirement (or a rising equity glide path), and part-time income that lowers the withdrawal rate in early years.
Bengen's 1994 study (extended by the 1998 Trinity study) found that an initial withdrawal of 4% of the portfolio, adjusted for inflation each year thereafter, survived every rolling 30-year US historical period with 50-75% stocks — the "4% rule." Its assumptions are also its criticisms: it relies on US historical returns (an unusually strong market), a fixed 30-year horizon, rigid inflation-adjusted spending with zero flexibility, and it ignores fees and taxes. Longer retirements, high starting valuations, or lower expected returns argue for 3-3.5% initial rates; dynamic rules (guardrails, amortization-based, RMD-style percent-of-balance) support higher initial rates because spending flexes with the portfolio.
A concrete dynamic rule set:
The full Guyton-Klinger rule set also skips the inflation increase after a negative-return year. The trade-off: a higher starting income than the 4% rule, paid for with variable spending — the retiree must actually take the cuts when triggered.
RMDs from tax-deferred accounts begin at age 73 under SECURE 2.0, rising to 75 in 2033 for those born in 1960 or later. Mechanics:
Full retirement age (FRA) is 67 for those born in 1960 or later. The adjustment factors are statutory:
The conventional order — taxable first, then tax-deferred, then Roth — preserves tax-free growth longest (see tax-efficiency for the tax mechanics and asset-location foundations). The decumulation refinement is the gap years: after retiring but before Social Security and RMDs begin, taxable-only withdrawals can leave the ordinary brackets nearly empty. Filling low brackets with partial Roth conversions (or tax-deferred withdrawals) in those years shrinks future RMDs, reduces the survivor's single-filer bracket exposure, and smooths lifetime tax rates — while watching Medicare IRMAA surcharge thresholds (indexed annually) that behave as cliffs. Delaying Social Security to 70 both earns delayed credits and widens the conversion window.
A bucket strategy holds 1-2 years of spending in cash, several more years in bonds, and the remainder in equities; spending comes from cash, refilled from the growth buckets opportunistically. A total-return approach holds one target allocation and funds withdrawals by rebalancing. Mathematically a maintained bucket structure is close to a fixed allocation with rebalancing discipline; its real value is behavioral — retirees tolerate equity drawdowns better knowing near-term spending is secured. The main failure mode is leaving the refill rules undefined.
A single premium immediate annuity (SPIA) converts an irrevocable premium into lifetime income. Because payments pool longevity risk across annuitants, mortality credits let a SPIA sustain a higher payout rate than a self-insured portfolio at the same confidence level — insurance, not an investment to benchmark against market returns. A floor-and-upside design annuitizes enough (with Social Security) to cover essential expenses and invests the rest for growth. Trade-offs: nominal SPIAs carry inflation risk, liquidity and bequest are surrendered, and payments depend on insurer solvency (state guaranty association limits vary). Deferred income annuities and QLACs push income to advanced ages as a tail-longevity hedge (QLAC premium cap: $200,000 statutory base under SECURE 2.0, indexed annually — verify the current limit).
| Formula | Expression | Use Case |
|---------|-----------|----------|
| Balance recursion (start-of-year withdrawal) | B_t = (B_{t-1} - W_t) x (1 + r_t) | Simulate a withdrawal plan / sequence risk |
| Inflation-adjusted withdrawal | W_t = W_1 x (1 + i)^(t-1) | Fixed-real spending path |
| Current withdrawal rate | CWR = W / B | Guardrail test each year |
| Guardrail bands | upper = r_0 x 1.20; lower = r_0 x 0.80 | Trigger thresholds |
| Guardrail adjustment | W' = W x 0.90 (cut) or W x 1.10 (raise) | Capital-preservation / prosperity rules |
| RMD | RMD = balance_Dec31 / divisor | Required minimum distribution |
| SS early reduction | factor = 1 - [min(m,36) x 5/9 + max(m-36,0) x 5/12]/100 | Benefit if claimed m months before FRA |
| SS delayed credit | factor = 1 + m x (2/3)/100 | Benefit if claimed m months after FRA (to 70) |
| SS breakeven | months after late claim = B_e x Δm / (B_l - B_e) | Age where delaying pulls ahead |
Given: $1,000,000 portfolio, $50,000 withdrawn at the start of each year (no inflation adjustment for clarity). Sequence A returns: -20%, +10%, +25%. Sequence B: the same returns reversed (+25%, +10%, -20%).
Calculate: Ending balances.
Solution:
Given: Retiree starts with $1,000,000 and a 5.0% initial rate ($50,000). Guardrails at plus or minus 20% of 5.0%: upper 6.0%, lower 4.0%. Adjustments are 10%.
Calculate: The required action in a bad-market year and a strong-market year.
Solution:
Given: Retiree turns 73 in 2026; the Traditional IRA balance on December 31 of the prior year was $850,000. Uniform Lifetime Table divisor at 73 = 26.5.
Calculate: The RMD and the penalty if entirely missed.
Solution:
Given: PIA = $2,000/month at FRA 67 (born 1960 or later).
Calculate: Benefits at 62 and 70, and the breakeven ages (ignoring COLA and discounting).
Solution:
Run the reference implementation directly:
uv run scripts/retirement_decumulation.py # PEP 723 header resolves dependencies automatically
python3 scripts/retirement_decumulation.py # standard library only — no installs needed
A bare run prints a demo covering sequence-of-returns comparison, guardrails adjustments, RMD calculation and penalties, Social Security claiming factors, and breakeven ages. Use --verify to recompute the demo figures and assert they match this skill's worked examples (prints PASS/FAIL, exits nonzero on mismatch), and --help to list the available classes and functions. The file is primarily meant to be imported as a module (from retirement_decumulation import RetirementDecumulation) rather than run standalone.
Take joellewis/retirement-decumulation from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.