Scope of work · Goal Planning App

Goal Planning App: UI/UX PRD

Product requirements · May 2026 · current product authority for UI/UX

Problem Statement

Self-directed Indian retail investors lack a single tool that lets them (a) test whether a portfolio strategy can plausibly fund a real life goal, (b) pick real funds that map to that strategy with rigour, (c) track whether their actual investing matches the plan they committed to, and (d) backtest portfolios against history before trusting any forward-looking simulation. The four existing tools the user pulled inspiration from each solve at most one of these well, and none target the Indian market with its NSE indices, AMFI fund universe, and SIP-driven savings behaviour. Users currently have to stitch together Excel sheets, fund factsheets, and US-centric simulators — losing the analytical rigour and the visceral, "your real path lives somewhere inside this cone of outcomes" intuition that helps a retail investor stay invested through volatility.

Solution

A web app with four independent but linked top-level entities — Goal Scenario Analysis, Fund Selection & Screeners, Progress and Portfolio Tracking, and Backtesting. The user defines goals (Accumulate to a target, or Withdraw from a corpus), runs probabilistic simulations on the 20-asset NSE index universe to find portfolio strategies that meet the goal, picks real Indian mutual funds that map to those indices using the existing Persistence Framework screener, commits a frozen Scenario Reference Document to each goal, defines an event journal of SIPs and lump-sums, and watches their real portfolio path overlay onto the simulated cone of outcomes. A separate Backtester answers "how would this portfolio have performed historically?" using the same shared portfolio library. Progressive disclosure keeps simple defaults visible to most users while exposing every methodology lever to the power user who wants it.

Target Users

Self-directed Indian retail investor. Familiar with basic fund terms, runs 3–10 SIPs, comfortable with concepts like "asset allocation" and "expense ratio" but not "block bootstrap" or "sequence of returns risk." Uses the app to plan goals, pick funds, and check progress.
Informed DIY investor / fund-curious enthusiast. Reads enough financial blogs to want a real downside number ("if it misses, how badly?"), wants to compare aggressive vs conservative portfolios, will explore the bucket drill-down and the trial-by-trial table.
Power user / advisor. Wants every methodology knob (block min/max years, simulation count, bootstrap parameters), wants per-trial sequences, wants to backtest at fund-level with custom rebalancing. Interacts mostly through Advanced Settings and the Backtester.

User Stories

Goal Scenario Analysis

As a new user, I want a starter template gallery (Retirement / House / Education / Vacation / Marriage) so I don't stare at an empty form.
As a user, I want to create a goal and pick a goal flavour (Accumulate to a target, or Withdraw from a corpus) so the form adapts to my situation.
As a user, I want to set my target amount, horizon in years, and starting portfolio value so the simulation has the basics it needs.
As a user, I want to start with one portfolio in my comparison, and add more incrementally up to five, so I am not forced to define five at once.
As a user, I want to populate a portfolio from a preset library (60/40, HFEA, Permanent Portfolio, Golden Butterfly, Three Fund, Coffeehouse, Yale Endowment, Couch Potato, etc.) so I don't fill 20 empty rows by hand.
As a user, I want to add and remove asset rows from the testfolio-style picker (Equities / Fixed Income / Alternatives) so my active rows reflect my actual portfolio.
As a user, I want a sticky 100% total badge with green/yellow/red colour states and a one-click Normalize button so I always know whether my weights balance.
As a user, I want gear-menu actions (Equal Weight / Normalize / Clear / Mirror Beginning) so common allocation operations are one click.
As a user, I want to define a glide path as "hold the beginning portfolio for X years, then transition over Y years to the ending portfolio" and see a live stacked-area preview of the asset mix evolving over the goal horizon.
As a user with a short-term Accumulate goal that ends in a one-shot withdrawal, I want the system to suggest a glide that derisks toward cash by horizon, so I don't end up holding equities the day I need the money.
As a user, I want to define cashflow events using Variation B (rigid compact: monthly contribution + annual top-up + one-time events) so the common case is fast.
As a user, I want to also try defining cashflow events using Variation C (timeline canvas: visible horizontal timeline of the goal horizon, click a year to add an event there) so I can see the cashflow shape over time.
As a user, I want all amounts entered in today's rupees by default, with a "show nominal" display toggle, so I'm not silently mixing real and nominal.
As a user, I want recurring streams to be inflation-adjusted by default and one-time events to be not-inflation-adjusted by default, so the defaults match my mental model.
As a user, I want recurring events to default their end-condition to "Goal horizon" so I'm not fiddling with end years for the common case.
As a user, I want a one-line live summary above the events list ("Net contributions: ₹X over N years (today's rupees)") so I have a sanity check before running the simulation.
As a user, I want simple defaults (block bootstrap only, ~4000 trials, sensible block min/max) so I never have to touch methodology on day one.
As a power user, I want to expose Advanced Settings to override block min/max years, increase the number of simulations to 10K or 20K (paid tier), and inspect the bootstrap parameters.
As a user, I want the simulation to use direct historical sampling for horizons under 7 years and block bootstrap for horizons of 7 years or more, without me having to know which is which.
As a user, I want to compare up to five portfolios on the same goal in a summary table, with metrics as rows and portfolios as columns.
As a user, I want each cell of the summary table colour-coded best/worst per row so I can scan dominance at a glance.
As a user, I want column headers in the summary table to carry a "Compare" checkbox; checking exactly two surfaces a sticky CTA "Deep-dive: A vs B →" that opens the comparison workbench preloaded with that pair.
As a user, I want the comparison workbench to let me freely pick Portfolio A, Portfolio B, and the comparison vector (Fan chart / Terminal wealth histogram / MWRR over time / Trial drill-down / Range of outcomes / Goal Range) and have the chart auto-render after a brief debounce.
As a user, I want the workbench to support all three layouts — overlay (single canvas, both portfolios coloured differently), side-by-side small multiples, stacked small multiples — so I can pick what reads best for the chart and screen.
As a user, I want responsive behaviour: side-by-side degrades to stacked on viewports under ~900px; overlay stays overlay.
As a user, I want a smart pre-fill on first landing in the workbench (Pair = the two portfolios with the largest delta on Chance of Success; chart = Fan chart) so I'm not configuring three empty selectors.
As a user, I want the per-portfolio results page to show a headline strip on top: a donut visualisation, the giant Chance-of-Success %, a contextual narrative sentence, and a 5-bucket trial breakdown row (Very Comfortably Meet / Comfortably Meet / On Target / Likely Miss / Very Likely Miss) with absolute trial counts.
As a user, I want the bucket counts to be clickable: clicking a bucket highlights the individual paths from that bucket on the main chart at year/quarter granularity AND opens the Trial drill-down tab pre-filtered to that bucket.
As a user, I want a "Clear filter" affordance to restore all trials.
As a user, I want bucket thresholds (150% / 110% / 90% / 50% of target) as smart defaults and configurable in Advanced Settings.
As a user, I want the main chart for an Accumulation goal to be a fan chart with two orthogonal toggles: Smooth / Full and Cross-at-Year / Cross-at-Value.
As a user, I want the main chart for a Withdrawal goal to be a Depletion fan: paths declining from starting corpus, zero-line highlighted, ruined trials coloured red.
As a user, I want a logarithmic Y-axis by default with a linear toggle.
As a user, I want a horizontal target-amount line on Accumulation charts (with the PortfolioCharts-style attached badge) and a zero-line on Withdrawal charts.
As a user, I want secondary visualisations available: Terminal wealth histogram (with vertical bucket-boundary lines) and MWRR fan chart over time.
As a power user, I want a Trial drill-down table (PL-style: sparkline + historical block sequence + terminal value + categorical result) so I can read individual trials.
As a user, I want each component to be buildable as an independent, composable unit so layouts can be tested empirically rather than designed up front.

