# PersonalInvestor — скрипт разговорного интейка (ТЗ для прототипа)

> Дословный сценарий диалога со всеми ветками. **Текст пользователю — на английском** (целевой рынок US/CA, готово к прототипу). **Логика, ветвление и скоринг — на русском** (для команды).
> Цель интейка: за **≤3 минуты** и **5–8 вопросов** довести до 2–3 объяснённых сценариев портфеля, сняв трение (70% бросают длинные анкеты).

---

## 0. Принципы и тон

| Принцип | Как реализуем |
|---|---|
| **Разговор, а не форма** | один вопрос на экран, крупные кнопки, естественный язык |
| **Объясняем «зачем»** | под каждым вопросом — микрокопирайт «why we ask» (снимает недоверие) |
| **Адаптивность** | следующий вопрос зависит от предыдущего ответа (пропуски/добавления) |
| **Честность важнее AUM** | если инвестировать не время (долг/нет подушки) — прямо говорим |
| **AI объясняет — правила решают** | LLM ведёт диалог и объясняет; **аллокацию считает детерминированный rules-engine** (комплаенс) |
| **Без обещаний** | всегда диапазоны и риск, никогда «вы заработаете X%» |

**Голос бренда (EN):** warm, plain-English, jargon-free, never condescending, never hype. Пример: не «diversified multi-asset allocation», а «a mix that doesn't put all your eggs in one basket».

---

## 1. Модель данных (что захватываем)

| Переменная | Тип | Из вопроса |
|---|---|---|
| `country` | US / CA | стартовый детект + Q6 |
| `goal_primary` | enum | Q1 |
| `horizon_years` | <2 / 2-5 / 5-10 / 10+ | Q2 |
| `initial_amount` | число | Q3 |
| `monthly_contribution` | число | Q3b |
| `risk_tolerance` | 1–4 | Q4 |
| `has_emergency_fund` | yes/partial/no | Q5a |
| `income_stability` | 1–3 | Q5b |
| `risk_capacity` | 1–4 (расчёт) | Q5 |
| `account_type` | taxable / retirement / TFSA / RRSP / unsure | Q6 |
| `high_interest_debt` | yes/no | Q7 |
| `mode` | for_me / with_me / human | Q8 |
| `effective_risk` | 1–5 (расчёт) | движок |
| `equity_pct` | % (расчёт) | движок |

---

## 2. Карта диалога (ветвление)

```mermaid
flowchart TD
    W["Welcome"] --> Q1["Q1 Цель"]
    Q1 --> Q2["Q2 Горизонт"]
    Q2 -->|"< 2 лет"| SHORT["`Вставка: короткий горизонт
инвестиции могут не подойти`"]
    Q2 -->|"2+ лет"| Q3["Q3 Сумма + взнос"]
    SHORT --> Q3
    Q3 --> Q4["`Q4 Риск-толерантность
реакция на -20%`"]
    Q4 --> Q5["`Q5 Риск-способность
подушка + доход`"]
    Q5 --> Q6["Q6 Тип счёта / налоги"]
    Q6 --> Q7["Q7 Дорогой долг?"]
    Q7 -->|"Да"| DEBT["`Вставка: сначала долг
честная математика + гибрид`"]
    Q7 -->|"Нет"| Q8["Q8 Режим"]
    DEBT --> Q8
    Q8 -->|"Хочу человека"| HUMAN["Бронь сессии CFP"]
    Q8 -->|"for_me / with_me"| ENGINE["`Rules-engine:
risk + horizon → equity %`"]
    HUMAN --> ENGINE
    ENGINE --> OUT["`2-3 сценария портфеля
+ объяснение + прогноз`"]
```

---

## 3. Дословный скрипт (EN-копия + логика)

### Welcome
🗣️ **EN:** "Hi 👋 I'll help you turn your savings into a plan — in plain English, no jargon. A few quick questions (about 2 minutes), then I'll show you 2–3 clear options. You don't need to open an account or commit to anything to see them. Ready?"
▶️ CTA: **"Let's go"**
📥 Старт сессии, `country` детект по IP (подтвердим в Q6).

---

