Methodology, sources, and changelog

The calculators are maintained by the operator of retiring.guide. Federal parameters are re-verified against primary sources each autumn when the IRS, CMS, and SSA publish the following year’s figures, and again whenever legislation changes them. Each build is stamped with a date-based version (currently 20260906-05) that appears in the page metadata and in this changelog.

Corrections. Reproducible calculation errors reported to info@retiring.guide are acknowledged within five business days, fixed in the next build, and recorded below with the affected range of inputs. The engine ships with a regression test file (tests/engine-tests.js) that checks statutory thresholds and worked examples before release.

No individual reviewer is named on this site. Results are educational estimates, not advice; see the Terms.

The engine runs month by month. Cash inflows, one-time events, spending, and withdrawals occur before investment returns. Account returns are nominal total returns; dividends are not added separately. Social Security is computed per person each month with the rules above, COLA applied each January. Taxes on withdrawals use the effective rate entered for each account (a projection convention, not a tax return). RMDs use the Uniform Lifetime Table, spread across the year, without the first-year April 1 deferral. Monte Carlo draws lognormal monthly returns with correlated asset-class factors (equity, bonds, real estate) and reports a model success rate with a binomial sampling margin; it does not represent fat tails, regime changes, or future law changes.

Savings longevity and growth apply one steady net return monthly. Withdrawal strategies take withdrawals at the start of each year on a stylized return sequence. RMD uses prior year-end balances and the Uniform Lifetime Table with an optional first-year deferral. Roth conversion and tax is a single-year 2026 federal estimate described on its page. Claiming and bridge tools share the Social Security engine with the household plan but omit the earnings test and account-access rules.

Build 20260906-05 — 6 September 2026

• Fix: the flicker reported on both phone and desktop was a logic error introduced in build 03: the pin test read the bottom edge of a placeholder that is zero-height while the grid is in the page, so pinning and unpinning fed each other. The bottom edge is now read from the grid itself while static and from the placeholder once fixed, with a small hysteresis band.

Build 20260906-04 — 6 September 2026

• Fix: continuous flicker on phones while the calculator grid was on screen. Cause: backdrop-filter blur on the header and grid and a transform on the fixed bar, which some mobile GPUs repaint endlessly. Both surfaces are now opaque and the bar is centred with insets; the panel entrance animation is opacity-only.

Build 20260906-03 — 6 September 2026

• Charts no longer open with the read-out card showing the final period; it appears only on hover, touch, or arrow keys. The final period is still announced to screen readers through the chart label.
• The fixed calculator bar now appears only after the whole calculator grid has scrolled above the header, which removes the blank space that showed beneath it on phones.

Build 20260906-02 — 6 September 2026

• Fix: the calculator list flickered while scrolling. The pinned bar was a sticky element whose height changed when it collapsed, which moved the page and re-triggered the switch. The full grid now stays in the page and a separate fixed slim bar (active calculator + “All calculators”) appears under the header once the grid scrolls away; a placeholder keeps the grid’s space so nothing moves.
• Charts: the hover read-out is back on the chart as a compact card that follows the cursor and flips sides near the right edge; it never intercepts the pointer.
• Independent tooling pass: all 19 pages validate with html-validate (WCAG rules on), scripts pass ESLint with no errors, and the stylesheet passes stylelint apart from stylistic notation choices. Fixes from that pass: min/step moved to data- attributes on formatted text inputs, scope on every table header, list semantics for the hero feature row, and role="group" on labelled action groups.

Build 20260906-01 — 6 September 2026

• Design system: the three stylesheets were replaced by one central, fully commented stylesheet (retirement-lab-20260906-05.css) with a design-token block at the top. The look now matches winning.monster: ivory paper, navy ink, emerald as the single action colour, gold for emphasis, Besley serif headlines with Public Sans text and IBM Plex Mono labels. Cards have one border colour on all sides; status is shown by tinting the whole card. Fonts are self-hosted (SIL Open Font License) so no request goes to Google Fonts, and the content-security policy no longer allows it.
• Every page — hub, ten calculator pages, methodology, legal and support pages, 404, and the consent dialog — uses the same header, type scale, buttons, tables and footer from that stylesheet.