Goal flavours

As a user, I want exactly two goal flavours: Accumulate to target, and Withdraw from corpus. No "accumulate-then-withdraw" combined flavour.
As a user planning retirement, I want to model it as two linked goals (an Accumulation goal followed by a Withdrawal goal) so each simulation stays within the historical data envelope and the two-phase plan is honest about what the math can support.
As a user, I want a visual "→" connector between two goals on the dashboard when they're chained (an Accumulation goal feeding a Withdrawal goal) with a tooltip explaining the chain.

As a user, I want to save up to 10 portfolios in my Portfolio Library, each with version control, so my work is preserved without unbounded sprawl.
As a user, I want preset portfolios (Boglehead, Permanent, etc.) to NOT count against my 10-portfolio cap, since they're library resources.
As a user, I want each portfolio to support 5–10 versions with FIFO eviction of the oldest version when capacity is exceeded.
As a user, I want a portfolio version to become immutable once it's referenced by a committed Scenario Reference (a goal is tracking against it). Editing forces a new version.
As a user, I want to "delete" a portfolio by archiving it (30-day trash with restore affordance), not destroy it permanently.
As a user, I want to save up to 5 goals.
As a user, I want exploratory simulation runs to be free (not counted against any cap) — only an explicit commit of a scenario to a goal creates a Scenario Reference.
As a user, I want each Scenario Reference Document to be immutable — re-running with edits creates a new vintage.
As a user, I want exactly one vintage of a goal's Scenario Reference to be "active" at any time, switchable by me.
As a user, I want a vertical line marker on the tracking chart at any vintage transition date with a hover note "Plan changed: now using v2."

Fund Selection & Screeners

As a user, I want the Fund Selection & Screeners entity to remain its own independent surface — fund-centric, not goal-centric — so I can browse funds without committing to a goal first.
As a user, I want the screener to expose persistence analysis (Signal + Confidence scoring on rolling 3Y/5Y windows) and regime capture (calm vs stress) for every fund, in line with the existing Persistence Framework spec.
As a user inside the screener, I want a "Save to Goal" affordance on every fund, with a multi-select dropdown of my goals, so I can tag a fund to one or more goals.
As a user, I want the screener and its outputs (Persistence Table, Fund Profile, Comparison, Category Overview) to live behind their existing routes (/screener, /fund/:scheme_code, /compare, /category/:style_label).

Asset Class → Fund Mapping (lives inside Goal)

