git:20260826.8da358a to git:20261008.6d4ab17

- description: First-time user onboarding to set up investment profile, watchlists, portfolio, and preferences.

- ---

-

- # Onboarding Skill

-

- ## Purpose

-

- Help new users set up their investment profile through a natural, conversational flow. The agent gathers preferences and stores them as rich, descriptive text that future conversations can reference for personalized advice.

-

- This skill provides 5 tools:

- - `get_user_data` - Read user data

- - `update_user_data` - Create or update user data

- - `remove_user_data` - Delete user data

- - `manage_workspaces` - Create workspaces (via action="create")

- - `ptc_agent` - Dispatch a research question to a workspace

-

- You should call these tools directly instead of using ExecuteCode tool.

-

- ---

-

- ## Tool Reference

-

- ### Tool 1: get_user_data

-

- Retrieve user data by entity type.

-

- | Entity | Description | entity_id |

- |--------|-------------|-----------|

- | `all` | Complete user data (profile, preferences, watchlists with items, portfolio) | Not used |

- | `profile` | User info (name, timezone, locale) | Not used |

- | `preferences` | All preferences (risk, investment, agent) | Not used |

- | `watchlists` | List of all watchlists | Not used |

- | `watchlist_items` | Items in a specific watchlist | Optional watchlist_id |

- | `portfolio` | All portfolio holdings | Not used |

-

- ```python

- # Get complete user data (recommended at start of onboarding)

- get_user_data(entity="all")

- ```

-

- ### Tool 2: update_user_data

-

- Create or update user data (upsert semantics). Preference entities merge by default.

-

- | Entity | Description |

- |--------|-------------|

- | `profile` | User info (name, timezone, locale, onboarding_completed) |

- | `risk_preference` | Risk tolerance settings |

- | `investment_preference` | Investment style settings |

- | `agent_preference` | Agent behavior settings |

- | `watchlist` | Create or update a watchlist |

- | `watchlist_item` | Add or update item in watchlist |

- | `portfolio_holding` | Add or update a portfolio holding |

-

- All preference fields accept **any descriptive string**. Extra fields are allowed and persisted.

-

- ```python

- # Good - rich context that helps future conversations

- update_user_data(entity="risk_preference", data={

- "risk_tolerance": "Moderate - comfortable with market swings but avoids concentrated bets",

- "notes": "Lost money in 2022 tech crash, now prefers diversification"

- })

-

- # Bad - keyword with no context

- update_user_data(entity="risk_preference", data={"risk_tolerance": "medium"})

- ```

-

- ### Tool 3: remove_user_data

-

- Delete user data by entity type.

-

- | Entity | Identifier fields |

- |--------|-------------------|

- | `watchlist` | `watchlist_id` or `name` |

- | `watchlist_item` | `symbol` (+ optional `watchlist_id`) |

- | `portfolio_holding` | `symbol` (+ optional `account_name`) |

-

- ### Tool 4: manage_workspaces (action="create")

-

- Create the user's first workspace. This requires user approval — the user sees a card and must approve.

-

- | Parameter | Type | Description |

- |-----------|------|-------------|

- | `action` | string | Must be `"create"` |

- | `name` | string | Name for the workspace (e.g. "My Portfolio Analysis") |

- | `description` | string | Brief description of the workspace purpose |

-

- ```python

- manage_workspaces(action="create", name="My Portfolio Analysis", description="Track and analyze my stock portfolio")

- ```

-

- Returns `{ success: true, workspace_id: "...", workspace_name: "..." }` on approval, or `"User declined workspace creation."` on rejection.

-

- ### Tool 5: ptc_agent

-

- Dispatch a personalized research question to a workspace. This requires user approval — the user sees the question and can approve to start the analysis.

-

- | Parameter | Type | Description |

- |-----------|------|-------------|

- | `question` | string | An actionable question related to the user's interests |

- | `workspace_id` | string | The workspace ID (from `manage_workspaces` result) |

-

