> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cfosilvia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Financial quiz funnel

# Financial Quiz Funnel

## Delivery Status

* Branch: `seo-financial-literacy-test`
* Status: implemented on the feature branch; not published to production
* Published: no
* Sanity changes: none
* Outbound email, SMS, or notification behavior: none
* Primary conversion: existing Clerk free-account signup after an ungated result
* Persisted quiz data: `public.quiz_sessions` + `public.quiz_answers` (RLS deny-all, service-role writes only). See "Session persistence" below and `docs/quiz-tracking.md`.
* Analytics: landing, start, completion, result view, retake, and signup click (all PostHog events now include the DB `session_id`), plus a `quiz_signup_attributed` event fired from `/auth/callback` when a signup is linked back to a quiz session.

## Routes

| Route | Assessment | Questions | Result Type |
| - | - | -: | - |
| `/financial-literacy` | Financial Literacy Test | 18 | Knowledge score, category breakdown, answer review |
| `/retirement-readiness-quiz` | Am I Ready to Retire? | 10 | Readiness estimate, projected savings, target, funding coverage |
| `/tax-intelligence-test` | Tax Intelligence Test | 7 | Knowledge score and sourced answer review |
| `/investing-iq-test` | Investing IQ Test | 7 | Knowledge score and sourced answer review |
| `/financial-planning-assessment` | Financial Planning Assessment | 8 | Planning-readiness score and weakest planning area |
| `/debt-knowledge-quiz` | Debt Knowledge Quiz | 7 | Knowledge score and sourced answer review |
| `/portfolio-knowledge-test` | Portfolio Knowledge Test | 7 | Knowledge score and sourced answer review |

Every route uses the existing public `SiteTopNav` and `SiteFooter`. The page
order is deliberately conversion-first:

1. Compact breadcrumb, H1, description, and trust facts.
2. First question, without an intro gate.
3. Immediate result and outcome-specific Silvia CTA.
4. Methodology, educational SEO copy, sources, related quizzes, FAQ, and disclaimer.

## Funnel and CTA Rules

Results are ungated. The user receives the answer before the account CTA.

The CTA is placed directly below the result headline and before secondary
diagnostics. It changes by outcome so the transition is relevant:

* Strong result: connect real accounts and put knowledge into practice.
* Developing result: identify gaps and organize the full financial picture.
* Low result: treat the score as a signal to act and build the foundation.
* Retirement ready: stress-test the retirement plan with actual account data.
* Retirement close: find the gap preventing a clear yes.
* Retirement not ready: build a plan before leaving employment income.

The signup URL includes `plan=free`, quiz ID, outcome, score, and referrer. It
does not include ages, balances, income, net worth, debt, or individual answers.

## Retirement Readiness Methodology

### Questions

| # | Category | Input |
| -: | - | - |
| 1 | Timing | Current age |
| 2 | Timing | Target retirement age |
| 3 | Income | Annual household income before taxes |
| 4 | Assets | Approximate net worth |
| 5 | Assets | Savings and investments available for retirement |
| 6 | Savings | Annual retirement contributions, including employer match |
| 7 | Spending | Expected annual retirement spending in today’s dollars |
| 8 | Income | Expected annual Social Security and pension income |
| 9 | Debt | Expected high-interest debt at retirement |
| 10 | Healthcare | Healthcare coverage and cost planning status |

### Calculation

The estimate uses the same general spending-gap framework documented for
Silvia’s retirement calculator:

1. Project retirement savings to the target age using 3% annual growth above inflation.
2. Calculate the annual portfolio income gap as retirement spending minus expected Social Security and pension income.
3. Divide the annual gap by a 4% planning withdrawal rate to create a simple portfolio target.
4. Compare projected savings with the target.
5. Add limited readiness credit for the current savings rate, high-interest debt plan, and healthcare preparation.

This is intentionally a screening estimate. It does not model taxes, investment
fees, market sequence risk, long-term care, lifespan, survivor needs, account
tax treatment, or benefit-rule changes. The UI never describes the estimate as
a guarantee or a recommendation to retire.

### Outcome Thresholds