As a user, once I have both a committed Scenario Reference and tagged funds for a goal, I want to see an Asset Class → Fund Mapping screen inside the goal.
As a user, I want the mapping screen to show every Asset Class slot from my Scenario Reference, with the funds I've tagged in that category listed under it at 0% allocation.
As a user, I want to manually allocate weights across the listed funds (no auto-equal-weighting), so I own the allocation decision — friction by design.
As a user, I want each fund row to show its persistence Signal score from the screener inline (read-only) so I have data to decide.
As a user, I want a running total per slot showing % allocated and % remaining, with red validation if a slot is under or over 100%.
As a user, I want to save the mapping as a draft if it's incomplete, so I don't have to finish it in one sitting.
As a user, I want the mapping to refuse to commit until every slot sums to 100%.
As a user, I want microcopy that explains why we don't auto-allocate: "We don't auto-allocate across funds because the choice depends on your conviction. Allocate based on what you'd actually buy."

Progress and Portfolio Tracking

As a user, I want Tracking to be a separate top-level entity from Goal Scenario Analysis, so planning and checking-in are different mental modes.
As a user, I want manual entry only in V1 — no Plaid, no broker integration. Brokerage links to Zerodha / IndMoney are V2/V3.
As a user, I want to enter a small set of events per fund rather than periodic portfolio values: SIP start, SIP modification, SIP stop, Lumpsum purchase, Redemption, Switch (within AMC), Rebalance (plan-level event).
As a user, I want a SIP defined once (fund, monthly amount, start date, day-of-month, optional end date) to auto-generate one purchase event per month at the prevailing NAV — I should not need to enter monthly check-ins.
As a user, I want to declare a Rebalance event as "as of [date], rebalance to my target weights" and have the engine compute the implied switches without me itemising each leg.
As a user, I want the system to compute my real portfolio value at any date from my event journal × AMFI NAV history, so the value chart updates automatically.
As a user, I want the tracking chart to show a 300-path representative subset of the 4000-trial cone (stratified to preserve the percentile distribution) so the visual stays parseable.
As a user, I want my real portfolio path overlaid as a thick black line on the simulated cone, anchored on the same time axis.
As a user, I want a metrics row above the tracking chart with: current value, % to goal, tracking percentile ("currently tracking near P54 of the original plan"), updated Chance of Success, drift from plan (cumulative contribution gap), closest historical analog ("closest historical match: 1973–1977 sequence").
As a user, I want to toggle between "Original Plan" view (static reference cone, default — answers is my reality normal?) and "From here forward" view (live re-simulation from current state — answers should I change anything now?).
As a user, I want a Match-to-Closest-Trial feature with strong "this is one possible analog, not a forecast" microcopy, so my real path can be paired with the historical sequence it most resembles.
As a user, I want plan-vs-reality drift to be decomposed visually into contribution drift, allocation drift, and market drift so I understand why I'm behind, not just that I'm behind.
As a user, I want target-weight nudges: "You're 6% over target on Mid Cap. Consider rebalancing on next SIP."

Backtesting

As a user, I want a separate Backtester entity at the top level — not nested inside Scenario Analysis or the Screener.
As a user, I want to run a single-portfolio backtest (pick portfolio, weights, start/end, optional contribution schedule) and see realised CAGR, max drawdown, Sharpe, terminal value, vs benchmark.
As a user, I want a SIP backtest mode tuned to the dominant Indian retail use case ("₹X/month SIP in Fund Y from date A to date B").
As a user, I want a multi-portfolio comparison backtest (2–3 portfolios on the same historical path).
As a user, I want a rolling-start backtest (same portfolio, every possible start date for a fixed horizon) — V1 implementation can be monthly-resolution and assume no rebalancing for cheap compute.
As a user, I want a stress-period backtest (pre-defined "2008 crash," "COVID 2020," etc.) — naturally available wherever the fund/index has history.
As a user, I want a single "Index-level / Fund-level" toggle at the top of the Backtester — index-level for the ideal-world comparison, fund-level for the real-world comparison.
As a user, I want the Backtester to read from the shared Portfolio Library so I can backtest any saved portfolio in one click.

Dashboard and cross-entity

As a user, I want a top-level dashboard listing all my goals with status (Plan / Track), per-goal Chance of Success, current value vs plan, and a total-monthly-contribution rollup across goals.
As a user, I want the four entities — Goals, Funds, Tracking, Backtester — as top-level navigation peers.
As a user, I want the Portfolio Library to be a shared resource accessible from Goals, Tracking, and Backtester.

Empty / error / recovery

As a brand-new user with no goals saved, I want a welcome surface with a starter template gallery and a "Create your first goal" CTA so the empty Goals dashboard isn't intimidating.
As a user who has reached the 10-portfolio cap, I want a clear message and a path to archive an existing portfolio before creating a new one.
As a user who has reached the 5-goal or 5-scenario cap, I want a similar clear message and archive path.
As a user who tries to commit a fund mapping with under- or over-allocated slots, I want the commit blocked with red validation messaging on the offending slots.
As a user who tries to edit a portfolio version that's referenced by a committed Scenario, I want a prompt: "This version is committed to [Goal Name]. Editing creates a new version." with options to confirm or cancel.
As a user who deletes a goal, I want its committed scenario vintages archived alongside it (TBD per Open Questions).
As a user who archives a portfolio in the 30-day trash, I want a Restore button visible from Settings → Archived Items.

"I changed my mind" paths