- ```python

- ptc_agent(

- question="Analyze my NVDA position — what's the current technical setup and any upcoming catalysts I should watch for?",

- workspace_id="abc-123"

- )

- ```

-

- Returns `{ success: true, workspace_id: "...", thread_id: "...", status: "dispatched" }` on approval, or `"User declined research dispatch."` on rejection.

-

- ---

-

- ## What to Gather

-

- ### Stocks (Required, Structured)

-

- At least one stock must be added to the watchlist or portfolio before onboarding can complete. Use the structured `watchlist_item` or `portfolio_holding` entities.

-

- ```python

- # Watchlist item

- update_user_data(entity="watchlist_item", data={

- "symbol": "NVDA", "notes": "Watching for AI chip growth"

- })

-

- # Portfolio holding

- update_user_data(entity="portfolio_holding", data={

- "symbol": "AAPL", "quantity": 50, "average_cost": 175.0

- })

- ```

-

- ### Risk & Investment Profile (Required, Flexible)

-

- Gather enough context so future conversations can give personalized advice. At minimum, capture `risk_tolerance` on `risk_preference`. Topics to explore:

-

- - **Risk comfort** - How much volatility can they handle? Any past experiences that shaped their risk view?

- - **Investment style** - Growth, value, income, ESG? Any sectors they avoid or focus on?

- - **Time horizon** - Short-term trading, long-term holding, or flexible?

- - **Analysis preference** - Do they care most about growth metrics, valuation, competitive moat, or risk factors?

-

- Store these as descriptive text across `risk_preference` and `investment_preference`:

-

- ```python

- update_user_data(entity="risk_preference", data={

- "risk_tolerance": "Conservative - prioritizes capital preservation, uncomfortable with >10% drawdowns",

- "notes": "Nearing retirement in 5 years, shifting from growth to income"

- })

-

- update_user_data(entity="investment_preference", data={

- "company_interest": "Dividend-paying blue chips and REITs for income",

- "holding_period": "Long-term (5+ years), rarely sells",

- "analysis_focus": "Dividend sustainability, payout ratio, and balance sheet strength",

- "avoid_sectors": "Crypto, speculative biotech"

- })

- ```

-

- ### Agent Preferences (Optional, Flexible)

-

- How does the user want the agent to behave? Topics to explore:

-

- - **Output style** - Quick bullet points, balanced summaries, or deep dives?

- - **Visualization** - Always include charts, only when helpful, or prefer text?

- - **Proactive questions** - Should the agent ask before acting, use its judgment, or only ask when critical?

- - **Anything else** - Notes, instructions, preferences the user wants remembered.

-

- ```python

- update_user_data(entity="agent_preference", data={

- "output_style": "Balanced summary with key numbers highlighted",

- "data_visualization": "Include charts when comparing multiple stocks",

- "proactive_questions": "Use your judgment, only ask when the decision significantly impacts the analysis",

- "instruction": "Always mention if a stock has upcoming earnings within 2 weeks"

- })

- ```

-

- ## Conversation Guide

-

- ### Always Use AskUserQuestion

-

- Present options so the user can tap instead of type. Options are **starting points for richer conversation**, not rigid mappings. After the user selects an option, capture the full context of their choice (including any follow-up detail) as descriptive text.

-

- Example AskUserQuestion options by topic:

-

- **Risk comfort:**

- - "Conservative - protect my capital"

- - "Moderate - balanced risk and reward"

- - "Aggressive - maximize growth potential"

- - "I have a nuanced view"

-

- **Investment style:**

- - "Growth companies with strong momentum"

- - "Stable dividend payers for income"

- - "Undervalued opportunities"

- - "ESG / sustainable investing"

-

- **Time horizon:**

- - "Short-term (under 1 year)"

- - "Medium-term (1-5 years)"

- - "Long-term (5+ years)"

- - "Flexible - depends on the opportunity"

-

- **Analysis preference:**

- - "Focus on growth metrics (revenue, earnings growth)"

