Skip to content

Feat/onboarding improvements #58

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
leo-Zhizhu merged 2 commits into from
Feb 15, 2026
Merged

Feat/onboarding improvements #58

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a4d9430
feat(dashboard): allow ignoring onboarding popup for 24 hours via loc…
leo-Zhizhu Feb 14, 2026
1263a18
docs(onboarding): update onboarding procedure with required/optional …
leo-Zhizhu Feb 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
236 changes: 135 additions & 101 deletions skills/user-profile/onboarding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,37 @@
# User Onboarding Procedure

This document describes the step-by-step procedure for onboarding new users.
This document describes the step-by-step procedure for onboarding new users via chat.

## Overview

Onboarding helps users set up their investment profile so the agent can provide personalized advice.

### Required Information
### Required Information (MUST HAVE)

1. **At least one stock** (in watchlist or portfolio)
2. **Risk preference** (tolerance level)

### Optional Information
- Portfolio holdings with quantity/cost
- Investment preference (style, sectors)
- Agent preference (research style, detail level)
The user **must** provide both before onboarding can be completed.

### Optional Preferences

Company Interest, Holding Period, Analysis Focus, and Output Style are **optional**. The user may skip any or all of these.

### Preference Entities and API Reference

Settings are stored via `update_user_data`. API details: `docs/api/50-users/update-preferences.yml` and `docs/api/50-users/get-preferences.yml`.

| Setting | Entity | Field | Valid Values |
|---------|--------|-------|--------------|
| Risk Tolerance | `risk_preference` | `risk_tolerance` | "low", "medium", "high", "long_term_focus" |
| Company Interest | `investment_preference` | `company_interest` | "growth", "stable", "value", "esg" |
| Holding Period | `investment_preference` | `holding_period` | "short_term", "mid_term", "long_term", "flexible" |
| Analysis Focus | `investment_preference` | `analysis_focus` | "growth", "valuation", "moat", "risk" |
| Output Style | `agent_preference` | `output_style` | "summary", "data", "deep_dive", "quick" |

### Using AskUserQuestion

For questions where the user picks from predefined options (risk tolerance, investment style,
research preference), use the `AskUserQuestion` tool to present a structured UI. For open-ended
questions (stock names, share counts, cost basis), use normal conversational messages.
For questions where the user picks from predefined options, use the `AskUserQuestion` tool to present a structured UI. For open-ended input, use normal conversational messages.

---

Expand All @@ -31,24 +43,24 @@ Greet the user and explain what you'll help them set up:

```
"I'd be happy to help you set up your investment profile! This helps me
give you personalized advice. Let's start with what matters most to you.
give you personalized advice. I'll need two things: at least one stock
you're watching or own, and your risk tolerance. I can also ask about
company interest, holding period, analysis focus, and output style —
those are optional.

Are there any stocks you're currently watching or own?"
```

**Key points:**
- Keep it welcoming and brief
- Ask what they'd like to set up first
- Adapt based on their response
- Make clear what is required (stocks, risk) vs optional
- Start with stocks

---

### Phase 2: Stocks (Natural Discovery)
### Phase 2: Stocks (Required)

Ask about stocks in a natural way. Users might mention:
- Stocks they're watching
- Stocks they own
- Both
Ask about stocks in a natural way. Users might mention stocks they're watching, stocks they own, or both.

**If they own stocks:**
```
Expand All @@ -69,95 +81,124 @@ User: "I'm interested in NVDA"

---

### Phase 3: Risk Assessment
### Phase 3: Risk Tolerance (Required)

This is **required** before completing onboarding.
**Must be completed** before onboarding can be finished.

```
Call AskUserQuestion(
question="How comfortable are you with investment risk?",
options=["Conservative", "Moderate", "Aggressive"]
options=["Low", "Medium", "High", "Long-term focus"]
)

Mapping:
Conservative → risk_tolerance: "low"
Moderate → risk_tolerance: "medium"
Aggressive → risk_tolerance: "high"
Low → risk_tolerance: "low"
Medium → risk_tolerance: "medium"
High → risk_tolerance: "high"
Long-term focus → risk_tolerance: "long_term_focus"

Then call update_user_data(entity="risk_preference", data={"risk_tolerance": "<mapped_value>"})
```

**Optional follow-up:**
- "What's your investment time horizon? Short-term (< 1 year), medium (1-5 years), or long-term (5+ years)?"

---

### Phase 4: Optional Preferences
### Phase 4: Company Interest (Optional)

Only ask if the user seems engaged and interested. Don't force these.
Ask about company interest only if the user is interested.

**Investment Style:**
```
Call AskUserQuestion(
question="Do you have a preferred investment style?",
options=["Growth", "Value", "Income", "Balanced"]
question="What type of companies interest you most?",
options=["Growth", "Stable", "Value", "ESG"]
)