| Score | Outcome | Primary CTA |
| -: | - | - |
| 85–100 | May be ready / on track for target age | Stress-Test My Retirement Plan |
| 65–84 | May be close | Build My Retirement Picture |
| 40–64 | Probably not ready yet | Start My Free Financial Plan |
| 0–39 | Significant retirement gap | Create My Free Silvia Account |

## Knowledge Test Keys

### Tax Intelligence Test

| # | Topic | Correct Concept | Primary Source |
| -: | - | - | - |
| 1 | Marginal brackets | Higher rate applies only to the income layer in that bracket | IRS |
| 2 | Credits and deductions | Credit reduces tax; deduction reduces taxable income | IRS |
| 3 | Withholding | Review after major income or life changes | IRS |
| 4 | Filing extension | Extends filing time, not payment time | IRS |
| 5 | Estimated tax | May apply when withholding does not cover income | IRS |
| 6 | Records | Support eligibility and amount claimed | IRS |
| 7 | RMDs | Traditional IRA RMDs generally begin at age 73 under current rules | IRS |

### Investing IQ Test

| # | Topic | Correct Concept | Primary Source |
| -: | - | - | - |
| 1 | Risk and return | Higher potential return generally means higher risk | Investor.gov |
| 2 | Diversification | Spread exposure; losses are not eliminated | Investor.gov |
| 3 | Compounding | Returns may earn additional returns | Investor.gov |
| 4 | Time horizon | Time until the money is needed affects tolerable volatility | Investor.gov |
| 5 | Employer match | Contributing enough may capture available employer contributions | Investor.gov |
| 6 | Fees | Fees reduce both value and the amount left to compound | Investor.gov |
| 7 | Fraud | High guaranteed returns with little or no risk are a warning sign | Investor.gov |

### Debt Knowledge Quiz

| # | Topic | Correct Concept | Primary Source |
| -: | - | - | - |
| 1 | APR | Useful for comparing yearly borrowing cost | CFPB |
| 2 | Minimum payments | Can extend repayment and increase interest | CFPB |
| 3 | Payoff order | Highest-rate-first generally minimizes interest after minimums | CFPB |
| 4 | Secured debt | Specific property serves as collateral | CFPB |
| 5 | Consolidation | Combines debts; does not automatically erase or reduce cost | CFPB |
| 6 | Payment trouble | Contact the lender or servicer promptly | CFPB |
| 7 | Debt stress | New borrowing for essentials can signal an unsustainable cycle | CFPB |

### Portfolio Knowledge Test

| # | Topic | Correct Concept | Primary Source |
| -: | - | - | - |
| 1 | Asset allocation | Mix of stocks, bonds, cash, and other asset classes | Investor.gov |
| 2 | Fund overlap | Several funds do not automatically create diversification | Investor.gov |
| 3 | Rebalancing | Return the portfolio toward its intended mix | Investor.gov |
| 4 | Concentration | One holding, sector, or exposure drives too much of the result | Investor.gov |
| 5 | Time horizon | Near-term essential money is poorly suited to high volatility | Investor.gov |
| 6 | Fees | Evaluate product and service costs together | Investor.gov |
| 7 | Benchmarking | Compare with a benchmark aligned to allocation and objective | Investor.gov |

## Financial Planning Assessment Key

The planning assessment has no objectively correct answers. Every item uses the
same maturity scale: current and specific (3), partial or stale (2), informal
(1), or not yet done (0).

| # | Planning Area |
| -: | - |
| 1 | Monthly cash flow |
| 2 | Current asset, account, and debt inventory |
| 3 | Emergency savings target |
| 4 | Dated and measurable goals |
| 5 | Expensive-debt payoff strategy |
| 6 | Insurance and essential estate documents |
| 7 | Retirement spending, income, and savings estimate |
| 8 | Annual and life-event review cadence |

## Design and Accessibility

* Existing public navigation and footer are reused without modification.
* New quiz surfaces use semantic theme tokens only; no new hardcoded colors.
* CTA surfaces use `bg-surface-card` with `text-content-title` and
  `text-content-muted`, avoiding the unreadable light-card/dark-theme pairing
  found in the first financial-literacy result CTA.