- - "Focus on valuation (P/E, DCF)"

- - "Focus on competitive moat and market position"

- - "Focus on risk factors and downside protection"

-

- **Output style:**

- - "Quick bullet points - just the highlights"

- - "Balanced summary with supporting data"

- - "In-depth deep dive with full analysis"

- - "Data-heavy with charts and numbers"

-

- **Visualization:**

- - "Always include charts and visuals"

- - "Include when it helps explain something"

- - "Prefer text-only analysis"

-

- **Proactive questions:**

- - "Ask me before making decisions"

- - "Use your judgment most of the time"

- - "Only ask when it's critical"

-

- ### Storing Responses

-

- After the user selects an option (or provides a custom answer), store the **descriptive text**, not a keyword:

-

- ```python

- # User selected "Moderate - balanced risk and reward" and added

- # "but I get nervous during big market drops"

- update_user_data(entity="risk_preference", data={

- "risk_tolerance": "Moderate - balanced risk and reward, but gets nervous during big market drops"

- })

- ```

- ### Conversation Flow

- 1. **Start** - Greet the user, explain what you'll set up, and ask about stocks they're watching or own.

- 2. **Stocks** - Add their stocks to watchlist/portfolio. Ask follow-up for holdings (quantity, cost basis).

- 3. **Risk & Investment** - Use AskUserQuestion for each topic. Follow up naturally for more detail.

- 4. **Agent Preferences** - Optional. Ask about output style, visualization, proactive questions.

- 5. **Open-ended** - "Anything else I should know about how you like to work?"

- 6. **Complete** - Summarize what was set up, mark onboarding complete.

- 7. **Workspace & Question** - After completing onboarding, create a workspace using `manage_workspaces(action="create", name="...", description="...")` with a name and description that fits the user's interests. Then use `ptc_agent(question="...", workspace_id="...")` with the returned `workspace_id` to dispatch an actionable starter question based on the user's stocks or interests. The question should be specific and immediately useful (e.g. "Analyze my NVDA position — what are the key technical levels and upcoming catalysts?" rather than "Tell me about stocks").

- Don't ask all questions at once. Let the conversation flow naturally. If the user wants to skip optional topics, respect that.

- ### Not Exhaustive

- The listed topics are a starting point. If the conversation naturally reveals other preferences (e.g., specific sectors to avoid, earnings season behavior, news sensitivity), store those too. Any extra fields are accepted via `extra="allow"` on the models.

- ---

- ## Completion Requirements

- Before marking onboarding complete, verify:

- 1. At least one stock was added (watchlist or portfolio)

- 2. Risk preference was set (any truthy value in `risk_preference`)

- ```python

- # Mark onboarding complete

- update_user_data(entity="profile", data={"onboarding_completed": true})

- ```

- If missing:

- - **No stocks:** "Before we finish, let's add at least one stock you're interested in. What's a stock you're watching or own?"

- - **No risk preference:** "One more thing - I'd like to understand your risk comfort level so I can tailor my advice."

- ---

- ## Tips

- 1. **Be conversational** - Don't interrogate. Let topics flow naturally and combine related questions.

- 2. **Use AskUserQuestion for choices** - Always present options as selectable buttons. Only use plain text for open-ended input (stock symbols, quantities, notes).

- 3. **Handle partial info** - If the user says "I own some AAPL", follow up for quantity and cost basis.

- 4. **Confirm entries** - After saving, briefly confirm: "Added AAPL (50 shares @ $175) to your portfolio."

- 5. **Capture context, not keywords** - The user's words and nuances are more valuable than a one-word category.

- 6. **Use defaults** - If user doesn't specify a watchlist, items go to the default one automatically.

- 7. **Respect skips** - Investment preferences and agent preferences are optional. Don't push if the user wants to move on.

- ---

- ## Error Handling

- - If a stock is already in a watchlist, inform the user and offer alternatives

- - If a holding already exists, offer to update it instead of creating a duplicate

- - If user_id is not available, inform that the user needs to be logged in