As a user, I want to undo a fund-to-goal tag at any time from the screener (untag) or from the goal (remove).
As a user, I want to switch the active vintage of a goal's Scenario Reference at any time, with the tracking chart re-anchoring to the new active.
As a user, I want to delete an event from my event journal at any time, with the tracking chart recomputing.
As a user, I want to roll back to a previous portfolio version from the version history.

Screens & Surfaces

Purpose: house the four top-level entities and the shared Portfolio Library.
Entry points: every page.
Primary content: four top-level tabs (Goals / Funds / Tracking / Backtester). Portfolio Library access from a sidebar or shared header.
Primary actions: switch between entities; access settings.
States: authenticated; unauthenticated landing (out of scope for this PRD).
Exits: each top-level entity.

S2. Goals Dashboard

Purpose: at-a-glance view of all of the user's goals.
Entry points: Goals tab.
Primary content: card or list of saved goals (max 5), each showing name, flavour, status (Plan/Track), Chance of Success, current value vs plan, target, horizon. A total-monthly-contribution rollup figure across all goals. Visual "→" connectors between chained goals (Accumulation → Withdrawal).
Primary actions: create new goal, open a goal, archive a goal.
States: empty (welcome + starter template gallery); populated; cap-reached (informative message, archive prompt).
Exits: Goal detail (Plan or Track view); New Goal flow.

S3. New Goal — Starter Templates / Flavour Picker

Purpose: seed a new goal with a known shape.
Entry points: Dashboard "+ New Goal".
Primary content: template tiles (Retirement / House / Education / Vacation / Marriage / Custom), and a goal flavour selector (Accumulate to target / Withdraw from corpus).
Primary actions: pick template + flavour; proceed to goal definition.
States: initial.
Exits: Goal Definition (S4).

S4. Goal Definition

Purpose: capture target, horizon, and (for Withdraw goals) starting corpus.
Entry points: S3.
Primary content: target amount input, horizon input (years), starting portfolio value, optional link to a predecessor goal (for chaining), name field.
Primary actions: save and proceed to Scenario Analysis.
States: valid / invalid (target ≤ 0, horizon ≤ 0, etc.).
Exits: Scenario Analysis Workspace (S5).

S5. Scenario Analysis Workspace

Purpose: define one or more candidate portfolios for the goal and run simulations.
Entry points: from a goal (Plan view).
Primary content: portfolio editor (S6); cashflow editor (S7) chosen by the user as Variation B or C; glide-path editor (S8); a "Run simulation" CTA.
Primary actions: edit portfolio, edit cashflows, edit glide path, run simulation, commit a scenario as Reference for the goal.
States: unsaved changes; simulation running (progress indicator); simulation complete; advanced settings expanded vs collapsed.
Exits: Per-Portfolio Results (S9); Comparison Summary Table (S10) once 2+ portfolios exist; commit creates a Scenario Reference and surfaces in Tracking.

S6. Portfolio Editor

Purpose: define a portfolio's asset rows and weights.
Entry points: Scenario Workspace; Portfolio Library; Backtester.
Primary content: testfolio-style toolbar [+ Add Preset ▼] [+ Add Asset ▼] [+ Add Saved ▼]; gear menu (Equal Weight / Normalize / Clear / Mirror Beginning / Import); active rows only (each row: asset class, weight %, remove button); category roll-up bar (equity / fixed income / alternatives / cash); sticky total badge at bottom (green at 100%, yellow at 99–101%, red otherwise); preset library accessible from Add Preset (60/40, HFEA, Permanent Portfolio, Golden Butterfly, Three Fund, Coffeehouse, Yale Endowment, Couch Potato, etc.); asset picker organised as a flat scrollable list with section headers (Equities / Fixed Income / Alternatives).
Primary actions: add/remove rows, edit weights, normalize, mirror beginning, save to library.
States: empty (preset prompt); valid (100%); invalid (banner offering Normalize); saving; immutable (committed-version warning).
Exits: back to context (Scenario Workspace, Library, Backtester).

S7. Cashflow Editor (Two Variations)

S7-B. Variation B — Rigid Compact

Purpose: capture cashflows with a structured form for the 80% case.
Primary content: Monthly contribution input + inflation toggle; Annual top-up (bonus) input + inflation toggle; Contribution years range; collapsible "One-time events (optional)" block with year + amount entries and "+ Add one-time event" affordance; one-line live summary.
Primary actions: fill, add/remove one-time events.

S7-C. Variation C — Timeline Canvas

Purpose: capture cashflows visually on a horizontal timeline.
Primary content: horizontal axis = goal horizon; rows for "Monthly DCA," "Annual bonus," "One-time events"; click anywhere on the timeline to add an event at that year.
Primary actions: click-to-add events; drag to edit; delete.

S8. Glide-Path Editor

Purpose: parameterise the transition between starting and ending portfolios.
Primary content: plain-English sentence "Hold beginning portfolio for [N] years, then transition over [M] years to ending portfolio"; live stacked-area preview chart showing asset mix over the goal horizon.
Primary actions: edit X, edit Y; defaults derived from goal flavour and horizon (e.g. short-term Accumulate goals propose a glide to cash by horizon).
States: invalid (X + M > horizon → soft-clamp + microcopy).

S9. Per-Portfolio Results