Then call update_user_data(entity="investment_preference", data={"company_interest": "<selected_value>"})
Mapping:
Growth → company_interest: "growth"
Stable → company_interest: "stable"
Value → company_interest: "value"
ESG → company_interest: "esg"

Then call update_user_data(entity="investment_preference", data={"company_interest": "<mapped_value>"})
```

**Agent Style:**
---

### Phase 5: Holding Period (Optional)

Ask about holding period only if the user is interested.

```
Call AskUserQuestion(
question="When I research stocks for you, how detailed should I be?",
options=["Quick summaries", "Balanced analysis", "Thorough deep-dives"]
question="What's your typical investment holding period?",
options=["Short-term", "Mid-term", "Long-term", "Flexible"]
)

Mapping:
Quick summaries → output_style: "quick"
Balanced analysis → output_style: "summary"
Thorough deep-dives → output_style: "deep_dive"
Short-term → holding_period: "short_term"
Mid-term → holding_period: "mid_term"
Long-term → holding_period: "long_term"
Flexible → holding_period: "flexible"

Then call update_user_data(entity="agent_preference", data={"output_style": "<mapped_value>"})
Then call update_user_data(entity="investment_preference", data={"holding_period": "<mapped_value>"})
```

**Visualizations:**
---

### Phase 6: Analysis Focus (Optional)

Ask about analysis focus only if the user is interested.

```
Call AskUserQuestion(
question="How often should I include charts and visualizations in my analysis?",
options=["Always", "When useful", "Prefer not to", "Never"]
question="When I analyze stocks, what should I emphasize?",
options=["Growth", "Valuation", "Moat", "Risk"]
)

Mapping:
Always → enable_charts: "always"
When useful → enable_charts: "auto"
Prefer not to → enable_charts: "prefer_not"
Never → enable_charts: "never"
Growth → analysis_focus: "growth"
Valuation → analysis_focus: "valuation"
Moat → analysis_focus: "moat"
Risk → analysis_focus: "risk"

Then call update_user_data(entity="investment_preference", data={"analysis_focus": "<mapped_value>"})
```

Then call update_user_data(entity="agent_preference", data={"enable_charts": "<mapped_value>"})
**Note:** If updating multiple investment_preference fields (company_interest, holding_period, analysis_focus), you can combine them in one call:
```
update_user_data(
entity="investment_preference",
data={
"company_interest": "<value>",
"holding_period": "<value>",
"analysis_focus": "<value>"
}
)
```

**Proactive Questions:**
---

### Phase 7: Output Style (Optional)

Ask about output style only if the user is interested. API reference: `docs/api/50-users/update-preferences.yml` (`agent_preference.output_style`).

```
Call AskUserQuestion(
question="Should I ask clarifying questions before starting work?",
options=["Always", "When unclear", "Prefer not to", "Never"]
question="When I research stocks for you, how detailed should I be?",
options=["Quick summaries", "Summary", "Data-focused", "Thorough deep-dives"]
)

Mapping:
Always → proactive_questions: "always"
When unclear → proactive_questions: "auto"
Prefer not to → proactive_questions: "prefer_not"
Never → proactive_questions: "never"
Quick summaries → output_style: "quick"
Summary → output_style: "summary"
Data-focused → output_style: "data"
Thorough deep-dives → output_style: "deep_dive"

Then call update_user_data(entity="agent_preference", data={"proactive_questions": "<mapped_value>"})
Then call update_user_data(entity="agent_preference", data={"output_style": "<mapped_value>"})
```

---

### Phase 5: Completion

Summarize what was set up and mark onboarding complete.
### Phase 8: Completion

**Before completing, verify:**
1. At least one stock was added (watchlist or portfolio)
Expand All @@ -170,13 +211,12 @@ Call update_user_data(entity="profile", data={"onboarding_completed": true})
**Summary template:**
```
"Your profile is set up:

- Portfolio: AAPL (50 shares @ $175)
- Watchlist: NVDA
- Risk preference: Moderate
- Research style: Quick summaries
- Charts: When useful
- Proactive questions: Always
- Portfolio/Watchlist: <stocks added>
- Risk tolerance: <value>
- Company interest: <value if set>
- Holding period: <value if set>
- Analysis focus: <value if set>
- Output style: <value if set>

