For David, Ken, Sydney, BIX & Engineering
What this document does: Defines what we're building, in what order, and what "done" looks like. Organized around the customer experience, not an engineering backlog.
STAGES = the customer experience AND the service architecture. Each Stage is a standalone product that can be distributed independently via API. Build each Stage as if it will be sold separately, because it will.
PRIORITIES = the build order (what the team works on first, next, later).
Everything we build serves one of these moments
| Step | Name | Description |
|---|---|---|
| 1 | ARRIVE | Homeowner lands with a question |
| 2 | ADDRESS | Enter property, data hydrates automatically |
| 3 | CONVERSE | AI understands goals & situation |
| 4 | EXPLORE | Scenario cards with trade-offs |
| Step | Name | Description |
|---|---|---|
| 5 | ACCOUNT | Create account + MFA |
| 6 | VERIFY | Soft credit pull (single bureau) |
| 7 | REFINE | Scenarios update with real data |
| 8 | SAVE | Progress persists across sessions |
| Step | Name | Description |
|---|---|---|
| 9 | REPORT | PDF report + shareable links |
| 10 | DEEPEN | Advanced calcs, income verification |
| 11 | MONITOR | Rate alerts, return engagement |
The rule: Steps 1-4 must work perfectly on their own. Steps 5-8 layer on top without breaking anything. Steps 9-12+ enhance based on what we learn. A user who never goes past step 4 still got the full product.
What the user gets without creating an account
| # | Deliverable | What It Does & When It's Done | Why It Matters |
|---|---|---|---|
| 1 | Property Data Integration | Sources: Attom Data + Clarity Capital Experience: User enters property address. System auto-fills: estimated home value, property type, lot size, year built, tax assessment, existing loan estimates where available Fallback: If user declines to enter address or data is missing/incomplete, conversational fallback collects the same variables through warm questions. No dead end either way Done: Address lookup returns property data in <2 seconds. Missing fields trigger conversational collection. User can override any auto-filled value. Data hydrates the math engine correctly. |
THIS is the magical moment. User enters an address and the platform already knows their situation. Reduces friction from 15+ manual inputs to 1. |
| 2 | Rate Data Pipeline | Source: Freddie Mac PMMS (30yr, 15yr, 5/1 ARM). Weekly refresh. Redis cache Staleness: Indicator at >7 days. Fallback to last-known rates + disclosure at >48hrs Display: Every scenario card shows rate source and date. National averages in P1 Done: PMMS rates available. Cache <50ms. Staleness and fallback work on simulated failure. |
Scenarios need a rate to calculate payments. This runs behind the scenes while the user enters their address. |
| 3 | Scenario Math Engine | Output: 3-4 scenarios per user: monthly payment, total interest, break-even, trade-off summary All 5 motivations: Payment reduction, term reduction, equity access (cash-out), risk reduction (ARM to Fixed), equity conversion (HELOC/Reverse, guidance only + disclaimer) Performance: <2 seconds. FastAPI + numpy-financial Done: Validated against manual amortization for 20+ inputs across all 5 motivations. Accepts property-hydrated inputs and manual inputs equally. Zero incorrect math. |
The calculation engine behind every scenario card. Takes property data + rate data and produces the numbers. Interest rates will be national from a GSE. |
| # | Deliverable | What It Does & When It's Done | Why It Matters |
|---|---|---|---|
| 4 | Conversation Engine | Model: Claude API. System prompt handles all 5 refinance motivations Intent: Detects motivation within 3-5 warm-up messages Tone: Warm, 5th-grade language, non-sales. Adapts per archetype Recommendation Protocol: Acknowledge, Restate priorities, Align scenario, Return agency Prohibited: "I recommend," "you should," "best option," ranking scenarios Done: 15 test sessions (3 per archetype) confirm intent detection, warm tone, recommendation protocol, and zero prohibited language. |
The AI guide. Fills in any gaps property data didn't cover, understands the user's WHY, and drives toward scenario generation. Multi-Scenario Timeline Projection: "Show me what happens if I sell in 3 years vs. keep for 10." |
| 5 | Navigator (State Machine) | States: Landing, Property Input, Intent Discovery, Education (parallel), Scenario Generation, Scenario Exploration, Crisis Intervention, Summary, Soft Exit Architecture: State stack. Education is interruptive: enter/exit from any state with context preserved Guidance: "What happens next" at every state. Timeout 30 min. Encrypted localStorage 24hr Done: All transitions work. Education enters/exits from 3+ states with context. Timeout fires. No dead ends. |
The backbone. Orchestrates every state transition in the journey. Without it, the experience is a chatbot, not a product. |
| 6 | Oracle (Full) | Archetypes: 5 types: Analytical, Risk-Taking, Emotional, Practical, Cautious Target: 70%+ confidence by message 5 Method: Rule-based classification with VADER sentiment as secondary validation Logging: Every classification logged per message (future ML training data) Done: 70%+ confidence in 80%+ of test sessions by message 5. Tone adaptation perceptible in A/B comparison. All classifications logged. |
This IS the personalization. Without it, every user gets the same generic experience. With it, the platform adapts to who you are. |
| # | Deliverable | What It Does & When It's Done | Why It Matters |
|---|---|---|---|
| 7 | Scenario Cards UI | Design: Named paths with personality (not "Scenario A"). 3-4 cards per session Interaction: Sliders <200ms. Side-by-side comparison 2-4 cards. 60fps Responsive: Mobile-first (375px+). Next.js + D3.js/Recharts + Framer Motion Accessibility: WCAG 2.1 AA. Keyboard nav. ARIA labels. 4.5:1 contrast. 44x44px touch targets Done: All 5 motivations render mobile + desktop. Sliders <200ms. WCAG audit passes. Screen reader announces card name, payment, trade-off. |
The core product surface. This is what the user interacts with. Everything else exists to get them here and help them understand what they see. |
| 8 | Education System | Content: 5th-grade visualizations: amortization, compound interest, break-even, trade-offs Variants: 2+ explanation approaches per concept (Magical Moment fallback) Accessibility: Data table or text alternative for every chart Done: 4 core concepts render. Each has 2+ variants. Every chart has accessible alternative. |
The "feel smart" layer. Users explore concepts without feeling talked down to. Feeds directly into the Magical Moment. |
| # | Deliverable | What It Does & When It's Done | Why It Matters |
|---|---|---|---|
| 9 | Magical Moment (Full) | Trigger: Repeated confusion or frustration detected by Advisor Visual: 500ms fade, chart simplification (60% data reduction, 150% font increase, high-contrast), cubic-bezier easing Content: Alternative analogy, simplified explanation, "Want to see this differently?" interactive element Motion: Respects prefers-reduced-motion (instant transitions when active) Done: Animation triggers correctly on crisis detection. Visual morphing is smooth at 60fps. Alternative explanation renders. 75%+ of test users continue exploring after trigger. |
The product differentiator. The moment the platform transforms from "cool tool" to "this thing gets me." This is what nobody else has. |
| 10 | Advisor (Basic to Full) | Ships basic: 3 states (confused, frustrated, confident). Claude prompt-based. Simplify on confusion, reassure on frustration. Crisis trigger on repeated confusion Upgrades to full within P1: 8 states (add anxious, excited, impatient, overwhelmed, disengaged). VADER dual-model validation. Proactive interventions. Celebration moments. Dynamic real-time tone Done (basic): 3 emotions detected. Tone shifts visibly. Crisis triggers correctly Done (full): 8 emotions detected. VADER validates Claude. Proactive interventions fire before abandonment. Celebration triggers on confidence. |
Why we exist. Hundreds of thousands of families were denied or discouraged because nobody met them where they were emotionally. The Advisor ensures PreFi never loses someone to confusion or frustration the way the old system did. |
| 11 | Error Handling | Covers: Unrealistic inputs, rate staleness, low AI confidence, session timeout, calc failure, LLM timeout (retry + template fallback + circuit breaker), unsupported scenario, property data lookup failure Principle: No user-facing errors. Every failure has a warm recovery Done: Each condition tested via simulation. User never sees broken state or dead end. |
Invisible when working. Catastrophic when missing. This is what makes the experience feel solid instead of fragile. |
| 12 | Analytics | Tool: PostHog. Session lifecycle, card interactions, emotion per turn, crisis triggers, property data coverage rates Coverage: All 12 success metrics measurable. Real-time funnel Done: Every component emits events. All metrics computable. Dashboard shows live funnel. |
Without this, beta tells us nothing. This is how we know if the empowerment model works. |
| 13 | Post-Session Survey | Questions: 2-3 at Soft Exit: Neutrality, Comprehension, "Got Me" Moment. 5-point Likert. Optional Done: Renders at Soft Exit. Skip works. Responses feed metrics. |
The data that determines Go/No-Go. |
P1 Core Complete = A homeowner enters their address, the platform hydrates their data, an AI conversation understands their goals, scenario cards show personalized options, the Magical Moment catches them when they're confused, and they leave understanding their refinance options, all without creating an account.
Stage as Service: The P1 Core anonymous exploration experience is a standalone product. It can be distributed independently via API. Any partner, platform, or lender can embed the Clarity Engine's conversation-to-scenario flow without requiring account creation, credit pulls, or marketplace connectivity. Build it as a self-contained service.
Account + credit pull, built before beta users arrive
| # | Deliverable | Description & Key Requirements | Why It Matters |
|---|---|---|---|
| 14 | Account Creation + MFA | Supabase Auth. Email + Google + Apple. MFA required. <60 second creation. Offered at Summary or when user requests credit pull. Never before. Decline = zero friction return to anonymous experience. NOT required for any P1 Core feature. | The gateway to verified scenarios. Optional. The anonymous experience is complete without it. |
| 15 | Soft Credit Pull | Gated behind account (#14). Single bureau (confirmed in discovery). Dedicated consent modal with plain language on what changes and doesn't. "Check My Credit" + "No thanks." Once per session, not re-raised if declined. Graceful failure handling. | Scenarios go from estimates to real numbers. The value exchange that justifies account creation. |
| 16 | Scenario Refinement | After credit pull, scenarios recalculate with real data. Cards animate changes. AI explains what changed. Better score = celebrate. Different = reassure + adjusted paths. | The payoff. User sees their scenarios sharpen from estimates to reality. |
| 17 | Saved Progress | Authenticated users return to saved scenarios. Server-side persistence (encrypted). "Welcome back." Unauthenticated sessions still use localStorage (24hr). | The reason to create an account beyond credit pull. Your exploration persists. |
Stage as Service: The authenticated verification layer is a standalone service. Account creation, identity verification, and soft credit pull can be offered independently. Any partner needing verified borrower data with consent-driven credit checks can consume this Stage via API without the conversation or scenario engine.
Report, enhance, and refine, informed by real user data
| # | Deliverable | Description | Why It Waits |
|---|---|---|---|
| 18 | PDF Report | Downloadable PDF: scenarios, trade-offs, rate assumptions, inputs, disclaimers. PreFi branded. Mobile/desktop. | The experience IS the P1 product. The report is a takeaway, not the product itself. |
| 19 | Shareable Reports | Email a report or generate a hyperlink to share with partners, advisors, family, spouse. Read-only scenario summary at the link. | Requires report (#18). Sharing needs auth + permissions + link generation. |
| 20 | Advanced Calculators | Tax implications, investment opportunity cost, multi-variable break-even, full amortization timeline visualizations. | P1 covers core math. Adds depth for Analytical archetype. |
| 21 | Income/Asset Verification | Truv or Hycron integration. Manual upload fallback. Progressive enhancement (spouse income, 401K, additional assets). | Extends verification beyond credit. Needs credit pull (Late P1) working first. |
| 22 | EI Refinement | Tune Oracle classifier and Advisor interventions using beta data. Improve archetype detection accuracy. Refine crisis intervention triggers based on real user patterns. | Requires real user data from P1 beta to know what to tune. |
Stage as Service: The report and sharing layer is a standalone service. Scenario summaries, PDF generation, and shareable links can be consumed via API by partners who want to deliver branded financial education reports without building their own scenario engine.
Extending PreFi beyond refinancing into property wealth building
P3 transforms PreFi from a one-time refinance exploration tool into an ongoing relationship with the homeowner. The Clarity Engine's educational model and emotional intelligence extend into new domains, all focused on helping homeowners maximize the value of their property.
Delivery model: Hybrid. Educational content is available to all users (including anonymous). Personalized recommendations require an account. Light proactive alerts are opt-in for authenticated users.
Two tracks: Homeowner Nurture (primary track, for all homeowners) and Investor Benefits (separate sub-section, for real estate investors). Both use the same Clarity Engine infrastructure.
Helping homeowners make smarter decisions about the property they already own.
| # | Deliverable | Description | Value to Homeowner |
|---|---|---|---|
| 23 | Mortgage Math Continuing Ed | Equity building strategies, recast vs. refinance comparison, prepayment analysis, bi-weekly payment impact. Interactive calculators using the same scenario card model from P1. AI explains concepts at the user's archetype level. | Most homeowners don't understand what they're paying or why. This turns confusion into strategy. |
| 24 | Title Holding Optimization | Educational guidance on how to best hold title: joint tenancy, community property, trust structures, survivorship implications. State-specific considerations. Scenario comparisons showing tax and legal trade-offs of each approach. | Title structure affects taxes, inheritance, and asset protection. Most homeowners never revisit this after closing. |
| 25 | Property Tax Reduction | Homestead exemption eligibility and application guidance. Assessment appeal process education. Senior, veteran, and disability exemptions. Deadline tracking and proactive reminders (opt-in). State/county-specific rules. | Veterans especially qualify for exemptions they don't know exist. Directly addresses the mission. |
| 26 | Insurance Intelligence | Dec page review: upload insurance declaration page, AI analyzes coverage gaps, identifies potential savings. Premium optimization suggestions. Replacement cost vs. market value education. | Most homeowners are either over-insured (overpaying) or under-insured (at risk). Both are fixable. |
| 27 | Proactive Opportunity Alerts | Opt-in alerts when: rates drop enough to change saved scenarios, property tax deadlines approach, assessment appeal windows open, insurance renewal is upcoming. User controls frequency. Single-click unsubscribe. | The reason to stay engaged. PreFi becomes the homeowner's ongoing advisor, not a one-time tool. |
Extending the Clarity Engine to real estate investors with specialized financial education.
| # | Deliverable | Description | Value to Investor |
|---|---|---|---|
| 28 | DSCR Education & Scenarios | Debt Service Coverage Ratio explained through the Clarity Engine model. Interactive scenarios showing how rental income, expenses, and loan terms affect DSCR. Qualification guidance for DSCR loan programs. | DSCR loans are growing fast but most investors don't understand the math. Same empowerment model, different audience. |
| 29 | Cost Segregation Overview | Educational content on cost segregation benefits, eligibility, and ROI. High-level scenario modeling showing potential tax savings. Guidance on when to engage a specialist. Connects to AutoSeg platform vision. | Investors leave thousands on the table. Education creates demand for the AutoSeg platform. |
| 30 | 1031 Exchange Guidance | Timeline requirements, identification rules, qualified intermediary roles. Scenario comparisons: sell and pay taxes vs. 1031 exchange vs. Delaware Statutory Trust. Educational, not advisory. | Most common investor question, most commonly misunderstood process. |
| 31 | Rental Income Optimization | Cash flow analysis, expense categorization, depreciation education, tax benefit scenario modeling. Connects property data from P1 to investor-specific calculations. | Turns property data into investment intelligence. |
P3 EI Extension: The Oracle and Advisor continue to refine across all P3 content. New domains (tax, insurance, investment) require new archetype patterns and emotional signatures. Every P3 interaction generates training data that further improves the EI system.
Stage as Service: The nurture layer is a standalone product. Property tax optimization, title holding guidance, insurance intelligence, and investor education can each be distributed independently. A veterans' organization could consume only the property tax exemption service. A real estate investment platform could consume only the DSCR and 1031 modules. Each is an independent API service.
Marketplace, licensing, and platform distribution
Built only after the empowerment model is proven (P1/P2 beta) and the nurture model demonstrates retention (P3). P4 also marks the expansion from refinance into purchase financing, extending the Clarity Engine from fundability ("am I eligible?") to affordability ("what can I actually afford and what does that home look like?").
| # | Deliverable | Description |
|---|---|---|
| 32 | Purchase Scenario Engine | Extend the math engine and conversation flow to purchase financing. Pre-qualification scenarios, affordability analysis, down payment strategies, first-time buyer programs, VA purchase benefits. Same empowerment model: clarity through scenarios, not sales pressure. |
| 33 | Fundability to Affordability | Two-phase experience: (1) Fundability: can the borrower qualify? Credit, income, DTI assessment. (2) Affordability: what does qualified purchasing power look like in real homes, real neighborhoods? Connects property data to purchasing scenarios. |
| # | Deliverable | Description |
|---|---|---|
| 34 | Lender Marketplace | User-initiated for fulfillment of scenarios. Explicit consent. MISMO 3.6 data package. |
| 35 | Lead Quality Package | Verified data + emotional journey summary + scenario heatmap + "why they chose you" AI summary. $400-$800 justification. |
| 36 | Multi-Tenant Infrastructure | tenant_id, row-level security, config-driven. Add tenant <1 day. |
| 37 | White-Label UI | Custom logos, colors, fonts, domains. Brand swap <3 days. |
| 38 | ML Pipeline | Fine-tuned archetype classifier (90%+). Trained on P1+P2+P3 data. Continuous learning. |
| 39 | API Marketplace | Public API, dev portal, rate limiting, webhooks. Stages as independent services. |
| 40 | Expanded Marketplace | 10+ lenders, live rates, MISMO 3.6, performance tracking. |
| 41 | Partnership Integrations | MonsterLead, Lofty, agent/lender networks. Referral flows. |
| 42 | Proactive Rate Alerts | Opt-in email/SMS when rates materially change saved scenarios. User-controlled. Single-click unsubscribe. |
| 43 | Voice Interface | Speech-to-text, text-to-speech, hybrid mode. 95%+ transcription. |
| 44 | Admin Dashboard | Internal: funnels, completion, EI metrics, conversation monitoring, lender analytics. CSV export. |
These exist because the product we build today must support the platform we build tomorrow.
| # | Principle | Details |
|---|---|---|
| 1 | API-First, Services-First | Every Stage is built as an independent service with its own API surface. The frontend consumes APIs. OpenAPI spec documented. Versioning (v1) from day one. Each Stage must be deployable, testable, and distributable independently. A partner can consume the scenario engine without the conversation layer, or the verification service without the education system. This is not future optionality; it is the business model. |
| 2 | MISMO-Compatible Data Model | MISMO 3.6-compatible field names from the first migration. Naming conventions now vs. database refactors later. |
| 3 | Log for the ML Future | Every Oracle classification, Advisor detection, crisis outcome, and interaction pattern. Structured, timestamped, session-keyed. This IS the training data for P3's fine-tuned models. |
| 4 | Education, Not Advice | Prohibited: "I recommend," "you should," "best option." Permitted: "This path addresses your stated goal because..." Legal, regulatory, brand-defining. |
| 5 | Accessible by Default | WCAG 2.1 AA from first commit. Keyboard, screen reader, contrast, touch targets, reduced motion. Not accessible = not done. |
| 6 | No Dead Ends | Every error has a warm recovery. Every edge case degrades gracefully. If we can't handle it elegantly, we don't ship it. |
| 7 | Bank-Level Security from Day 1 | Privacy, security, and compliance are promises, not compromises. All data encrypted at rest (AES-256) and in transit (TLS 1.3). No PII on server for unauthenticated users. Encrypted localStorage (24hr expiry). Credit pull is opt-in, gated behind account, offered once, declined without friction. SOC 2 Type I certification target. |