### Q1 — Цель
🗣️ **EN:** "First — what do you want this money to *do* for you?"
Варианты (кнопки):
- 🏠 "Buy a home" → `goal=home`
- 🌴 "Retire comfortably" → `goal=retirement`
- 🛟 "Build a safety net" → `goal=safety`
- 👶 "My kids' future" → `goal=kids`
- 📈 "Just grow it over time" → `goal=growth`
- ✍️ "Something else" → free-text

💬 **why we ask (EN):** "Your goal shapes everything — how long we invest and how much risk makes sense."
🔀 Ветвление:
- `safety` → в Q2 подсветить ликвидность; дефолт горизонта короче.
- `retirement` → дефолт горизонта 10+; включить пенсионные оболочки в Q6.
- `home` → уточнить срок жёстко (Q2 критичен: дом через 2 года ≠ через 10).

---

### Q2 — Горизонт
🗣️ **EN:** "Roughly when might you need this money?"
- "Within 2 years" → `horizon=<2`
- "2–5 years" → `horizon=2-5`
- "5–10 years" → `horizon=5-10`
- "10+ years" → `horizon=10+`
- "I'm not sure" → `horizon=unsure` (трактуем как 5–10 по умолчанию, уточняем позже)

💬 **why we ask (EN):** "Time is your biggest advantage. The longer you can wait, the more the ups and downs smooth out."

🔀 **Вставка при `horizon=<2` (SHORT):**
🗣️ **EN:** "Heads up — for money you'll need within 2 years, investing in markets can be risky: there might not be time to recover from a dip. For this money, I'll lean toward safer, stable options (like high-yield savings or short-term government bonds). Want to keep going?"
- "Yes, show me safe options" → продолжить, `equity_cap=15%`
- "Actually, it's longer-term" → вернуть в Q2
📌 Это фича «честность важнее AUM» + suitability-комплаенс.

---

### Q3 — Сумма и взнос
🗣️ **EN (Q3a):** "About how much would you start with? (A ballpark is fine — you can change it anytime.)"
📥 `initial_amount` (слайдер/ввод; диапазоны $500 … $100k+)

🗣️ **EN (Q3b):** "And do you plan to add to it regularly?"
- "Yes, monthly" → ввод суммы → `monthly_contribution`
- "Once in a while" → `monthly_contribution≈0`, флаг «lump»
- "Not for now" → `monthly_contribution=0`

💬 **why we ask (EN):** "Even small regular top-ups can matter more than the starting amount — I'll show you why in the projection."
🔀 Ветвление:
- `initial_amount ≥ $20k` и `account=taxable` → в OUT включить **direct indexing / tax-loss harvesting** как опцию.
- `monthly_contribution > 0` → в прогнозе показать эффект dollar-cost averaging.

---

### Q4 — Риск-толерантность (поведенческая)
🗣️ **EN:** "Imagine your investments drop **20% in a month** — it happens. What would you most likely do?"
- "Sell everything to stop the losses" → `risk_tolerance=1`
- "I honestly don't know" → `risk_tolerance=2`
- "Wait it out and do nothing" → `risk_tolerance=3`
- "Buy more while it's cheap" → `risk_tolerance=4`

💬 **why we ask (EN):** "There are no wrong answers. This tells me how much bumpiness you'll actually be comfortable with — so you don't panic-sell at the worst time."
🔀 Ветвление:
- `risk_tolerance=1` → пометить `panic_prone=true`; в OUT усилить блок «antipanic», предложить более консервативный дефолт даже если горизонт длинный.

---

### Q5 — Риск-способность (объективная)
🗣️ **EN (Q5a):** "Do you have 3–6 months of expenses saved separately, as an emergency fund?"
- "Yes" → `emergency=3`
- "Partially" → `emergency=2`
- "No / not yet" → `emergency=1`

🗣️ **EN (Q5b):** "How steady is your income?"
- "Very steady (salary)" → `income=3`
- "Somewhat variable" → `income=2`
- "Unpredictable (freelance/commission)" → `income=1`

💬 **why we ask (EN):** "Being *able* to take risk is different from being *willing* to. If your income is bumpy or you've no cushion, I'll dial risk down to protect you — even if you're bold."

