SimpleFinanceDash/.planning/research/FEATURES.md

# Feature Research

**Domain:** Personal budget app — wizard-driven setup, auto-budget creation, simplified monthly tracking UX
**Researched:** 2026-04-02
**Confidence:** MEDIUM — grounded in competitor analysis (YNAB, Monarch, EveryDollar, Actual Budget, Quicken Simplifi, Copilot) and UX/fintech design literature. Some specifics are inferred from behavioral patterns; no first-party user testing data.

---

## Context

This research covers v2.0 UX Simplification. The existing app already has all the data infrastructure — categories (6 types), template system, monthly budget generation, quick-add library, dashboard with charts. The problem is cognitive: too many disconnected concepts, friction in getting a budget running, and no guided experience for new users.

The research question: **How do personal budget apps handle first-run wizard setup, auto-creation from template, and simplified monthly views?** What is table stakes, what differentiates, and what should be avoided?

Existing features that remain and are not re-researched here:
- Category CRUD
- Template item management
- Budget detail with inline editing
- Charts (donut, bar, horizontal bar)
- Collapsible dashboard sections
- Settings (locale, currency)

---

## Feature Landscape

### Table Stakes (Users Expect These)

Features users assume exist. Missing these = product feels incomplete or broken.

| Feature | Why Expected | Complexity | Notes |
|---------|--------------|------------|-------|
| Wizard-style first-run setup | Every modern app (YNAB, EveryDollar, Monarch) guides new users through initial setup — no blank-slate drop. Blank-state is a known retention killer for budget apps. | MEDIUM | Multi-step flow: income → recurring items → review. Must be skippable per step. |
| Pre-filled category items with common defaults | Users expect "rent," "groceries," "car insurance" to already be there — not to type everything from scratch. YNAB's Beginner Template and Quicken Simplifi both provide starter category lists. | LOW | Pre-seed the wizard with a curated list of ~15-20 common items grouped by type. User selects/deselects, edits amounts. |
| Auto-created budget on first month visit | After setup, users expect a budget to exist for the current month without a separate "generate budget" step. The manual trigger pattern is a v1-era pattern that creates friction. Quicken Simplifi does this with its Spending Plan. | MEDIUM | Trigger auto-generation server-side when a user visits the current month and no budget exists. |
| Ability to skip setup and start minimal | Power users and returning users want to start blank or skip ahead. Forcing everyone through a wizard is patronizing. | LOW | Each wizard step needs a "Skip" option. Entire wizard skippable via "I'll set this up later." |
| Inline add-from-library on the budget view | Users expect to add a one-off expense from their familiar item list without navigating away. The current separate Quick-Add page is a disconnect. Spendee and Actual Budget surface this inline. | MEDIUM | Replace Quick-Add page with an inline panel/sheet triggered from the budget view. Category + item picker, amount field, confirm. |
| Monthly budget shows budgeted vs actual, grouped | The core interaction loop: open budget, see what's in each category, enter actuals. Every app (YNAB, EveryDollar, Actual Budget) organizes this as grouped rows with a budgeted amount and an actuals field. | LOW | Already exists in the current BudgetDetailPage. Table stakes means this must work correctly and clearly — not changed, just verified. |
| Dashboard = this month's budget at a glance | Users want to open the app and immediately know their status: income, spending, balance. Not a chart gallery. Monarch and Copilot both lead with a "current month" summary card. | LOW | Dashboard must surface current month's data prominently — summary cards first, then detail. Already partially true; needs data correctness fix. |
| Empty state with clear call to action | If no template is set up, the app must explain what to do — not just show a blank page. "Set up your budget template" with a single action button. | LOW | Applies to: empty template page, empty budget view, empty dashboard. |

### Differentiators (Competitive Advantage)

Features that set the product apart. Not required, but valued.

