How we keep the math honest
A retirement plan is only as good as the math under it. Here is how that math works, how we test it, what happens to your data, and what the model doesn’t do.
The detail
The five promises in full, and every check a change has to pass.
What we promise about your retirement numbers
Each pillar is a promise about how this platform's accuracy is maintained. Together they describe the trust posture from end to end — math engine through AI Advisor.
🧪 Reproducibility
Every change is tested. The pipeline runs automatically on every push — the tier that protects your numbers before the release goes out, the rest within minutes of it. We don't ship around failing tests; the test gets fixed or the change comes back out.
See the 32-gate pipeline →👥 Real-scenario coverage
Math is exercised against 49 realistic retirement profiles — early retirees, FIRE plans, Coast FIRE, household + single, multi-state edge cases, pension-heavy. Every profile re-runs when the engine changes.
See the persona corpus →📐 No silent drift
Your projection won't change without us telling you why. Every code change is locked against a regression gate that fails on any output drift. When fidelity does change — a tax law update, a bug fix — it's documented in the changelog.
See the changelog →📦 Source-vs-shipped parity
What you run in your browser is verified against the version we test in development. Bundle minification can silently strip dead code; this gate catches that failure mode.
See the parity check →🤖 AI groundedness
The AI Advisor you talk to is verified against a 107-entry canonical question set covering navigation, card references, deterministic field citations, recommendation shape, out-of-scope handling, and compositional patterns. By policy, the AI never recommends specific products, services, or providers — it educates and grounds in authoritative sources (IRS, SSA, Bengen / Trinity / Pfau research). Every shipped fix to AI grounding gets a permanent regression test, so when something slips it can't slip the same way twice.
See the AI verification regime →Distinctive methodological commitments
Seven methodological commitments that distinguish this platform from category baseline. The full math doc lives in the "How It Works" modal — link below to open it at any specific topic.
Seeded Monte Carlo
Monte Carlo simulations use a deterministic seeded RNG. Same inputs produce identical trajectories across reloads — no success-rate flicker. 1,000 sims for headline confidence; 750 for sweep metrics.
SECURE 2.0 birth-year-aware RMDs
RMD age is dynamic per birth year: 75 for births 1960+, 73 for births 1951–1959, per IRS Pub 590-B. No hardcoded "73" anywhere in the engine; the prompt verifier scans for drift on every push.
51-state tax modeling
All 50 states + DC modeled individually: tax brackets, standard deduction, LTCG treatment, IRMAA thresholds, ACA premium-credit cliffs. Refreshed annually against IRS / CMS / HHS source publications.
Roth conversion sweet spot + IRMAA framing
Engine computes annual Roth conversion recommendation grounded in the user's bracket headroom AND IRMAA Medicare-surcharge tier position — not generic 4% conversion advice.
Tax-aware withdrawal order
Withdrawal sequence — bridge → savings → brokerage → 401(k) → HSA → Roth — applied year by year. The order you withdraw determines how much goes to the IRS vs. your retirement.
Guyton-Klinger dynamic spending
Opt-in dynamic withdrawal modeling the Guyton + Klinger 2006 guardrail framework. Capital preservation rule + prosperity rule. Historically supports 5.0% safe withdrawal rates vs the 4% rule's static math.
Historical back-testing (Bengen / Trinity Study)
Plan replayed against Shiller's 1928–2022 dataset of actual S&P 500, 10-year Treasury, and CPI-U sequences. Two surfaces: a five-era card (Great Depression / 1966 / stagflation / dot-com / financial crisis) and a full-range workshop (every eligible start year, allocation slider). Cohort survival rate sits alongside Monte Carlo SR — two views of the same plan, honest about what each measures.
A four-tier regime for AI behavior — not just AI prompts
The most likely production-bug source in any LLM-integrated product.
The pipeline has 32 pre-push gates. The AI Advisor needs a different kind of verification — one that actually talks to the AI and checks what it says. Three tiers shipped and active; a fourth (live response-pattern telemetry) is queued.
For every category of question users ask the AI — "where do I change X?", "tell me about Y card", "what's my Z value?", "should I do strategy W?", "should I buy this specific product?" — there's a canonical entry in the eval corpus. Each entry has shape-based assertions; the runner dispatches each to Anthropic, applies assertions to the response, compares against the locked baseline.
Every reported AI bug becomes a permanent regression entry — when something slips, it can't slip the same way twice. The same discipline that math regression-locks every shipped bug fix, extended to AI behavior.
See the full AI eval regime →32 gates, in two tiers
Every release runs all 32. The ones that protect your numbers — a zero-drift check against 39 saved plans, the structural invariants, the determinism check — block the release outright: the first red gate halts it, no opt-outs. The rest, covering things like our free calculators and page layout, run in the minutes after and alert us if they fail. We split them deliberately. A wrong number has to be impossible. A wrong layout has to be fast to fix.
Size guard
Asserts the deployed bundle is above a calibrated byte threshold. The bundle minifier can silently strip dead code; this gate catches the failure mode where a refactor accidentally removes a load-bearing chunk and the build looks fine but ships broken.
Deployed-bundle freshness
The app you load is a minified build of the source. This gate rebuilds the bundle from the current source and byte-compares it against the committed file — catching the failure mode where a fix lives in the reviewed source but a stale build never carried it to your browser.
Gate wiring
A verification gate only counts if something actually runs it. This gate walks every verifier in the repository and asserts each one is reachable by a runner — or carries a written reason it is run by hand. Added after two gates were found fully written, documented, and wired to nothing.
Three-list alignment
Every input field is defined in four places — the engine's defaults, the user-action whitelist, the AI Advisor's known-fields list, and the cache-key derivation list. This gate verifies all four agree.
State tax profile parity
State tax modeling for 51 states (50 + DC) is defined in two places — the engine and the methodology doc. 51 × 5 fields = 255 equality checks confirm the documented tax treatment is exactly what the engine applies.
Actuarial life-table parity
The Planning Horizon Workshop reads the SSA 2022 period life table. The table is defined in two places — the engine and the methodology doc. This gate confirms every survival probability the workshop shows you is exactly the number the engine computes with.
Long-term-care cost parity
Long-term-care costs are priced from a 50-state, three-care-level table sourced from a published cost-of-care survey. The table lives in the engine and in a citable reference document; this gate proves the two match, cell for cell.
Move library descriptor drift
The Smart Moves library (31 moves) is defined in the engine; the AI needs a parallel description. This gate confirms the AI's catalog matches the engine's exactly.
ENGINE_VERSION drift
The engine carries a version stamp that must change whenever the calculation math changes. This gate diffs the current engine functions against the version they were last stamped at and fails the push if the math moved without a stamp bump — the same stamp that invalidates any cached AI analysis so you are never shown a stale number against new math.
API syntax check
Runs node --check on every server-side file. Added after a single misplaced apostrophe in a system prompt broke the AI Advisor endpoint for ~24 hours.
API no-undef scan
Static scope analysis of every server-side file — catches a reference to a variable that was never defined, the runtime-error class a plain syntax check can't see. Added after exactly that bug: a reference to an undefined body returned a 500 on every AI call for ~24 hours.
Worker no-undef scan
The heavy maths runs on a background thread, which gets its own copy of the engine built from the same source. This checks that every name that copy uses actually exists inside it — a function left behind in the rebuild would work perfectly on the page and fail only in the background, which is the hardest kind of fault to notice.
AI deep-link infrastructure
The AI Advisor can navigate you to a specific input when you ask "where do I change my SS claim age?" This routing relies on three layers staying in sync; this gate verifies all three are wired so AI navigation can't silently no-op.
AI prompt section-target drift
The AI's system prompt references specific UI cards by name. If a card gets renamed but the prompt still references the old name, the AI would confidently tell you to look for a card that no longer exists. This gate verifies every reference resolves.
AI context payload schema
When the AI responds, it gets your specific data — your RMD age, your success rate, your bridge-year MAGI, your effective tax rate. If the engine stops producing one of these fields, the AI silently falls back to generic defaults. This gate catches that.
AI prompt hardcoded-value scan
Scans prompt source for known-drifty hardcoded values (specific ages, dollar amounts, tax brackets) that should be dynamically interpolated. Context-aware: legitimate historical references don't fire; user-direct claims do.
Structural invariants
Six structural rules across 49 personas (294 assertions): balances can't be negative, monthly displays can't exceed annual ones, depleted-flag semantics must be consistent. Catches math regressions that don't shift the bottom line enough to fail persona-gate.
Per-bug + Worker verifiers
Every shipped bug fix gets a dedicated verifier. Same for Worker infrastructure (the off-thread calculation pipeline) and the Observation Engine's detector mechanisms. 72 individual checks. If any future refactor accidentally reverts a fix, the verifier fires.
Degenerate-input safety
Runs 20 degenerate and boundary input shapes — zero balances, a life expectancy at or below retirement age, already-retired, extreme values — through the engine and all three Monte Carlo paths. Asserts no output is ever NaN or a stray infinity, and that an impossible window returns a clean “no result” instead of a crash or a garbage number.
Persona home consistency
A saved test plan that includes a house has to store the figures its own entries produce, or the gate below locks a plan this app could never actually produce. Added 2026-08-03 after one test plan was found carrying a $700,000 home and a description saying it downsized, while modelling no sale at all — three quarters of the plan it claimed to describe was never being simulated. A baseline that locks the wrong plan is worse than none, because it reads as coverage.
Persona end-balance gate
The master correctness check. 49 synthetic retirement profiles — early retirees, FIRE plans, Coast FIRE, household + single, multi-state edge cases — run through the engine and compare against locked baseline end balances. Any drift, even $1, fails the push.
Monte Carlo determinism
Monte Carlo uses random numbers, but for the same inputs they must produce the same results across runs. Verifies the seeded RNG produces byte-identical MC trajectories across 4 personas × 3 simulation functions.
Lens consistency
Smart Moves has four lenses (Retire Earlier, Spend More, Leave a Legacy, Weather a Downturn). Validates every move object across all four is well-formed.
Smart Moves snapshot
The largest gate. For each of 49 personas, computes baseline + optimized values across all four lenses (192 total computations using real Monte Carlo bisection). Compares against locked baseline with tight tolerance bands.
Doc constant drift
User-facing copy — methodology, glossary, in-app tips — cites IRS limits, tax thresholds, and contribution caps. This gate re-derives each from the live engine constant every run and fails if any copy string still shows a stale value (last year’s number after a limits update). The discipline gate 13 applies to the AI prompt, applied to the words humans read.
Doc ledger 1:1
Every methodology section and every glossary entry must have a row in the documentation coverage ledger — and no ledger row may cite a section or term that doesn’t exist. A new feature can’t quietly add engine math without its documentation being accounted for.
Methodology anchors
Every section of the methodology declares which engine functions it describes, and a retired model leaves a “tombstone” phrase its section may never use again. A methodology sentence describing code that no longer exists blocks the push — the engine and its documentation must move in the same commit.
Trust-page figures vs the code
The numbers on this very page — gate count, benchmark plans, AI evals, glossary entries — are re-derived from the code on every push and compared against what this page claims. A stale figure blocks the push outright. It caught this page being several gates behind on the day the newest gates landed.
Concierge surface map
The AI concierge on this site can open modals and scroll to sections; its allowed targets live in a prompt on the app side. This gate proves every target the prompt claims still exists on the real page, and that the prompt’s pricing matches the pricing canon.
Design mock parity
When a screen is designed as a mock first, that mock becomes the build checklist. This reads the approved mock and the built app and compares them element by element, so a piece of an approved design cannot quietly be left out and forgotten — which had happened twice before it existed.
Analytics contract
What the app records about usage is held to a written contract, checked against the real API handlers: an allow-list of what a session document may contain, a purchase counted only when money actually moved, and an excluded browser proven to send nothing.
Headless UI smoke
Loads the built app in a real headless browser and walks every tab on realistic and boundary plans — asserting no render crash and that the cards that should appear actually appear. The gates above test the engine in a sandbox; this one catches render-layer failures they can’t see — a plan that calculates correctly but crashes on screen.
Two further steps run warn-only — a cross-repo check that the app and marketing changelogs stay in sync, and one that checks every figure on this page against the code it describes. They surface drift but never block a release, so they aren’t counted among the 32 gates above.
Fail-fast: first red gate halts the push
If any single gate fails — even the cheapest 30ms check — the entire push is blocked. No manual override, no per-gate bypass. Either every gate passes and the code ships, or nothing ships and we fix the regression first.
49 synthetic retirement profiles, baseline-locked
The persona gate (step 21 above) runs each of 49 hand-built retirement profiles through the engine on every push: early retirees, traditional retirees, FIRE plans, Coast FIRE, single-earner households, dual-earner households, pension-heavy plans, multi-state edge cases. Each persona has a locked baseline end balance. The gate compares fresh runs against the lock. Any drift — even one dollar — fails the push. The corpus expands as we discover real-world edge cases users hit.
93 canonical question/response pairs
The pipeline has 32 gates. AI behavior needs a different mechanism — one that actually talks to the AI. For every category of question users ask — "where do I change my X?", "tell me about Y card", "what's my Z value?", "should I do strategy W?", "should I buy this specific product?", "what about a survivor scenario?", "I just got laid off and I'm panicking" — there's a canonical entry in the eval corpus.
Each entry has shape-based assertions (does the AI emit the right navigation directive? cite the right number? decline the right kind of request? never recommend a specific product?). The runner dispatches each entry to Anthropic, applies assertions to the actual response, compares against the locked baseline. Any entry that flips from passing to failing exits non-zero and the change doesn't deploy until it's understood. The eval set runs separately from the pre-push pipeline (cost + dispatch time make per-push unfit). Discipline rule: any change to AI prompt source triggers an eval run before deploy.
What runs in your browser matches what we test
The size guard (gate 1) + the persona end-balance gate (gate 21) together lock the relationship between the source we develop against and the bundle we ship. The minified browser bundle is verified semantically equivalent to the source across all 49 persona end balances. If they ever diverge, we catch it before you see it.
Privacy isn't a policy. It's an architecture.
There's no user account, and your retirement numbers live in your browser — we keep no copy you could lose, leak, or sell. Our server holds only what a purchase needs and anonymous usage of the app itself, never a figure you entered. The two opt-in exceptions — the AI Advisor and Share links — are detailed below.
🔒 Stored in your browser
Inputs, calculations, saved scenarios — all stored in your browser's local storage. Clear your browser data and it's gone; we have no copy.
🚫 No account, no signup
Use the full calculator without registering anything. No email, no profile, no marketing pipeline waiting to be hacked.
📊 Anonymous analytics only
PostHog gets click/scroll events tied to a random local UUID — no identifiers, no financial inputs, no AI conversations. Easy to block with any privacy extension.
🤖 AI Advisor — anonymized in transit
Plan numbers (no names, no account numbers, no institutions) go to Anthropic to generate the response, then discarded. We don't log requests; Anthropic doesn't train on them.
💳 Stripe handles payment
If you upgrade to Navigator, payment is processed by Stripe. We see a confirmation; Stripe handles every financial detail. No credit cards stored on our side.
🤝 Zero third-party data sales
We don't sell, rent, or share user data with third parties — because we don't have user data to share. The architecture makes it impossible, not a policy promise.
What this regime doesn't cover
Honest scope acknowledgment. Naming the limits is part of the trust posture, not a defect.
- Calculator results are projections, not guarantees. Monte Carlo gives confidence bands across simulated futures; reality is one path, not 1,000. Use these projections as planning instruments, not crystal balls.
- This is not financial, tax, investment, or legal advice. It's an informational and educational tool. For decisions involving significant money, consult a qualified fiduciary CFP, CPA, or estate attorney.
- Free-form AI prose quality. The eval set checks structural behavior. It doesn't grade subjective writing quality.
- Adversarial AI prompts designed to jailbreak. Out of scope for a retirement-calculator AI.
- Cross-model drift on provider updates. When Anthropic ships a new Haiku or Sonnet version, the AI eval set must be rerun and recalibrated.
- Real-time AI response telemetry. Tier D — live response-pattern monitoring — is queued for a future release.
- Edge cases not represented in personas. Our 49-persona corpus covers realistic edge cases but real-world situations have variations no corpus fully captures.
See these numbers for your own plan — free, no account, nothing leaves your browser.
Open the app