# RetiFlo — Assumptions & Limitations

**Status:** Living document · **Owner:** Product/Engineering · **Last reviewed:** 2026-07-22
**Governs product copy:** claims in-app, in marketing, and in advisor deliverables must not
contradict this inventory (enforced in part by the honesty-gate tests in
`apps/web/src/lib/__tests__/honestyGate_*.test.ts`).

RetiFlo is an **educational retirement-planning and analytics tool**. It is **not** tax,
legal, or investment advice, and it does not replace a CPA, EA, CFP, or attorney. Every
projection is a model built on the simplifications below. This document is the
compliance-grade inventory of those simplifications, kept so that no user-facing claim
overstates what the engine actually computes.

> **Project philosophy that drives these choices:** *"Fallback data that impacts a
> calculation is more dangerous to the user than a complete system failure. At least with a
> failure, we didn't potentially lie to the user."* Where a required figure is missing, the
> engine **fails loud** rather than substituting a guess (see §6.2 fail-loud getters and the
> K2 regulatory manifest). This document covers the *modeled-but-simplified* cases; the
> fail-loud cases cover the *missing* ones.

---

## 1. Scope & intended use

- Audience: pre-retirees and the advisors who work with them. Projections are
  **illustrative**, not guarantees of any future outcome.
- All figures are **pre-tax-year-2026 nominal U.S. dollars** unless a projection applies
  modeled inflation. U.S. residents only; no non-U.S. tax or benefit systems are modeled.
- Results depend entirely on user-entered data and the assumptions selected. Garbage in,
  garbage out — the tool does not validate that entered balances, incomes, or ages are
  truthful.

## 2. Federal income tax

- **Modeled:** ordinary-income brackets, standard deduction, the age-65 additional standard
  deduction, the temporary OBBBA senior deduction (2025–2028, with phaseout), long-term
  capital-gains/qualified-dividend rate brackets, student-loan-interest deduction phaseout,
  and Social Security taxability under IRC §86.