| Feature | Value Proposition | Complexity | Notes |
|---------|-------------------|------------|-------|
| Smart amount suggestions during wizard setup | Rather than blank amount fields, prefill with sensible defaults (e.g., $1,500 for rent, $400 for groceries) that users can override. Reduces the "I don't know what to put here" paralysis. Most apps leave this blank. | LOW | Can be static defaults (not AI). Store suggested amounts per item type in a constant/config. User edits freely. |
| "Start from your income" wizard framing | Frame setup as: "First, how much do you earn each month?" then "Here are common expenses people like you track." Income-first anchoring mirrors zero-based budgeting mental model (YNAB's core concept) and makes subsequent amounts feel grounded. | LOW | First wizard step = income amount. Subsequent steps show remaining balance updating as items are added — "you have $X left to allocate." |
| Running balance display during wizard | As the user adds items in the wizard, show "Remaining to allocate: $X" updating live. Makes it immediately obvious if they're over-allocating. This is YNAB's core interaction loop, applied to setup. | LOW | Derived from: income total minus sum of bill/expense/debt/saving/investment items. Frontend computation only. |
| Persistent sidebar "this month" widget on dashboard | A small always-visible card showing remaining balance for the month, top 2-3 categories near limit, and a "View full budget" link. Eliminates the need to navigate away to check status. Copilot uses this pattern. | MEDIUM | Requires current month budget query always running. Can be a sticky sidebar panel on the dashboard page rather than a global element. |
| Auto-create silently, notify only on first creation | First-time users see a brief notification "Your March budget was created from your template." Subsequent months: silently created, no notification. This is the right default — zero friction for users who've set up their template. | LOW | Backend: check if budget for current month exists on page load; create if not. Frontend: show a toast only if a new budget was just created. |
| Template edit directly accessible from monthly view | If a user wants to permanently change a recurring item (e.g., rent went up), they should be able to jump to the template from the budget view without hunting through the nav. | LOW | An "Edit template" link on the budget page or a per-item "Save to template" action. Single nav jump, no modal complexity. |

### Anti-Features (Commonly Requested, Often Problematic)

Features that seem good but create problems in this context.

| Feature | Why Requested | Why Problematic | Alternative |
|---------|---------------|-----------------|-------------|
| AI-suggested amounts based on spending history | "Smart defaults should learn from me over time" | Requires enough historical data (users don't have it at setup), an ML model or LLM call, and privacy tradeoffs. The payoff is low when static defaults work fine for first-run. | Static curated defaults per item type. After 3+ months of use, a "Review your template" prompt is sufficient. |
| Mandatory wizard (no escape) | "Force users to complete setup so they have a working budget" | Patronizing for returning users; creates frustration for users who want to explore before committing. YNAB's old onboarding got negative feedback for being too locked-in; they added a flexible checklist in Oct 2025 for this reason. | Skippable wizard with a prominent resume-later CTA. Show a "Complete setup" banner if template is empty. |
| Auto-sync with bank accounts | "Automatically populate actuals from transactions" | Plaid/bank integrations add significant infrastructure cost, security scope, and maintenance burden. Out of scope for a self-hosted personal tool. | Manual actual entry (inline editing, already implemented) with optional import as a future feature. |
| Complex wizard with 6+ steps | "Guide the user through every aspect of budgeting" | Drop-off increases sharply with each step beyond 3. Users who see step 4 of 7 abandon setup entirely. | Max 3 steps: (1) Income, (2) Recurring items, (3) Review + confirm. Everything else is editable post-setup. |
| Per-item recurrence configuration in wizard | "Let users set whether each item is weekly, monthly, etc." | Adds decision burden during setup. The app model is monthly budgeting — every item is implicitly monthly. Edge cases (weekly, biweekly) should be post-setup configuration. | Monthly-only assumption during wizard. Users can edit frequency on the template page after setup. |
| Gamification / streaks for budget tracking | "Engage users to check in daily" | Budget apps that add gamification often feel gimmicky for a personal finance tool. The target user is tracking a spreadsheet replacement — they want data, not achievements. | Progress indicators (spent X% of budget) provide motivation without game mechanics. |
| Duplicate "Quick Add" page alongside inline add | "Keep the existing page and add inline too" | Two ways to do the same thing creates confusion about which to use. The standalone Quick Add page has no added value over an inline approach. | Replace entirely with inline add-from-library on the budget view. Remove the nav link for the old Quick Add page. |

---

## Feature Dependencies

```
Wizard Setup
    └──requires──> Pre-seeded library items (common defaults in DB or seed data)
    └──requires──> Template CRUD (already exists)
    └──produces──> Populated template (unlocks auto-creation)
    └──enhances──> Smart amount suggestions (display layer only)
    └──enhances──> Running balance during wizard (computed from income + items)

Auto-Budget Creation
    └──requires──> Populated template (wizard must complete, or manual template setup)
    └──requires──> Backend trigger logic (check if budget for month exists; create if not)
    └──produces──> Current month budget (unlocks simplified budget view)
    └──enhances──> Silent creation toast (frontend notification, optional)

Simplified Budget View (inline add from library)
    └──requires──> Current month budget exists (auto-creation must fire first)
    └──requires──> Category library with quick-add items (already exists as quick_add_items table)
    └──replaces──> Standalone Quick Add page (remove from nav)
    └──enhances──> Budget detail (adds inline picker panel alongside existing inline editing)

Dashboard = This Month at a Glance
    └──requires──> Current month budget exists (auto-creation must fire first)
    └──requires──> Budget data correctness fix (tracked separately)
    └──depends-on──> Simplified budget view (users need to be able to add actuals quickly)

Template Edit from Budget View
    └──requires──> Template page (already exists)
    └──enhances──> Simplified budget view (provides escape hatch to change recurring items)
```

### Dependency Notes

- **Wizard depends on pre-seeded library:** The wizard presents pre-filled common items. These must exist in the database (or a constants file) before the wizard can show them. This is the foundational data concern for v2.0.
- **Auto-creation depends on template having content:** If the user skips the wizard entirely, auto-creation generates an empty budget (no items). The UI must handle this gracefully — show empty-state with "Set up your template" CTA.
- **Inline add replaces Quick Add page:** This is a replacement, not an addition. The Quick Add page should be removed from the nav. The backend endpoint it uses can be repurposed or kept as the inline add trigger.
- **Dashboard correctness is a prerequisite:** The "dashboard = this month at a glance" feature is only meaningful if the data it displays is accurate. Data correctness fix must happen before or alongside the dashboard simplification.

---

## MVP Definition

This is v2.0 of an existing working app. "MVP" here means: what is the minimum set of changes that delivers the simplified UX without regressions?

### Launch With (v2.0 — Core UX Simplification)

- [ ] Wizard-style template setup — 3-step flow: income → common items (pre-filled, editable) → review — skippable
- [ ] Pre-seeded library with ~15-20 common items grouped by category type (rent, car insurance, groceries, utilities, car payment, etc.)
- [ ] Smart amount defaults in wizard (static sensible values per item — not AI)
- [ ] Running balance during wizard (income minus sum of selected items)
- [ ] Auto-create current month budget from template on first visit (backend trigger, silent)
- [ ] Toast notification on first auto-creation only ("Your April budget was created from your template")
- [ ] Inline add-from-library on the budget view (replaces Quick Add page)
- [ ] Remove Quick Add from navigation
- [ ] Dashboard summary cards correctly reflect current month budget data
- [ ] Empty state CTAs for: empty template, empty dashboard, empty budget

### Add After Core Ships (v2.x)

- [ ] "Edit template" shortcut from budget view — once core flow is working, add the escape hatch
- [ ] Persistent "this month" summary widget on dashboard — adds value once data is correct
- [ ] "Complete setup" banner for users who skipped wizard but have empty template
- [ ] Wizard resume-later state (save partial wizard progress) — only needed if drop-off is observed

### Future Consideration (v3+)

- [ ] Income-based spending recommendations (percentages by category type)
- [ ] "Review your template" prompt after 3 months of use
- [ ] CSV/bank import for actuals — mentioned as future feature in PROJECT.md
- [ ] Recurring transaction automation — mentioned as future in PROJECT.md

---

## Feature Prioritization Matrix

| Feature | User Value | Implementation Cost | Priority |
|---------|------------|---------------------|----------|
| Wizard setup (3-step, skippable) | HIGH | MEDIUM | P1 |
| Pre-seeded library items (15-20 defaults) | HIGH | LOW | P1 |
| Smart amount defaults in wizard | MEDIUM | LOW | P1 |
| Running balance during wizard | HIGH | LOW | P1 |
| Auto-create budget on month visit | HIGH | MEDIUM | P1 |
| Dashboard data correctness fix | HIGH | MEDIUM | P1 |
| Inline add-from-library on budget view | HIGH | MEDIUM | P1 |
| Remove Quick Add page from nav | MEDIUM | LOW | P1 |
| Empty state CTAs (template, dashboard, budget) | MEDIUM | LOW | P1 |
| Silent creation with first-time toast | MEDIUM | LOW | P2 |
| "Edit template" link from budget view | MEDIUM | LOW | P2 |
| Persistent "this month" dashboard widget | MEDIUM | MEDIUM | P2 |
| "Complete setup" banner for empty template | LOW | LOW | P2 |
| Wizard resume-later persistence | LOW | MEDIUM | P3 |

**Priority key:**
- P1: Must ship for v2.0 to feel complete
- P2: Should have; include if effort allows
- P3: Nice to have; future consideration

---

## Competitor Feature Analysis

| Feature | YNAB | Monarch Money | EveryDollar | Quicken Simplifi | Our Approach |
|---------|------|---------------|-------------|------------------|--------------|
| First-run wizard | Flexible checklist (Oct 2025 update); Beginner Template to import categories | Guided category setup on signup; AI auto-categorizes after account link | Wizard-style setup; named "best for newbies" | Template import + Spending Plan auto-setup | 3-step wizard: income → items → review |
| Pre-filled defaults | Beginner Template with common categories (mortgage, groceries, vacation) | Default category list; user trims | Pre-loaded category list | Category templates to import | ~15-20 curated items, editable in wizard |
| Auto-budget creation | Manual monthly allocation required ("assign every dollar") | Spending Plan auto-projects from past data + recurring detected | Manual each month; no auto-create | Spending Plan auto-calculates and updates | Auto-create from template on month visit; silent |
| Add expense inline vs separate | Inline per category row; no separate page | Inline transaction entry | Separate transaction entry form | Inline via Spending Plan category rows | Inline panel on budget view; Quick Add page removed |
| Dashboard focus | "To be budgeted" balance + category status | Monthly spending summary + goals | Zero-based plan + remaining | Spending Plan summary + bills calendar | Summary cards (income/expense/balance) + current month budget |
| Skippable setup | Yes (since Oct 2025 checklist) | Yes | Limited | Yes | Yes — every step skippable |

---

## Wizard Flow Design Notes

Based on research into YNAB, EveryDollar, and UX onboarding best practices, the recommended wizard structure is:

**Step 1 — Income**
- Single question: "What's your monthly take-home income?"
- Single number input + currency formatting
- Skip option: "I'll add this later"
- Sets the anchor for running balance in step 2

**Step 2 — Recurring Items**
- Pre-loaded list of common items grouped by type (bills, variable expenses, debts, savings, investments)
- Each item has a checkbox (on by default for high-likelihood items, off for lower-likelihood)
- Editable amount field per item (prefilled with static sensible default)
- Running balance updates live: "Remaining to allocate: $X"
- "Add custom item" inline for items not in the list
- Skip option: "I'll set this up manually"

**Step 3 — Review**
- Summary of selected items by group
- Total income, total allocated, remaining
- "Create my template" CTA — writes to the template table
- "Go back" link to step 2

**Post-wizard:**
- Auto-create current month budget from template (immediate)
- Show toast: "Your [Month] budget has been created"
- Land on budget view for current month

**Confidence:** MEDIUM — pattern validated by YNAB (beginner template import), EveryDollar (wizard-style), and UX onboarding research. 3-step max is validated by drop-off research (complexity above 3 steps correlates with abandonment).

---

## Inline Add-From-Library Design Notes

The existing Quick Add page uses a library of one-off items (`quick_add_items` table). In v2.0, this interaction moves inline to the budget view.

**Recommended pattern (based on fintech UX research):**
- Trigger: "Add item" button in each category section header on the budget view
- Mechanism: A slide-in panel or modal sheet (not a full page navigation)
- Contents: Category pre-selected (from which section was clicked); searchable list of library items for that category type; amount field; description field
- On confirm: Item added to budget for the month, totals update immediately
- On dismiss: Panel closes, no navigation

**Why panel/sheet over modal:**
- Modals block background context; users lose their place in the budget
- A slide-in sheet (shadcn/ui Sheet component) keeps the budget visible alongside the picker
- Smashing Magazine (2026): "modals work for quick confirmations; sheets work for contextual data entry tasks"

**Why not keep the separate Quick Add page:**
- Two surfaces for the same action creates confusion (which should I use?)
- The separate page breaks the flow — user must navigate away, losing their place
- Inline keeps the budget view as the single place for monthly budget work

---

## Sources

- [YNAB Beginner Template and category setup](https://www.ynab.com/templates)
- [YNAB new flexible checklist for mobile (Oct 2025)](https://www.ynab.com/whats-new)
- [YNAB vs Copilot AI comparison 2025 — ZenFinanceAI](https://zenfinanceai.com/ynab-vs-copilot-ai/)
- [Monarch Money budget creation documentation](https://help.monarch.com/hc/en-us/articles/360048883631-Creating-Your-Budget-in-Monarch)
- [Monarch vs EveryDollar comparison — BudgetCoachUSA](https://budgetcoachusa.com/monarch-vs-everydollar/)
- [Top Personal Finance Apps with Customizable Budget Categories 2026 — Quicken](https://www.quicken.com/blog/top-personal-finance-apps-with-customizable-budget-categories/)
- [Best Budget Apps 2026 — NerdWallet](https://www.nerdwallet.com/finance/learn/best-budget-apps)
- [Best Budget Apps 2026 — Engadget](https://www.engadget.com/apps/best-budgeting-apps-120036303.html)
- [How Great Budget App Design Increases User Retention — Onething Design](https://www.onething.design/post/budget-app-design)
- [UX Onboarding Best Practices 2025 — UX Design Institute](https://www.uxdesigninstitute.com/blog/ux-onboarding-best-practices-guide/)
- [Budget App Design Tips from Fintech Experts — Eleken](https://www.eleken.co/blog-posts/budget-app-design)
- [Modal vs. Separate Page: UX Decision Tree — Smashing Magazine](https://www.smashingmagazine.com/2026/03/modal-separate-page-ux-decision-tree/)
- [Actual Budget — self-hosted open source](https://actualbudget.org/)
- [App Onboarding Guide 2026 — UXCam](https://uxcam.com/blog/10-apps-with-great-user-onboarding/)
- [Fintech App Top 20 Financial UX Dos and Don'ts — UXDA](https://theuxda.com/blog/top-20-financial-ux-dos-and-donts-to-boost-customer-experience)

---

*Feature research for: SimpleFinanceDash v2.0 — wizard setup, auto-budget creation, simplified monthly tracking UX*
*Researched: 2026-04-02*