wealth-analyze-investment-performance

wealth-analyze-investment-performance

Trigger: Called by wealth-investment-review Produces: Investment performance summary at vault/wealth/00_current/YYYY-MM-performance.md

What It Does

Reads all investment account records from vault/wealth/00_current/ — one directory per account containing holdings snapshots, historical value records, and contribution logs — and produces a comprehensive performance and allocation analysis.

Per-account returns. For each investment account (identified by type and institution in config), the flow calculates: 30-day simple return ((current value − value 30 days ago) / value 30 days ago), YTD simple return ((current value − value on January 1) / January 1 value), and total return since inception where data allows. Dollar P&L is shown alongside percentage return. Contributions made during the period are noted separately so return is not inflated by new money.

Asset allocation derivation. Holdings records list each position by ticker or fund name. The flow maps each holding to an asset class category using the embedded fund taxonomy: domestic equity funds (e.g., FXAIX, VFIAX, VTI, SWTSX), international equity funds (e.g., VXUS, IXUS, FZILX), bond funds (e.g., BND, VBTLX, AGG), real estate/REITs (VNQ, VGSIX), cash and money market (SPAXX, FDRXX). When a holding is not in the embedded taxonomy, the user is prompted to classify it manually in the holdings record.

Allocation drift check. Actual allocation percentages across the entire invested portfolio (sum of all taxable and tax-advantaged accounts) are compared to the target allocation in config.md. Any asset class more than 5 percentage points from target is flagged for rebalancing. The flag includes: the asset class, current %, target %, over/under, the dollar amount to add or trim to restore target, and the specific account(s) best suited for the rebalancing trade (preference: tax-advantaged accounts first for rebalancing to avoid taxable events).

401k contribution pace. Reads YTD contribution total from the 401k holdings record and compares to the 2025 IRS limit ($23,500; $31,000 if age 50+). Annualizes the current contribution rate and flags if the projected full-year contribution will miss the limit by more than $500. Includes the math: "At your current rate of $X/paycheck biweekly, you'll contribute $Y by year-end — $Z below the limit. Increase to $Z/paycheck to max out."

IRA contribution tracking. Reads IRA contribution log and compares YTD contributions to the 2025 limit ($7,000; $8,000 if 50+). Flags the April 15 deadline for prior-year IRA contributions.

Triggers

• "investment review"
• "check my portfolio"
• "am I due for rebalancing"
• "how are my investments doing"
• "portfolio performance"
• "allocation check"
• "401k pace"
• "am I on track to max my IRA"

Steps

1. Read all investment account holdings files from vault/wealth/00_current/ — current holdings snapshot and historical value records
2. Calculate 30-day return per account using current value and value 30 days prior
3. Calculate YTD return per account using current value and January 1 value
4. Map each holding to an asset class using embedded fund taxonomy
5. Sum holdings by asset class across all accounts; compute portfolio-level allocation percentages
6. Compare actual allocation to target allocation from config.md; calculate drift per class
7. Flag any asset class with |drift| > 5% and calculate the rebalancing dollar amount
8. Read YTD 401k contributions from contribution log and compare to IRS limit; compute pace
9. Read IRA contribution log and compare to limit; flag if April 15 deadline is approaching
10. Write formatted performance summary and allocation analysis to vault/wealth/00_current/YYYY-MM-performance.md

Input

• vault/wealth/00_current/[account-name]/holdings.md — current holdings for each account
• vault/wealth/00_current/[account-name]/values.csv — historical account values by date
• vault/wealth/00_current/[account-name]/contributions.md — YTD contribution log
• vault/wealth/01_prior/ — prior period records for trend comparison
• vault/wealth/config.md — target allocation, account types, IRS limit overrides for catch-up contributions

Output Format

Markdown document at vault/wealth/00_current/YYYY-MM-performance.md:

• Performance table: Account | Institution | Type | 30-Day Return | YTD Return | Current Value | YTD Contributions
• Allocation table: Asset Class | Target % | Actual % | Drift | Dollar Amount | Status (OK / REBALANCE)
• 401k section: YTD Contributions | Annual Pace | IRS Limit | Gap | Suggested Increase
• Rebalancing recommendations section (if any drift > 5%)

Configuration

Required in vault/wealth/config.md:

• target_allocation — target percentages per asset class (must sum to 100)
• 401k_contribution_per_paycheck — current contribution amount
• paycheck_frequency — biweekly | semi-monthly | monthly | weekly
• age — for catch-up contribution limit eligibility (50+)
• ira_type — roth | traditional | both

Error Handling

• If a holding cannot be mapped to an asset class: list as "Unclassified — update holdings record" and exclude from allocation calculation; note total unclassified value
• If value history doesn't extend back 30 days or to January 1: compute return for available period and note the date range used
• If no investment accounts are configured: report "No investment accounts configured — add accounts to vault/wealth/config.md"

Vault Paths

• Reads from: ~/Documents/aireadylife/vault/wealth/01_prior/ — prior period records
• Reads from: ~/Documents/aireadylife/vault/wealth/00_current/ (all account subdirectories)
• Reads from: ~/Documents/aireadylife/vault/wealth/config.md
• Writes to: ~/Documents/aireadylife/vault/wealth/00_current/YYYY-MM-performance.md