🔀 **Расчёт `risk_capacity`:**
```
cap_sum = emergency + income        # диапазон 2..6
risk_capacity = 1 если cap_sum<=2 ; 2 если 3 ; 3 если 4-5 ; 4 если 6
```
🔀 **Вставка при `emergency=1`:**
🗣️ **EN:** "One thing first — before investing, it's usually smart to set aside a small emergency fund (even $1,000 to start). I can split your plan: build a cash buffer first, then invest the rest. Want that?"
- "Yes, split it" → создать под-цель «emergency», распределить взносы
- "No, invest it all" → продолжить, но `equity_cap` понижен на один шаг

---

### Q6 — Тип счёта / налоги
🗣️ **EN:** "Where would this money live? (This changes your taxes — I'll optimize it for you.)"
US-варианты:
- "A regular investment account" → `account=taxable`
- "Retirement (401k / IRA / Roth)" → `account=retirement`
- "Not sure" → `account=unsure`

CA-варианты (если `country=CA`):
- "TFSA (tax-free)" → `account=tfsa`
- "RRSP (retirement)" → `account=rrsp`
- "A regular (non-registered) account" → `account=taxable`
- "Not sure" → `account=unsure`

💬 **why we ask (EN):** "The right account can save you real money in taxes — often more than any difference in fees."
🔀 Ветвление:
- `taxable` + сумма ≥ порог → **TLH + direct indexing** on.
- `account=unsure` → короткий разъяснитель (US: Roth vs traditional; CA: TFSA vs RRSP) с рекомендацией по `goal`/доходу.
- Включить логику **account location** (облигации → в tax-advantaged, акции → в taxable/TFSA).

---

### Q7 — Проверка на дорогой долг
🗣️ **EN:** "Quick check: do you have any debt costing more than about **7% a year** (like credit-card balances)?"
- "Yes" → `debt=yes`
- "No" → `debt=no`

💬 **why we ask (EN):** "I only recommend what's genuinely best for you — and sometimes that's not investing yet."

🔀 **Вставка при `debt=yes` (DEBT):**
🗣️ **EN:** "Here's the honest math: paying off debt at, say, 20% is like earning a **guaranteed 20%** — something no investment can promise. Usually it's smart to clear that first. I can still start a small investing habit alongside it. What feels right?"
- "Focus on debt first" → перевести в режим план-долга + микро-инвест ($X/mo символически)
- "Split: some debt, some investing" → гибридный план
- "Invest anyway" → продолжить, залогировать информированный выбор
📌 Мощнейший триггер доверия (и вирусности: «единственные, кто отговаривал меня вкладывать»).

---

### Q8 — Режим
🗣️ **EN:** "Last one — how hands-on do you want to be?"
- "Do it for me — automate everything" → `mode=for_me`
- "Do it *with* me — I want to understand and approve" → `mode=with_me`
- "I'd like to talk to a real person first" → `mode=human`

💬 **why we ask (EN):** "Either way you get the same smart plan — this just sets how involved you are."
🔀 Ветвление:
- `mode=human` → предложить **бронь бесплатной 15-мин сессии с CFP/фидуциаром** (но сначала всё равно показать сценарии, чтобы разговор был предметным).
- `mode=with_me` → в OUT включить обучающие пояснения и режим «approve each step».
- `mode=for_me` → в OUT акцент на «set and forget», автоинвест.

---

## 4. Rules-engine: от ответов к аллокации

### Шаг 1 — эффективный риск
```
effective_risk = min(risk_tolerance, risk_capacity)      # берём меньшее — безопаснее и честнее
если panic_prone: effective_risk = max(1, effective_risk - 1)
```

### Шаг 2 — целевая доля акций (equity %)
Базовая матрица (риск × горизонт), затем берём минимум с horizon-cap:

| effective_risk → | Гориз. <2 | 2–5 | 5–10 | 10+ |
|---|---|---|---|---|
| 1 (очень низкий) | 0–10% | 20% | 30% | 35% |
| 2 | 10% | 35% | 45% | 50% |
| 3 (средний) | 15% | 45% | 60% | 65% |
| 4 | 15% | 50% | 70% | 80% |
| 5 (высокий*) | 15% | 55% | 80% | 90% |

