/portfolio-rebalance-review

name: portfolio-rebalance-review
description: Run a portfolio review for a client or household — performance pulled from Orion, allocation drift analysis vs. IPS or model portfolio, model-portfolio mapping, rebalance preparation with tax-aware rebalance opportunities to consider, and a rebalance rationale memo for the compliance file. Triggers on "portfolio review", "/portfolio-rebalance-review", "drift analysis", "rebalance [client]", "how is [client]'s portfolio positioned", "rebalance rationale", or "map [client] to a model".

Portfolio Rebalance Review

Review a client portfolio end to end: performance → drift → model mapping → rebalance prep → rebalance rationale memo.

Inputs

Required: **client/household name**. Optional: which accounts to include, the model portfolio or IPS targets (if not on file), and whether the advisor wants analysis only or a full rebalance prep.

Step 1: Pull Performance & Holdings

**Disambiguation rule:** confirm which household before pulling anything, the same as every other skill in this plugin — if a name search returns more than one match, show the advisor the candidates and ask which one before proceeding. Never proceed on a name match alone.

Query the household's connected portfolio-data system for:

• Accounts with registrations (taxable, IRA, Roth, 401k, trust) and market values
• Holdings with quantity, market value, cost basis, and unrealized gain/loss
• Performance: QTD/YTD/1yr/3yr vs. assigned benchmark, net of fees
• Assigned model/target allocation and cash balances
• Recent flows (contributions, distributions, RMD status)

**Which system to query:** this data can live in Orion, Addepar, or Envestnet/Tamarac depending on the firm. Check `ListConnectors` (load via `ToolSearch` if not already available) to see which is actually connected — don't guess at tool-name prefixes, use `ToolSearch` by system name once you know which is live.

**Look for the tools before you trust the registry.** `ToolSearch` by the system's own name is the check that decides: if its tools come back, that system is connected and callable — use them. `ListConnectors` can answer "No installed connectors found" even in a session with several live, working connectors, and in some clients it renders a user-facing card rather than returning data at all. So it explains a gap, it never establishes one, and an empty result means **unknown**, never "nothing is connected". When it does return entries, read `enabledInChat`, not `connected`: `connected: true` with `enabledInChat: false` is authenticated but switched off for this chat, so tell the advisor they can enable it here rather than reporting it as unconnected; a missing or `null` `connected` is unknown, not disconnected.

• **If none is connected**: follow the Connector Placeholder Convention — say *"This is where I'd make a call out to [system] to pull [holdings/performance] once that connector is built,"* then offer the fallback. Before asking for a manual upload, offer to search Google Drive (if connected) for an existing export or statement. If nothing turns up there either, ask the advisor to upload an export (CSV/PDF), a custodian statement, or paste holdings. Continue with whatever's provided, and mark anything still missing "— pending [connector]" rather than leaving it blank — a missing source degrades only the section that depends on it, not the whole review.
• **If more than one connected tool could try to solve this for the household**, ask the advisor once which is the book of record — per the Ask-Once, Then Route Convention — rather than guessing or merging both, and use that system for the rest of this review. This applies even when the household name hasn't resolved against either system yet: ask before searching further, not after finding out neither recognizes the name — an unresolved household is not an exception to this rule. Offer to help the advisor save the choice using the Personalization Convention so they aren't asked again next session. This check runs for the rest of the review, not just once up front — if the advisor brings up another source mid-review, ask before pulling from it too. And if a second system's figures get pulled anyway and disagree with the routed one on a material fact (a balance, a drift percentage), that's a blocking question for the advisor, not a note in the output.

**Held-away accounts:** ask the advisor whether the household has accounts held away from this system (a spouse's 401k, assets at another custodian) relevant to wash-sale coordination or the overall allocation picture. If yes, request those holdings manually — there's no connector for outside accounts.

**Addepar specifics:** call `get_portfolio_data` with `lookthrough=false` for drift purposes. Lookthrough decomposition (fund → underlying constituents) is a separate risk-review lens — an IPS names sleeves at the fund-commitment level, and lookthrough silently returns an incompatible set of buckets with no warning. Group by `direct_owner`, not `account` — the latter is not a valid grouping key and errors. For tax-lot detail, pass a tax-lot value in `groupings` only if the live tool schema actually documents one — cost basis and lot-level fields are not confirmed to exist on every Addepar deployment. If the schema doesn't support it or the returned columns don't include cost basis, say so explicitly rather than presenting fabricated lot data; this feeds the same "Completeness" gate below.

**Orion specifics:** Orion Connect's tools (household search, report catalog, report parameters, `oc_generate_report`) are identity and report-catalog/generation only — they do not return structured holdings, cost basis, or tax lots. Generating a report yields a **link to the finished report**, not its contents — hand it to the advisor and say it **expires after 24 hours** (a unique per-run URL; regenerate rather than troubleshoot an expired one); don't fetch it to scrape a holdings table out of, and don't treat