Is there anything else you'd like to add or adjust?"
```
Expand All @@ -200,20 +240,24 @@ What's a stock you're currently watching or own?"
**No risk preference:**
```
"One more thing - I need to know your risk tolerance to give you good advice.
Would you say you're conservative, moderate, or aggressive with investments?"
Would you say you're comfortable with low, medium, high, or long-term focus?"
```

### Optional Settings:
- Company Interest, Holding Period, Analysis Focus, Output Style are optional. If the user skips these, respect that and proceed.

---

## Example Full Session

```
User: Help me set up my profile

Agent: I'd be happy to help you set up your investment profile! This helps me
give you personalized advice.

Are there any stocks you're currently watching or own?
Agent: I'd be happy to help you set up your investment profile! I'll need
at least one stock you're watching or own, and your risk tolerance.
I can also ask about company interest, holding period, analysis
focus, and output style — those are optional. Are there any stocks
you're currently watching or own?

User: I own some AAPL and want to watch NVDA

Expand All @@ -224,43 +268,33 @@ User: 50 shares, bought around $175

Agent: [calls update_user_data(entity="portfolio_holding", data={"symbol": "AAPL", "quantity": 50, "average_cost": 175.0})]
[calls update_user_data(entity="watchlist_item", data={"symbol": "NVDA", "notes": "Watching"})]
Done! I've added AAPL to your portfolio and NVDA to your watchlist.

Done! I've added:
- AAPL to your portfolio (50 shares @ $175)
- NVDA to your watchlist

[calls AskUserQuestion(question="How comfortable are you with investment risk?", options=["Conservative", "Moderate", "Aggressive"])]
→ User selects "Moderate"
[calls AskUserQuestion(question="How comfortable are you with investment risk?", options=["Low", "Medium", "High", "Long-term focus"])]
→ User selects "Medium"

Agent: [calls update_user_data(entity="risk_preference", data={"risk_tolerance": "medium"})]
Got it! Would you like to set up company interest, holding period,
analysis focus, or output style? These are optional.

User: Just company interest and output style

Got it! I've set your risk preference to moderate.
Agent: [calls AskUserQuestion(question="What type of companies interest you most?", options=["Growth", "Stable", "Value", "ESG"])]
→ User selects "Growth"

[calls AskUserQuestion(question="When I research stocks for you, how detailed should I be?", options=["Quick summaries", "Balanced analysis", "Thorough deep-dives"])]
Agent: [calls update_user_data(entity="investment_preference", data={"company_interest": "growth"})]
[calls AskUserQuestion(question="When I research stocks for you, how detailed should I be?", options=["Quick summaries", "Summary", "Data-focused", "Thorough deep-dives"])]
→ User selects "Quick summaries"

Agent: [calls update_user_data(entity="agent_preference", data={"output_style": "quick"})]
[calls update_user_data(entity="profile", data={"onboarding_completed": true})]

[calls AskUserQuestion(question="How often should I include charts and visualizations in my analysis?", options=["Always", "When useful", "Prefer not to", "Never"])]
→ User selects "When useful"

Agent: [calls update_user_data(entity="agent_preference", data={"enable_charts": "auto"})]

[calls AskUserQuestion(question="Should I ask clarifying questions before starting work?", options=["Always", "When unclear", "Prefer not to", "Never"])]
→ User selects "Always"

Agent: [calls update_user_data(entity="agent_preference", data={"proactive_questions": "always"})]
[calls update_user_data(entity="profile", data={"onboarding_completed": True})]
# Or: onboarding will auto-complete when risk_preference + at least one stock are set

Perfect! Your profile is set up:

Your profile is set up:
- Portfolio: AAPL (50 shares @ $175)
- Watchlist: NVDA
- Risk preference: Moderate
- Research style: Quick summaries
- Charts: When useful
- Proactive questions: Always
- Risk tolerance: Medium
- Company interest: Growth
- Output style: Quick summaries

Is there anything else you'd like to add or adjust?
```
Expand All @@ -269,8 +303,8 @@ Agent: [calls update_user_data(entity="agent_preference", data={"proactive_quest

## Tips for Good Onboarding

1. **Be conversational** - Don't ask all questions at once
2. **Respect their time** - If they seem brief, skip optional preferences
3. **Confirm each entry** - Let them know what was saved
4. **Handle errors gracefully** - If a stock exists, offer to update it
5. **End with a summary** - Show what was set up
1. **Be conversational** - Don't ask all questions at once.
2. **Ensure required items** - At least one stock + risk preference must be collected before completion.
3. **Optional preferences** - Company interest, holding period, analysis focus, output style are optional. Respect skips.
4. **Confirm each entry** - Let them know what was saved.
5. **Handle missing data** - Gently prompt for stocks or risk if user tries to skip them.
Loading