* Every question uses a fieldset and legend.
* Numeric fields have persistent labels, bounds, input modes, and inline errors.
* Choice labels and radio controls share a single touch target.
* Progress, result changes, and errors have accessible labels or live regions.
* Focus moves to the next question or result only after a user action.
* Raw personal answers are not written to the URL or PostHog events.

## Session persistence

Quiz sessions and answers are persisted to Supabase for growth reporting:

* `public.quiz_sessions` — one row per visit, keyed by a client-generated `session_id` (localStorage, per quiz). Stores the score, outcome, structured result data, and first-touch attribution captured on `/api/quiz/start` (`utm_source/medium/campaign/term/content`, `gclid`, `fbclid`, `ttclid`, `msclkid`, referrer, landing URL, user agent, hashed IP, geo).
* `public.quiz_answers` — one row per `(session_id, question_id)` with the latest answer, upserted on `/api/quiz/answer` so revisions overwrite rather than duplicate.
* `clerk_id` on `quiz_sessions` is filled in by `/api/quiz/attribute-signup` — the signup CTA appends `?quiz_session=<uuid>&quiz_id=<slug>` to the sign-up href and stashes the same pair in sessionStorage; `/auth/callback` reads it after Clerk resolves and hits the endpoint once per new signup. Retakes generate a fresh `session_id` so first-take conversion is measurable.

Both tables are RLS deny-all; all writes flow through `/api/quiz/*` using `SUPABASE_SERVICE_ROLE_KEY`. The four API routes (`/start`, `/answer`, `/complete`, `/attribute-signup`) use Upstash Redis for per-IP sliding-window rate limits and fail open on Redis errors so the browser experience is never blocked. The full architecture and column-by-column rationale is in [`docs/quiz-tracking.md`](../quiz-tracking.md).

## Benchmark Notes

* iA Financial’s retirement readiness quiz covers finances, health, housing,
  and retirement lifestyle and returns advice matched to the result.
* Family Investors uses a one-question-at-a-time 10-question flow covering
  retirement timing, income planning, confidence, taxes, and guaranteed income.
* U.S. Department of Labor retirement worksheets begin with age, expected
  retirement timing, projected income, assets, and expenses.
* SSA recommends using an official earnings-linked benefit estimate rather than
  guessing Social Security income.

The Silvia implementation keeps the ad-friendly step-by-step interaction and
outcome-specific next step, while publishing the assumptions and leaving the
result ungated.

## QA Record

The final branch pass covered the complete interaction, not only route renders:

* All seven routes loaded with the shared public navigation and footer.
* Every question in each quiz was answered in a real browser through the result state.
* The retirement ready-path returned 85/100, $1.2 million projected savings,
  a $750,000 simple target, 160% coverage, and the retirement stress-test CTA.
* The financial-literacy low path returned 0/100, the one-line attention
  headline, and the prominent `Start My Free Silvia Account` CTA.
* Repeating the same radio-option position on consecutive questions was tested;
  the radio group is keyed and remains controlled so the next button unlocks.
* Light and dark result surfaces passed automated WCAG A/AA checks with zero
  violations in the quiz UI. The existing gradient navigation signup button is
  reported as contrast-incomplete because the scanner cannot resolve its gradient.
* A 390-by-844 mobile pass found no horizontal overflow on the retirement start
  or portfolio result surfaces, and CTA buttons remain visible and full width.
* Targeted ESLint, TypeScript, and 34 Vitest checks pass.
* The production bundle compiles and completes its lint/type phase. Full page-data
  collection remains blocked in this local environment by the pre-existing
  `/api/account/delete` authenticator initialization and missing service credentials.

## Silvia Skills Sync

These are new public pages and user-visible flows. Per
`docs/SILVIA-SKILLS-SYNC.md`, a companion update to
`CFO-Silvia/skills/silvia-navigation-skills/SKILL.md` is required before the
feature is merged and deployed. The companion documentation has been prepared,
but the current GitHub account cannot push to `CFO-Silvia/skills`, and that
repository has forks disabled. A skills-repo maintainer must apply the prepared
navigation update and complete the normal S3 sync before this feature is
released.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.