- **Simplified / not modeled:** AMT; the Net Investment Income Tax (3.8%); most credits
  (child, education, EV, saver's, foreign tax); itemized deductions beyond the configured
  set; QBI; state/local tax interaction with itemizing (SALT); employment/self-employment
  tax; the "kiddie tax"; and any brackets/thresholds not present in the seeded config.
- Brackets and deductions are **annually-indexed published figures** tracked in the K2
  regulatory manifest with a `reviewBy` date; a rolled tax year without re-attestation
  fails the staleness CI check.
- **Filing status changes mid-projection.** A household that loses a spouse files jointly for
  the year of the death and as a **single filer from the start of the next tax year** — brackets,
  standard deduction, §86 Social Security thresholds, LTCG brackets, the senior-deduction and
  student-loan phase-outs, and the IRMAA ladder all move together on that date. **Dependents are
  not modeled**, so the two further years of joint rates available to a qualifying surviving
  spouse with a dependent child (IRC §2(a)) are not applied; that **overstates** tax for the
  households it would apply to. A **divorce** switches filing status for the **entire divorce year**,
  per the IRC §7703 rule that marital status on 31 December governs the whole year (corrected
  2026-09-03; it previously switched at the divorce month). The pre-divorce months of that year
  still carry both spouses' income while being taxed single, which **overstates** tax slightly for
  that one year — the direction this product prefers to err. Only `single` and
  `married_filing_jointly` are modeled; a household needing married-filing-separately uses the
  override paths.

### 2a. How annual tax is built from monthly slices (YTD marginal, 2026-07-23)

Ordinary-income tax is computed **month by month** as each slice of income is recognized, taxed at its
marginal rate stacked on the income already recognized that year (year-to-date). A year's monthly taxes
therefore sum **exactly** to the tax on the year's total — no matter how uneven the timing is. This
replaced an earlier method that annualized each month's income ×12, which overstated tax on lumpy years
(a one-month RMD or a January Roth conversion was taxed as if it recurred all twelve months).

**Display note (known, cosmetic):** because tax is recognized when income is, the **monthly** tax column
is intentionally lumpy — a large figure in the month of an RMD or Roth conversion, near-$0 in quiet
months, and a **December true-up that can be negative** when itemized deductions reduce the year's tax
below what the earlier months withheld. The **annual** tax figure is the correct, canonical view; the
monthly column is a cash-timing detail. Smoothing/annotating the monthly display is a deferred UI-only
follow-up (I-8) — it must never alter the money model, so it stays out of the engine.

### 2b. Withdrawal-generated tax funding — FIXED (2026-07-22)

Taxes triggered **by a portfolio withdrawal** — federal and state income tax on a tax-deferred
(IRA/401k) distribution, and brokerage capital-gains tax — are funded by drawing more from the
portfolio (an iterative gross-up: after the withdrawal, the engine draws enough to cover that
withdrawal's own tax, converging in a few passes; any residual after the cap becomes shortfall).
This covers **all** withdrawal paths — expense-driven withdrawals as well as the tax on pre-tax
**transfers** and **fund-from-withdrawal** shortfalls. Portfolio depletion and out-of-money dates for
withdrawal-heavy plans are correct. See `plans/withdrawal-tax-grossup-plan.md`.

## 3. State income tax

- Modeled **conditionally**: state income tax on ordinary income is added **only** for
  states with a curated `StateTaxProfile`. For any state without one, the engine returns
  **federal-only** and reports `stateTaxes = 0` — never a blended guess.
- State handling is a **simplified graduated model**. Local/municipal income taxes,
  state-specific retirement-income exclusions beyond those curated, state AMT, and
  state-specific credits are **not** modeled. Some states are explicitly marked
  `needsReview` or **not-modeled** and should be treated as federal-only.
- Because production per-state coverage is partial, user-facing copy must **not** make a
  flat "federal + state" tax co-claim (enforced by `honestyGate_federalStateClaim.test.ts`).
  Expose state tax only via a **qualified** label (e.g. "0 when the state is not modeled").

## 4. Social Security

- Claiming: early-claiming reduction (5/9 of 1% per month for the first 36, 5/12 thereafter)
  and delayed-retirement credits (2/3 of 1% per month to age 70) per SSA rules; FRA by
  birth-year schedule. Golden-tested against SSA published percentages.
- **Approximation:** the year-by-year schedule generator applies a **flat current-year SS
  amount across all years** — it does not vary the benefit by future COLA or a changed
  claiming age within the schedule view (the full projection engine does apply COLA).
- Taxability: IRC §86 provisional-income thresholds are the **non-indexed 1984/1993 statutory
  amounts** ($25k/$34k single, $32k/$44k joint) — they do not inflate, so more of a benefit
  becomes taxable over time, as in current law.
- **Solvency haircut:** an optional projected post-depletion benefit reduction sourced from
  the SSA Trustees Report. This is a **projection of a policy that has not happened**, not a
  scheduled cut.

## 5. Required Minimum Distributions (RMDs)

- Uses the **IRS Pub 590-B Uniform Lifetime Table (Table III)**, 2022+ factors
  (golden-tested), and SECURE 2.0 birth-year → start-age rules (73 for 1951–1959, 75 for
  1960+). Single-life factors are used where applicable.
- **Timing:** each year's RMD executes in the **first month of the year the account
  owner attains (or has passed) RMD age** — including the first RMD, which lands in the
  attainment year itself (even for a Dec 31 birthday). The engine deliberately does
  **not** model the IRS option to defer the first RMD to April 1 of the following year,
  because that path forces two taxable RMDs into the second year. The first-month
  balance approximates the prior Dec-31 balance, the IRS basis for the year's RMD, and
  the divisor is the Uniform Lifetime factor for the age **attained during** the
  distribution year. There is no sub-annual optimization of *when* within the year to
  distribute.
- **Per-owner schedules:** each account RMDs on its **own owner's** attained age — a
  spouse's IRA waits for (and uses the divisor of) that spouse, not the primary
  planholder. An account marked joint-owned follows the primary (IRAs/401(k)s cannot
  truly be jointly owned).
- **Joint Life and Last Survivor Table (Table II):** applied when the plan has a
  partner **more than 10 years younger** than the account owner (attained ages, per the
  IRS rule), producing the smaller Table II RMD. **Assumption:** the spouse is treated
  as the account's **sole designated beneficiary** — beneficiary designations are not
  tracked per account, so a plan whose actual beneficiary is not the spouse (or not
  sole) would overstate the divisor / understate the RMD in this narrow case. Table II
  stops applying (falls back to the Uniform table) in years after the spouse's death.
  Spouse ages below 20 use the published table's age-20 column (conservative — larger
  RMDs). Table data: IRS Pub 590-B Appendix B, 2022+ factors, provenance-tracked in the
  K2 regulatory manifest.

## 6. Medicare & IRMAA

- Part B standard premium and Part B/D IRMAA surcharge tiers are modeled with the
  **two-year MAGI lookback**. IRMAA MAGI includes Roth conversions and capital gains.
- **Filing status selects the threshold ladder.** Each tier carries both the individual and the
  married-filing-jointly boundary; the premium attached to a tier is the same either way. A
  household with two living people is measured against the joint column, and **a survivor moves to
  the individual column** — their first cliff roughly halves — from the month their spouse dies.
  Two simplifications there, both erring toward the more expensive answer: the switch lands in the
  month of the passing rather than the following tax year, and **married filing separately is not
  modeled** (CMS publishes a three-tier ladder for it; households needing it use the override paths).
- **Vintage:** Part B and Part D are both **2026** figures as of 2026-08-23 (Part B from the CMS
  Parts A & B fact sheet, Part D from that plus the separate Part D bid-information notice for the
  base beneficiary premium). They are flagged in the K2 manifest with a `reviewBy` tied to the CMS
  November announcement and should be refreshed annually. Users near an IRMAA cliff should treat the
  surcharge tier as approximate until the current-year CMS notice is seeded.
- **Boundary convention:** CMS makes only the top boundary exclusive ("greater than or equal to
  $500,000"); the engine compares with `≤` throughout, so an income of exactly $500,000 is placed
  one tier low. Recorded rather than fudged — see OW-085.

## 7. Healthcare out-of-pocket costs

- Pre-Medicare (ACA) premiums, Medigap/supplement premiums, and out-of-pocket estimates are
  **national-average survey figures** (KFF/CMS/HHS), **not** plan-, insurer-, or
  location-specific quotes. Actual costs vary widely by state, age-rating, and plan choice.
- **ACA premium tax credit (2026-09).** Estimated ACA premiums for pre-65 household members
  are shown **net of an estimated §36B premium tax credit**, computed from the household's
  own projected income under the law in force for 2026 — including the **400%-of-poverty-level
  cliff**, above which the entire credit ends. This is an estimate, not an eligibility ruling:
  the benchmark is a national Silver-plan proxy rather than your rating area's actual
  second-lowest Silver plan; below 100% of the poverty level no credit is modeled (Medicaid
  eligibility differs by state and is not determined here); Alaska/Hawaii poverty-guideline
  variants and cost-sharing reductions are not modeled. A premium you enter yourself is used
  exactly as entered — never adjusted. Each simplification errs toward overstating your costs.

## 8. Long-term care (LTC)

- LTC cost defaults to a **national-average annual figure** with a fixed modeled duration.
  The engine supports either an end-of-life anchored window or an explicit user-defined
  event window. LTC is a **high-variance, deeply personal cost**; the national average is a
  planning placeholder, not a prediction for any individual.
- **State figures are deliberately set ~20% above published statewide medians (2026-09).**
  A statewide median under-prices the metro areas where most households live — metro
  private-room medians can run 60%+ above their state's figure — and understating a cost
  makes a plan look safer than it is. The uplift is uniform, disclosed conservatism, not a
  metro-level prediction; households who know their own local figure can set per-person care
  costs directly on the Future Events timeline, and that entered figure always wins.
- **LTC insurance (2026-09-05):** each party may hold a traditional or hybrid policy. The
  level monthly premium is modeled as an expense while they are alive; during their care
  window the policy's **benefit pool** (default $165,000, growing at the priced 3% option)
  pays care costs first, and only costs beyond the remaining pool fall to the household —
  the pool caps the offset, it never simply zeroes LTC cost. Estimated traditional premiums
  are **AALTCI national age/sex averages** (a market index, not a quote — carrier spreads
  reach 80% for the same profile); a user- or advisor-entered premium and pool always
  override. Hybrid policies are priced only from an entered quote. **Not modeled:** premium
  rate increases (premiums are held level), premium waiver during claim, elimination
  periods, shared-care/couple discounts (omitting them errs toward overstating cost), and
  tax deductibility of premiums or benefits.

## 9. Real estate & reverse mortgage

- Home-sale gain uses the IRC §121 exclusion ($250k single / $500k joint, non-indexed) with
  a residency check and modeled selling costs.
- **Reverse mortgage (HECM):** the available principal is a **simplified approximation of the
  HUD actuarial Principal Limit Factor tables** (HUD Handbook 4235.1), keyed off a base
  factor and expected-rate adjustment — **not** the exact current HUD PLF lookup. Treat
  reverse-mortgage proceeds as an estimate; a HUD-counseled quote is authoritative.

- **Nothing is modeled AT the second death (decided 2026-09-06, OW-109).** The projection
  runs to the later longevity and reconciles the final partial year's taxes at the death
  month, and per-person flows stop at each person's own death — but no estate settlement,
  basis step-up, or final expenses occur at the second death. Deliberate: every candidate
  effect there changes only what heirs receive, and the product makes no heir-facing value
  claim (the estate feature is a document checklist). An heir-facing Estate Module is
  specified as a future feature under evaluation (PRD §13.5); if it is built, settlement,
  §1014 step-up at the second death, and IRD treatment of tax-deferred balances are its
  scope, not the projection's.

## 9a. Divorce, death, and community property (2026-07-30)

Every asset and debt carries an **owner** (member / spouse / joint), and the property law of the
state the household lives in **at the event date** decides how each one divides. The regime is
derived from the profile's state and moved by a relocation event — it is not a static setting.

- **Community-property states** — `AZ CA ID LA NM NV TX WA WI` (Wisconsin's Marital Property Act
  is included). Assets *and* debts divide 50/50 at divorce regardless of whose name is on them, and
  the survivor continues to carry the deceased spouse's debts. Five further states
  (`AK FL KY SD TN`) allow community property only by **election**; living there is not enough, so
  it must be asserted explicitly.
- **All other states** — ownership decides: the member keeps their own, the ex-spouse's leaves the
  plan, and jointly-held items divide by the percentage entered. At a death, a debt that was solely
  the decedent's is settled out of the estate and does not follow the survivor.

**Limitations you should know about:**

- **Step-up in basis at the first death (IRC §1014) is modeled** — the decedent's own holdings are
  revalued in full and half of anything jointly held, or *everything* in a community-property state
  (the §1014(b)(6) double step-up). The adjustment runs in both directions: a holding that has lost
  value steps **down**. It applies to taxable brokerage/cash accounts and to real estate (treated as
  jointly held, since properties carry no owner), and deliberately **not** to 401(k)s or traditional
  IRAs — those are income in respect of a decedent and receive no step-up under §1014(c).
- **Your existing unrealized gain is recognized — if you record it.** Enter a cost basis on a
  taxable brokerage account and the projection treats the difference between it and today's balance
  as gain you have already accrued, taxable proportionally as you draw the account down. **If you
  leave it blank, the projection assumes there is no built-up gain**, which understates the tax you
  would owe on withdrawals. The app says so where you enter it. Only brokerage accounts have a cost
  basis; cash accounts and tax-advantaged accounts do not need one.
- **Separate property is not modeled.** Pre-marital, inherited, and gifted assets legally remain
  separate even in a community-property state; the plan tracks an owner, not a separate/community
  classification, so a community-property split treats everything as community.
- **The division and the estate settlement are untaxed and pro-rata.** Basis scales with value (no
  gain realized) and the amounts come proportionally from all accounts rather than through the
  withdrawal order.
- **Real estate is not divided at divorce.** Model a property disposal as a sale before the split
  date and divide the proceeds.
- **Federal and private student loans are not distinguished.** Federal student loans are discharged
  at death with no estate claim; the plan has no such flag, so all debt types settle identically.
- **Debts with no owner recorded** are treated as jointly owed — the conservative reading. They are
  flagged in the app rather than assigned a default.
- **Retirement plans:** ERISA-qualified accounts (401k/403b/pension) are governed by federal law
  regardless of state — a real divorce splits them via a **QDRO**, and beneficiary changes need
  spousal consent. The projection does not model QDRO mechanics. IRAs are not ERISA-protected and
  do carry a community-property interest.
- **Social Security is never community property.** It is federal; divorced-spouse benefits follow
  the federal 10-year-marriage rule and are unaffected by any of the above.

## 10. Monte Carlo & spending guardrails

- Monte Carlo draws returns via a **Box-Muller normal** model around the selected
  expected/volatility assumptions — a **stylized** return process, not a bootstrap of actual
  historical sequences (a separate historical-sequence stress feature exists for that).
- **Dynamic spending guardrails:** three methods — Vanguard-style ceiling/floor,
  Guyton-Klinger, and a **risk-based** method built on a precomputed success-rate surface
  (itself a stylized MC, trilinear-interpolated, shipped to a ±3pp fidelity gate vs. the
  engine). All are **decision rules layered on the model**, not predictions.
- **Compounding convention:** the engine uses **discrete monthly compounding**
  ((1+r)^(1/12)), consistently across growth, inflation, and the risk surface.

## 11. Inflation

- A single running-product inflation multiplier is applied by category (general, housing,
  healthcare, education, etc.). Category inflation rates are assumptions, not forecasts.
  Users may override inflation for specific future year bands (What-If); the year-band
  override applies to GENERAL inflation only.

## 11a. Education funding & 529 plans (2026-09-05)

- College costs are modeled as **education expense entries** (the staged window on the
  Expenses page), inflated at the scenario's **college-cost inflation** assumption rather
  than general inflation.
- With the education line's **"funded from the 529 account first"** setting on, the
  projection pays education costs from 529 balances before any other account — treated as
  **qualified distributions (tax-free)**. Costs beyond the 529 balance fall back to the
  regular withdrawal order and are taxed normally.
- 529 balances are **never** drawn for retirement spending, whatever the withdrawal order
  says. **Non-qualified 529 withdrawals** (10% penalty plus earnings taxation) are **not
  modeled** — the tool only ever routes qualified education dollars through a 529. State 529
  deduction benefits are not modeled (state taxes are approximate throughout).
- Contributions to a 529 are modeled like any account: the asset's annual contribution
  (while its owner's salary runs) or scheduled transfers.

## 12. Advisor-authored adjustments

- Advisors may apply a **variance layer** (adjusting balances, income, expenses, expected
  return, or inflation, whole-stream or from a future year onward). These are **the
  advisor's inputs and the advisor's professional responsibility** — the tool records and
  applies them transparently (append-version history, shown with the underlying engine value
  and the advisor's rationale) but does not validate their reasonableness. Existing
  disclaimers govern; see `questions-for-lawyers.md` #26.

## 13. Calculation-verification program (Tier 6 §6.12) & honest claims

RetiFlo's math is checked by a layered program, **not** (yet) by an external professional
review. Current state:

| Layer | What it does | Status |
|-------|--------------|--------|
| K1 — Golden-example tests | Expected values cite IRS Pub 590-B / SSA published figures, breaking circular self-consistency | ✅ shipped |
| K2 — Regulatory manifest + staleness CI | Every published figure cites its source, tax year, and `reviewBy`; a rolled year fails CI | ✅ shipped |
| K3 — Cross-validation fixtures | Full sample households computed independently by hand, asserted end-to-end | ✅ shipped |
| K4 — This document | Compliance-grade inventory governing product copy | ✅ shipped |
| K5 — External CPA/EA review | Independent professional review of tax + RMD logic against K1/K3 artifacts | ⛔ not yet performed |

**Honest-claim rule (D-K3):** because K5 has not happened, **no user-facing surface may
claim the calculations are "verified," "CPA-reviewed," "professionally verified," or
"guaranteed accurate."** The honest interim claim is:

> *"Calculations are checked against externally-anchored golden tests reproducing published
> IRS and SSA examples."*

This restriction is enforced by `honestyGate_verifiedClaim.test.ts`. It should be relaxed
only when K5 is complete and its audit trail (who reviewed what, against which publication
year) exists — at which point the claim wording is a new question for legal (rides with
`questions-for-lawyers.md` #26/#27).

---

## Review cadence

- **Annually (January):** re-attest every K2-manifest figure against the current published
  IRS/SSA/CMS values; refresh anything past its `reviewBy`.
- **On any engine change** touching tax, RMD, SS, Medicare, or guardrails: confirm the K1
  golden tests and K3 cross-validation fixtures still pass and update this document if a
  simplification changed.