Build 20260904-08 — September 4, 2026

• Design: once the calculator list is pinned to the top of the page it collapses to the active calculator plus an “All calculators” button, so it no longer covers the form and results (it previously took up to 40% of a laptop screen). Input labels in the same row now reserve two lines so their fields line up.
• Fix: chart hover readouts floated over the plot at desktop widths after the stylesheet change in build 07; the readout is docked below the plot again and the scripts now respect the docked layout instead of positioning it inline.
• The last !important declarations in the theme were removed (26 → 20 site-wide, all in base/consent for hidden, visually-hidden, reduced-motion and print rules).

Build 20260904-07 — September 4, 2026

• New calculators: historical backtest (every retirement window 1928–2025 with real returns and inflation), “am I on track” savings benchmark with 2026 limits, and pension lump-sum vs. monthly comparison (present value, IRR, break-even, survivor terms). The withdrawal-strategy tab gained a historical start-year sequence.
• Fixed-real spending now uses each year’s actual inflation when a historical series is selected; the inflation-adjusted income shown is exactly constant for that strategy.
• Engineering: calculator code loads on demand (Social Security engine, tax/history modules, and the full plan each load only when their tab opens; the first view loads about 94 KB of script instead of 408 KB). Stylesheets now use CSS cascade layers (base → consent → theme), removing 450 of 474 !important declarations; browsers older than 2022 (iOS 15.4, Chrome 99, Firefox 97) will see the unthemed base styles.

Build 20260904-06 — September 4, 2026

• Correction (critical): the 2025–2028 senior deduction was phased out on the combined household amount instead of per person, overstating the deduction for married couples in the $150,000–$250,000 MAGI range by up to $6,000 and understating tax and Roth conversion cost. Now computed per IRS Schedule 1-A; boundary tests added at $150k, $175k, $200k, $225k, $250k.
• Social Security: earnings test now withholds whole monthly checks from the start of each year, applies the monthly test after earnings stop, and recomputes the reduction factor at full retirement age for months withheld.
• Social Security: survivor benefits now apply the widow(er)’s limit (82.5% of PIA floor) when the deceased claimed early and pass inherited delayed credits through when the deceased claimed late.
• Social Security: COLA is applied once each January rather than compounded monthly. The Trustees preset now declines from 78% in 2032 to 62% in 2100 instead of staying flat.
• Tax tab: added married-filing-separately, an investment-income field for NIIT, a Medicare-people count for household IRMAA cost, the surcharge year (2028), a component breakdown of the marginal conversion cost, and a household-specific “not modeled” list; “marginal rate” relabeled as federal bracket; state entry relabeled as a rough allowance.
• RMD tab: first-year April 1 deferral option; unsupported situations listed beside the answer.
• Household plan: default 2,000 Monte Carlo paths (max 10,000) with a sampling margin shown; effective-rate tax model labeled at the result; validation errors link to and mark the responsible field; calculation failures keep entries and show a diagnostic code.
• Sharing and storage: share links open a review dialog with redaction options and a length warning; imports show a preview and can be undone; a “delete saved plan” action clears local storage and switches to session-only mode; saves are debounced and show the last saved time.
• Accessibility and design: 16px baseline, 44px targets, privacy dialog focuses its heading, result cards announce a single sentence instead of the whole card, out-of-range currency entries are reported rather than silently clamped, tables have sticky headers and a scroll hint, consent bar compacted with safe-area insets.
• Security: CSP allowlist replaces the HTTPS wildcard; custom 404 page; HSTS includeSubDomains.
• Content: dedicated landing pages for each calculator, glossary, this methodology page, Terms rewritten to describe the two tax models, accessibility statement updated with test scope.

Build 20260904-05 — September 4, 2026

• Added withdrawal-strategy, RMD, and Roth conversion tabs; today’s-dollar views on the savings and growth tabs; 2026 contribution-limit checks.

Send the tab, the inputs (with sensitive values changed), the result you saw, and the result you expected with a citation if you have one to info@retiring.guide. Reproducible errors are corrected in the next build and listed above.