Purpose: show the simulation outcome for one portfolio.
Entry points: Scenario Workspace after running.
Primary content (top to bottom):
- Headline strip: donut visualisation, giant Chance-of-Success %, contextual narrative sentence ("This chance of success looks excellent. Your portfolio met the target X% of the time, based on N trials using historical returns data."), 5-bucket clickable trial breakdown row (Very Comfortably Meet / Comfortably Meet / On Target / Likely Miss / Very Likely Miss) with absolute counts.
- Main chart: Fan chart (Accumulation) or Depletion fan (Withdrawal) with two orthogonal toggles (Smooth / Full × Cross-at-Year / Cross-at-Value); log Y-axis by default with linear toggle; horizontal target line for Accumulation, zero-line for Withdrawal; reserved styling for a future real-path overlay.
- Tabbed secondary views: Terminal Wealth histogram (with vertical bucket-boundary lines), MWRR Over Time fan, Trial Drill-Down table (PL-style: sparkline + historical block sequence + terminal value + categorical result).
Primary actions: flip toggles, click buckets to filter, click cells in drill-down.
States: simulation in progress, complete, no result yet.
Exits: Comparison Summary (S10), or commit this scenario as the goal's Scenario Reference.

S10. Comparison Summary Table

Purpose: compare up to 5 portfolios on one goal at the metric level.
Entry points: Scenario Workspace once 2+ portfolios exist.
Primary content: table with metrics as rows (Chance of Success, P5, P50, P95, Expected return, Std deviation, then 5 trial-bucket count rows) and portfolios as columns; column headers each carry a "Compare" checkbox; cells colour-coded best/worst per row; column-header click sorts.
Primary actions: check exactly two checkboxes → sticky CTA "Deep-dive: A vs B →" appears; click any cell to jump to that metric's deep-dive in the workbench.
States: 0/1/2+ portfolios checked.
Exits: Comparison Workbench (S11).

S11. Comparison Workbench (Deep-Dive)

Purpose: visually compare two portfolios on a single chart type at a time.
Entry points: S10 sticky CTA, or cell click.
Primary content: three selectors (Portfolio A pill row, Portfolio B pill row, Comparison vector pill row — Fan chart / Terminal wealth / MWRR / Trial drill-down / Range of outcomes / Goal Range); chart canvas below; layout segmented control (Overlay / Side-by-side / Stacked); auto-render with debounce on selector change.
Primary actions: swap A or B, change vector, change layout.
States: smart pre-fill on first land; A == B blocked; invalid combinations greyed.
Exits: back to S10.

S12. Tracking — Goal Detail (Track view)

Purpose: show real progress against the committed Scenario Reference.
Entry points: dashboard, or S5 commit.
Primary content: metrics row (current value, % to goal, tracking percentile, updated Chance of Success, drift from plan, closest historical analog); main chart (300-path representative cone + thick black real-path overlay); toggle "Original Plan / From here forward"; vintage transition markers; drift decomposition (contribution / allocation / market); rebalancing nudges.
Primary actions: add/edit events (S13), switch active vintage, toggle plan vs live re-simulation, click match-to-closest-trial card to highlight that trial.
States: no events yet (empty state with "+ Add first SIP / Lumpsum" prompts); event journal populated; vintage just switched (transition marker visible).
Exits: S13 (Event editor); back to dashboard.

S13. Event Journal Editor

Purpose: capture sparse transaction-style events that drive the tracking computation.
Primary content: list of events grouped by fund; "+ Add event" with a 7-type picker (SIP start / SIP modification / SIP stop / Lumpsum purchase / Redemption / Switch / Rebalance); each event card shows fund + type + key fields + edit/delete.
Primary actions: add, edit, delete events.
States: empty; populated; SIP date conflict (if defined day-of-month falls on a non-business day, the system rounds to next business day per AMC convention).

S14. Asset Class → Fund Mapping

Purpose: map the indices in a Scenario Reference to the funds tagged for the goal, with user-chosen weights.
Entry points: Goal Plan view, after committing a Scenario Reference and tagging at least one fund.
Primary content: list of Asset Class slots from the active Scenario Reference; under each slot, the funds tagged in that category at 0% with a weight input; each fund row shows persistence Signal score (read-only) inline; per-slot running total ("60% allocated, 40% remaining") with red validation if not 100%.
Primary actions: allocate weights, save as draft, commit when all slots are 100%.
States: draft (incomplete); committed; invalid (slot ≠ 100%).

S15. Portfolio Library

Purpose: central home for the user's saved portfolios, version-controlled.
Entry points: sidebar or shared header from Goals, Tracking, Backtester.
Primary content: list of up to 10 saved portfolios; each row shows name, latest version, last edited, "used in [N goals/backtests]"; preset library shown separately (does not count against cap); 30-day Archive section; per-portfolio version history accessible by expanding a row.
Primary actions: open, edit (creates new version if referenced), archive, restore from Archive, clone preset.
States: under cap; at cap (informative message + archive prompt); referenced version edit (confirmation prompt).

S16. Fund Selection & Screener (existing)