\* `effective_risk=5` достижим только при tolerance=4 И capacity=4 И длинном горизонте.
Затем применяем: `equity_pct = min(matrix, equity_cap)` (cap из вставок SHORT/emergency).

### Шаг 3 — сборка портфеля (пример для equity 60%)
- Акции 60%: US total market 35% + ex-US 20% + small/value tilt 5%
- Облигации 30%: aggregate bond 20% + TIPS 10%
- Подушка/кэш 10%: money-market / T-bills
- (опц.) альтернативы до 10% из акций/облигаций для афлюент-профиля
- (опц.) крипто-слив ≤5% только если пользователь явно просил в «something else»

---

## 5. Вывод: 2–3 сценария (шаблон EN)

Показываем **ровно 2–3** карточки (не витрину). Средняя — «recommended», подсвечена.

**Card template (EN):**
> **{Name}** · *{one-line vibe}*
> **The mix:** {plain-language allocation}
> **Why it fits you:** {ссылка на ответы — goal, horizon, risk}
> **In a good decade / a rough one:** growth could look like **{range}** — markets go up *and* down, and this shows both.
> **If markets drop:** you might see about **−{drawdown}%** temporarily. Here's how we'd coach you through it.
> ▶️ *See the projection* · *Start this* · *Talk to a human*

Пример трёх карточек для `goal=retirement, horizon=10+, effective_risk=3`:
1. **Steady** — equity 45%. "Smoother ride, slower growth."
2. **Balanced** ⭐ *recommended* — equity 65%. "Best fit for your timeline and comfort."
3. **Growth** — equity 80%. "More growth, bigger swings — only if you can stomach them."

📥 Каждая карточка + **Monte-Carlo прогноз** (вероятность достижения цели, диапазоны 10-й/50-й/90-й перцентиль).

---

## 6. Комплаенс-guardrails для AI (обязательно)

| Правило | Реализация |
|---|---|
| **Никаких обещаний доходности** | запрещённые паттерны («will earn», «guaranteed returns»); только диапазоны + «markets can lose value» |
| **Suitability** | нельзя equity-heavy при `horizon<2` или `emergency=1`; движок жёстко ограничивает |
| **AI не выдумывает цифры** | все числа — из rules-engine/данных, не из LLM |
| **Дисклеймеры** | «This is educational, not a guarantee»; при выдаче реком. — фидуциарный дисклеймер |
| **Аудит-трейл** | логировать каждый вопрос/ответ/рекомендацию (Books & Records, Reg S-P) |
| **Эскалация** | при признаках уязвимости/непонимания — маршрут к человеку |
| **Marketing Rule** | симулятор и прогнозы — по правилам гипотетической доходности |

**System-prompt guardrail (EN, черновик для LLM):**
> "You are a friendly financial guide. You explain and clarify; you NEVER invent numbers, NEVER promise or predict specific returns, and NEVER recommend a specific allocation — the rules engine provides allocations and figures. Always mention that investments can lose value. If the user seems distressed, confused, or in a situation beyond scope, offer to connect them with a human advisor."

---

## 7. Заметки по прототипу

- **MVP-стек:** фронт (React/Next) → интейк-стейт-машина → LLM (диалог/объяснения) + отдельный **детерминированный allocation-service** → мок-портфели → прогноз (Monte-Carlo, ~1000 путей).
- **Тестируем 2 метрики:** (1) **completion rate** интейка (цель >70%), (2) «trust score» — понял ли пользователь, *почему* ему предложили именно это (пост-опрос 1 вопрос).
- **A/B:** разговорный интейк vs классическая анкета — замерить разницу в completion и в конверсии «показали → подключил счёт».
- **Локализация:** копия готова на EN; при выходе в Канаду — те же строки + CA-варианты Q6 (TFSA/RRSP) уже заложены.

---

*Скрипт — стартовая версия для прототипа и пользовательских тестов. Финальные формулировки проходят комплаенс-ревью (Marketing Rule / фидуциарные дисклеймеры) до продакшена.*