Purpose: browse the AMFI fund universe with persistence analysis.
Entry points: Funds tab.
Primary content: Persistence Table (Signal + Confidence sortable); Fund Profile Card on row click; Comparison Page; Category Overview. (Detailed UI per existing Fund-Persistence-Framework spec.)
Primary actions: filter, sort, click a fund to drill into Profile, Save to Goal, Compare.
States: per existing spec.
Exits: Profile / Compare / Category / back to Goal via Save-to-Goal.

S17. Backtester

Purpose: historical, deterministic analysis of a portfolio.
Entry points: Backtester tab; "Backtest this" links from Scenario Workspace and Screener.
Primary content: Mode toggle (Single-portfolio / SIP / Multi-portfolio comparison / Rolling-start / Stress-period); Index-level vs Fund-level toggle; portfolio picker (from shared library); start/end dates; contribution schedule (for SIP mode); chart canvas + summary metrics (CAGR, max drawdown, Sharpe, terminal value, vs benchmark).
Primary actions: configure inputs, run backtest, save result snapshot.
States: insufficient data for chosen window; backtest running; complete.

S18. Settings / Advanced

Purpose: expose methodology controls and global preferences.
Primary content: simulation parameters (block min/max years, simulation count); bucket threshold overrides (150/110/90/50% defaults); inflation rate default; risk-free rate default (India 6.5% baseline); display toggle (today's vs nominal rupees); archive / restore section.

Key Flows

F1. New User → First Committed Goal

Trigger: new user lands on empty Goals dashboard.
Steps: Welcome → Starter Template Gallery (S3) → Goal Definition (S4) → Scenario Workspace (S5) → Portfolio Editor with preset preselected (S6) → Cashflow Editor B or C (S7) → Glide Path Editor (S8) → Run simulation → Per-Portfolio Results (S9) → optionally add more portfolios → Comparison Summary (S10) → Comparison Workbench drill-downs (S11) → commit chosen scenario as Scenario Reference v1.
Success outcome: goal exists, scenario committed, dashboard shows goal in Plan-only state.
Failure modes: simulation engine error (retry banner); validation fails (inline errors on offending fields).

F2. Tag Funds and Map to Goal

Trigger: user opens Funds tab.
Steps: Persistence Table → filter / sort → click fund → Fund Profile → Save to Goal → pick goal(s) → return to Goals → open goal → Plan view shows "Tagged funds: N" → click into Asset Class → Fund Mapping (S14) → allocate weights manually per slot → commit when all slots = 100%.
Success outcome: mapping committed; tracking surface unlocks.
Failure modes: slot under/over-allocated → commit blocked with red validation; user can save draft and return later.

F3. Define Events and Begin Tracking

Trigger: mapping committed for a goal.
Steps: Goal Track view → empty state with "+ Add first SIP / Lumpsum" → Event Journal Editor (S13) → add SIP events for each fund → tracking chart populates with real-path overlay against 300-path cone.
Success outcome: real-path line visible; metrics row populates.
Failure modes: missing NAV history for a fund (graceful degradation with note).

F4. Drift Detected, User Refines Plan

Trigger: user opens a goal in Track view; metrics row shows drift below P15.
Steps: review drift decomposition (contribution / allocation / market) → return to Plan view → re-run scenario with new assumptions → commit as Vintage v2 → switch active vintage to v2 → tracking chart redraws with vintage transition marker at today's date.
Success outcome: tracking now measures against v2; v1 remains in version history.

F5. Backtest Before Committing

Trigger: user wants to validate a candidate portfolio before committing it.
Steps: in Scenario Workspace → "Backtest this" → Backtester opens with portfolio preloaded → choose mode (Single / SIP / Rolling-start / Stress) → run → review realised history → return to Scenario.
Success outcome: user has historical context before trusting the bootstrap.

F6. Cap-Reached Recovery

Trigger: user attempts to create an 11th portfolio or 6th goal.
Steps: clear modal/banner → "You've reached the cap. Archive an existing item to make room." → Archive picker → confirm → return to creation flow.
Success outcome: archived item moves to 30-day trash; new item creation proceeds.

Interaction Details

Auto-render: workbench chart re-renders 200–300 ms after the last selector change (debounced). No "Display" button.
Bucket click (single): highlights paths from that bucket on the main chart at year/quarter granularity AND auto-switches the secondary tab to "Trial Drill-Down" pre-filtered to that bucket.
Click-to-clear: "Clear filter" affordance restores all trials on the chart.
Comparison checkbox enforcement: exactly two boxes can be checked at once. A third selection is rejected with inline microcopy ("Uncheck one to add another").
Sticky CTA: "Deep-dive: A vs B →" only appears when exactly two boxes are checked. Clicking opens the workbench in the same tab (route change); browser back returns to summary table.
Workbench pair swap: click any non-active pill in the pair-picker; auto-replaces the older selection.
Chart toggles: Smooth / Full and Cross-at-Year / Cross-at-Value act independently; layout segmented control (Overlay / Side-by-side / Stacked) is orthogonal to both.
Glide-path live preview: stacked-area chart updates on every keystroke in X / Y fields.
Cashflow editor B: monthly + annual + one-time events; one-time event rows auto-add when "+" pressed.
Cashflow editor C: click anywhere on the horizontal timeline to add an event there; drag to edit; delete via per-event menu.
Real-path overlay: thick black line on the tracking chart, rendering on the same axes as the cone.
Vintage transition: vertical line marker on tracking chart with hover note.
Match-to-closest-trial card: clicking the card highlights that trial path on the chart and reveals its historical block sequence in a tooltip; microcopy reminds "this is one possible analog, not a forecast."
Form validation: sticky 100% total badge (green/yellow/red) for portfolio weights; red validation per slot for Asset Class → Fund Mapping; commit buttons disabled until valid.
Undo / cancel patterns: archive (not delete) for portfolios with 30-day restore; goal/scenario delete is a destructive action with confirmation; event delete is one-click but instantly recoverable from a "Last action: Undo" toast.
Confirmation: editing a portfolio version that's referenced by a committed Scenario triggers a confirmation prompt; otherwise edits autosave.
Responsive: workbench side-by-side automatically degrades to stacked under ~900 px viewport width; overlay stays overlay.
Cell colour coding (summary table): diverging scale, best=green, worst=red per row.
SIP day-of-month rounding: when chosen day falls on a non-business day, the engine uses next business day (matches AMC convention); documented in microcopy near the SIP-start input.

Content & Copy

Bucket labels (Accumulation): Very Comfortably Meet / Comfortably Meet / On Target / Likely Miss / Very Likely Miss.
Bucket labels (Withdrawal): parallel scheme on terminal legacy and year-of-depletion (Comfortable Surplus / Comfortable / Tight / Failed Late / Failed Early — exact strings TBD).
Headline narrative: "This chance of success looks [excellent / strong / borderline / weak]. Your portfolio met the target X% of the time, based on N trials using historical returns data."
Tracking percentile microcopy: "Currently tracking near P54 of the original plan."
Drift microcopy: "You're ₹5,200 behind your planned contributions."
Closest historical analog microcopy: "Closest historical match: 1973–1977 sequence. This is one possible analog, not a forecast."
Mapping friction microcopy: "We don't auto-allocate across funds because the choice depends on your conviction. Allocate based on what you'd actually buy."
Vintage transition microcopy: "Plan changed: now using v2."
Cap-reached microcopy: "You've reached your X cap. Archive an existing item to make room."
Scenario commitment microcopy: "Committing this scenario will freeze it as the reference for this goal. Re-running creates a new vintage."
Disclaimer microcopy on tracking chart: "Your real path could land outside this cone. The cone shows historical possibilities, not guarantees."
Tone of voice: factual, plain English, statistically honest. No marketing puffery. Calls out limits explicitly (data envelope, "not a forecast"). India-flavoured vocabulary (SIP, lakh/crore, ₹).

Visual Design Direction

Chart palette (fan chart): PortfolioCharts-inspired — red→grey→blue diverging across percentile bands (Min / Conservative / Average / Stretch / Max).
Chart palette (depletion fan): same diverging scale; ruined trials coloured red prominently; zero-line emphasised.
Real-path overlay: thick black line (high contrast on light theme; high contrast on dark theme).
Density preference: progressive disclosure — low density on first land for new users (one portfolio, one cashflow form, one chart), expandable into the full surface (5-portfolio comparison, secondary tabs, drill-downs).
Headline number treatment: giant percentage (PL-inspired) for Chance of Success; donut visualisation as decorative anchor.
Iconography: category icons for goal templates (Retirement / House / Education / Vacation / Marriage); minimal, semantic.
Y-axis log default: chosen so percentile bands look symmetric over long horizons.
Cell colour-coding (summary table): diverging scale per row.
Component-first composition: every chart, editor, and table is buildable as an independent unit; layouts (single scroll vs tabs vs accordion) deliberately deferred and to be tested empirically.

Responsive & Platform Behavior

Desktop primary. Comparison Workbench side-by-side and overlay both first-class.
Under ~900 px viewport: Comparison Workbench side-by-side degrades to stacked. Overlay stays overlay. 5-column summary table is horizontally scrollable; metrics-as-rows / portfolios-as-columns structure is preserved (no transpose on mobile).
Mobile: primary viewing of dashboard and Tracking; editors usable but optimised for desktop.
Browser back: route changes (e.g. Summary Table → Workbench) work with the back button.
No native mobile app in V1.

Accessibility

Touch targets: 44 px minimum on mobile.
Keyboard: form fields, picker pills, segmented controls all keyboard-reachable.
Colour: colour-coded cells, percentile bands, and bucket states must not rely on colour alone — labels and patterns supplement.
Screen readers: chart canvases must expose a textual summary (e.g. "Fan chart: 4000 trials. P5: ₹X. P50: ₹Y. P95: ₹Z. Chance of success 78%."). Trial drill-down table is fully readable.
Motion: auto-render debounce shouldn't cause involuntary motion sickness; respect prefers-reduced-motion (skip transition animations).
Focus states: explicit focus rings on every interactive element.

Out of Scope

Brokerage integrations (Zerodha, IndMoney, account aggregator framework). Manual entry only in V1; integrations are V2/V3.
Plaid / US-style aggregator integration.
US market or any non-Indian market focus.
Combined "accumulate-then-withdraw" goal flavour. Retirement is modelled as two linked goals (Accumulation + Withdrawal).
Auto-allocation across funds in the Asset Class → Fund Mapping. User must allocate manually — friction by design.
Per-fund value entry for tracking. Portfolio-level value is computed from the event journal × NAV history; manual periodic value entry is not a V1 path.
Tracking-error and expense-ratio adjustment of the reference cone. The cone is the index-ideal in V1; the gap to real-fund reality is acknowledged in microcopy, not subtracted in the math.
Multi-fund household balance sheet (a single fund holding earmarked across multiple goals). V1 silos: each goal's fund holdings are its own.
Unbounded portfolio / scenario / goal libraries. Caps are 10 / 5 / 5 in V1.
Live screener built inside the goal planner. The Fund Selection & Screeners entity is a separate, existing surface.
Native mobile apps.
Tax-aware projections (LTCG, STT, exit load). Out of V1.
Cross-goal transfers / surplus reallocation across goals.
Chat-style or AI-driven goal advisor. The product respects user agency; it does not recommend.

Open Questions

Whether the 5-scenario cap is global across all goals or per-goal. (Tabled as TBD in conversation.)
Whether an exploratory scenario run that is not committed counts against the scenario cap. (Almost certainly no, but unstated.)
What happens to a goal's committed scenario vintages when the goal itself is archived/deleted.
Exact relationship between "saved scenarios" and the multi-vintage Scenario Reference model — are they the same thing or different?
Exact bucket labels and thresholds for Withdrawal-flavour goals (Accumulation thresholds locked at 150/110/90/50%; Withdrawal scheme described directionally but not finalised).
Definition of "consistent fund performance" used for screener ranking — tracking error / rolling-3yr variance / information ratio / standard deviation of monthly returns / max drawdown — was not pinned down.
Whether rolling-start backtest should run with or without rebalancing in V1, and what the UI affords for that toggle. (User noted "no rebalancing" as the cheap initial path; details deferred.)
Whether to allow drag-handles on the glide-path preview chart (V2 candidate only — discussed but not selected for V1).
Whether to surface a per-portfolio "show all 4000 trials" full-spaghetti toggle in addition to Smooth and Full modes. (Considered as Variation B in chart options; deprioritised.)
Whether the donut visualisation around the headline Chance-of-Success number is kept or dropped. ("Decorative; not load-bearing" — open.)
Final composition of the per-portfolio results page (single scroll vs tabs vs accordion) — deliberately deferred to be tested empirically across the 5–6 flow variations.
Settings & advanced parameters surface design — discussed in principle; specific layout deferred.
Onboarding microcontent and educational tooltips ("What does P5 mean?", "Why block bootstrap?") — agreed needed; specific copy and placement deferred.
Mobile-specific design details — agreed responsive; mobile-specific affordances not deeply specified.
Number of versions per portfolio (5 or 10) before FIFO eviction kicks in.
Withdrawal-flavour bucket clickable filter behaviour and exact 5-bucket scheme.

Further Notes

Reference patterns drawn from: Portfolio Visualizer (form-driven dense editor — adopted for asset hierarchy in picker), PortfolioCharts (fan chart with named percentile bands, log axis, terminal value labels, Goal Range view — adopted as the primary chart language), ProjectionLab (giant Chance-of-Success %, contextual narrative, 5-bucket trial label scheme, per-trial drill-down table — adopted for headline strip and drill-down), testfolio (incremental "1 Portfolio | 2 Portfolios" add pattern, ADD PRESET / ADD ASSET / ADD SAVED toolbar, flat-list asset picker by section — adopted for portfolio editor mechanics).
The Fund Selection & Screeners entity already exists as a parallel project (Fundlevel-FE) with its own implementation plan and route taxonomy (/screener, /fund/:scheme_code, /compare, /category/:style_label). This PRD treats those surfaces as existing; the only new affordance to add inside them is the Save to Goal action.
The Fund Persistence Framework (Signal + Confidence scoring on rolling 3Y/5Y windows, regime capture with India VIX thresholds) is the analytical substrate the screener's persistence Signal score draws from, and is referenced read-only inline in the Asset Class → Fund Mapping screen.
Component-first build philosophy: every chart, editor, and table will be built as an independent, composable unit. The 5–6 flow variations explore different compositions of those components (page architecture, tabs vs accordion vs scroll, wizard vs single-page goal creation, vertical vs horizontal portfolio comparison) rather than different components.
Rejected design directions (worth recording so they aren't reintroduced later):
- Combined accumulate-then-withdraw goal flavour. Rejected because the joint correlation in 50-year simulations on 20 years of historical data is mostly bootstrap artifact; cleaner to model as two linked goals.
- Auto-allocation across tagged funds in the mapping. Rejected because real progress tracking requires user ownership of the allocation decision.
- Pre-populating all 5 portfolios in the comparison at goal creation. Rejected in favour of incremental "1 portfolio → Add → 2 portfolios → ..." pattern.
- Per-fund manual value entry for tracking. Rejected because AMFI NAVs are public; the system can compute value from a sparse event journal × NAV history.
- Single-flavour-only goal model. Rejected because forcing accumulation-flavoured goals into a "% success on $0 floor" metric makes short-term goals weirdly meaningless.
- Pure single-overlay-of-5 fan chart for comparison. Rejected because beyond two portfolios, the visual becomes spaghetti and pairwise visual comparison matches how brains actually decide.
- Display button (manual commit) on the workbench. Rejected in favour of auto-render with debounce.