Risk Parity Compass

A React + Vite static site for risk parity portfolio rebalancing and retirement drawdown planning. It tells you what to trade to reach your target risk allocation tax-efficiently, and then how much you can spend from that portfolio once you stop earning.

Deploys free to GitHub Pages: https://paruff.github.io/risk-parity-compass/

Not financial advice. This is educational planning software. Every projection depends on assumptions you supply, and historical and simulated returns do not predict the future.

What it does

Accumulation / rebalancing

• Risk parity allocation — equal-risk-contribution weights (long-only, unlevered) from live volatilities and correlations
• Tax-efficient placement — waterfall algorithm (bonds → IRAs, stocks → taxable)
• Rebalancing guidance — trade only when drift exceeds your threshold, harvesting volatility (the "Shannon's Demon" effect) without paying for noise
• Risk contribution and correlation views for the chosen mix
• Scenarios — save and compare portfolio configurations

Drawdown / retirement

• Withdrawal sequencing — a common heuristic (taxable → traditional with an RMD floor → Roth) or a bracket-filling order that draws traditional money first up to a federal bracket allowance, with an optional Roth conversion that fits in the unused room. Both are planning heuristics, not tax advice
• RMD table — IRS Uniform Lifetime Table, with the SECURE 2.0 73/75 eligibility split
• Spending guardrails — RPR-80 is selectable (a trip can only cut spending, never raise it); Guyton-Klinger and VPW exist in the engine but are not exposed in the UI yet
• Static vs guardrail — Monte Carlo success probability and terminal values side by side, on identical simulated markets
• Income floor — Social Security and pension netting, with bridge-year awareness
• Historical backtest — rolling safe and perpetual withdrawal rates on 1928–2025 annual index proxies when every holding has one, otherwise on your ETFs' own history; the metrics are withheld, with the reason, when that history is too short, and the window count is always shown
• Monte Carlo — fan chart of simulated outcomes with withdrawals; resamples whole historical years (keeps stock/bond co-crashes) when every holding has a proxy, otherwise Gaussian shocks. The method is stated under the chart

Portfolio library

• Templates — Golden Butterfly, All Seasons and Golden Ratio as published on riskparityradio.com (URL and review date recorded per template), plus the classic Permanent Portfolio credited to Harry Browne
• Template cards — each shows description, allocations and source, with its own Load button
• Compare — up to 3 templates at once against your current weights, with SWR, PWR, success probability and max drawdown side by side
• Diversification score — average and max pairwise correlation plus macro-class count, with warnings above 0.6 average or below 4 classes
• Load Template — replaces your tickers and re-runs analysis; your saved scenarios are untouched until you save

Quick start

npm ci          # install
npm run dev     # dev server on http://localhost:5173/risk-parity-compass/
npm run build   # production build to dist/
npm run preview # preview the build on http://localhost:4173/risk-parity-compass/

Using it

1. Assets — enter tickers (comma-separated), pick a volatility lookback, set a rebalance threshold
2. Accounts — enter Taxable, Traditional IRA/401k and Roth IRA balances, plus current share counts
3. Run Analysis — fetches prices, computes targets, and generates trades
4. Retirement — enter spend, horizon, inflation, birth year and any Social Security or pension income, then run the projection

State persists in localStorage under rpcompass_* keys (schemaVersion 2). Data saved under the old shannonsdemon_* keys (the project's former name) is migrated on first load and left in place as a backup; plan files exported under the old name still import.

Retirement tab — Safe/Perpetual Withdrawal Rate, Monte Carlo success probability, RMDs, guardrails (None, RPR-80) and a static-vs-guardrail comparison. Every metric block carries a planning-estimate disclaimer. Download PDF uses the browser print dialog with a print stylesheet (no sidebar, nav or dark theme).

Portfolios tab — curated templates you can load, compare and analyse. Template weights are validated, never adjusted to sum to 1.

Data resilience — every quote carries its snapshot date. If a ticker is missing from the snapshot the app says so and suggests close matches, and you can override a price by hand. The Retirement tab reports the effective history horizon and which ticker limits it.

Backup and accessibility — Export plan / Import plan (versioned, validated JSON, includes scenarios); a reminder appears when a backup is over 30 days old or storage is nearly full. Text size (100/115/130%) and high contrast persist.

Data source

Prices are a bundled snapshot, not a live feed. npm run prices:update (scripts/update-prices.mjs) fetches daily (2 years) and monthly (full history) adjusted closes from Yahoo Finance's unofficial chart endpoint server-side, one polite request at a time, and writes one JSON file per ticker to public/prices/ plus an index.json. The site reads those files from its own origin, so browsers never call Yahoo (it sends no CORS header and cannot be called from GitHub Pages). The deploy workflow refreshes the snapshot best-effort on weekday evenings; if Yahoo rate-limits the runner, the committed files are used. Yahoo is the only data source (the project has no API key for a fallback provider), so a blocked refresh means stale prices, not a different source; there is no live or intraday pricing. Only tickers in the snapshot can be analysed (about 50 common ETFs: the defaults, every template holding and the common-ETF list). Tests never call Yahoo: unit tests use MSW and E2E uses Playwright route interception on the snapshot files.

Static datasets are also bundled and need no network: the IRS RMD table and the 1928–2025 long-run returns (see below).

Long-run history and attribution

Rolling SWR/PWR/success and the Monte Carlo use bundled annual returns for 1928–2025 (src/utils/long-run-returns.json):

• Returns on US stocks, small-cap stocks, T-bills, 10-year Treasuries, Baa corporate bonds, real estate and gold from Aswath Damodaran, Historical Returns on Stocks, Bonds and Bills: 1928–2025, NYU Stern, https://pages.stern.nyu.edu/~adamodar/pc/datasets/histretSP.xls (his own sources include S&P, Ken French's data library, FRED and Shiller). His usage rules say the data is free to use and ask for acknowledgement; they also say it is not meant for public policy debates or court cases, and that it is best suited to real-time valuation work rather than historical research. Here it is a planning proxy only.
• Inflation: U.S. Bureau of Labor Statistics, Consumer Price Index for All Urban Consumers: All Items in U.S. City Average [CPIAUCNS], retrieved from FRED, Federal Reserve Bank of St. Louis, https://fred.stlouisfed.org/series/CPIAUCNS (public domain, citation requested).

Privacy

Everything you enter stays in your browser's localStorage; there is no server, account or analytics. The page makes no requests to third parties: prices are static files served from the same site, so not even the tickers you look up leave your browser. See SECURITY.md.

Quality gates

Gate	Command	Budget
Unit / integration	npm test	must pass
End-to-end	npm run test:e2e	must pass
Lint	npm run lint	0 errors
Format	npm run format	Prettier clean
Build	npm run build	must succeed
Lighthouse	CI	perf ≥ 0.9, a11y ≥ 0.95, best practices ≥ 0.9, SEO ≥ 0.9

Pre-commit runs Lefthook + lint-staged on staged files. CI runs every gate plus the build on each push and pull request. A human reviews and merges; agents never merge.

Environment note: this repository's tooling requires env -u NODE_OPTIONS <command> for Node subprocesses, because a broken NODE_OPTIONS shim in the development environment breaks vitest, Playwright, hooks and Lighthouse.

Documentation

Document	Purpose
DESIGN.md	Design tokens, component rules and UI do's/don'ts (designmd.app / Google design.md format)
docs/intent.md · docs/spec.md · docs/plan.md	Why, contracts, and milestones mapped to GitHub issues
REVIEW.md	How to review a change here
AGENTS.md	Repository context and conventions for AI agents
docs/superpowers/specs/2026-10-25-retirement-production-roadmap-design.md	Long-form roadmap spec (history)
docs/superpowers/plans/	Implementation plans, one per milestone
docs/superpowers/reviews/	Code review records
Known Limitations.md	Known constraints and open risks

Roadmap

Source of truth: docs/plan.md, which maps each milestone to its GitHub issue and PR.

Milestone	Scope	State
M1–M3.5	Withdrawal engine, tax and account mechanics, guardrails, correctness remediation	shipped
M4	Portfolio templates, diversification view, comparison	shipped
M5	Storage v2, print/PDF, accessibility preferences	shipped
M6	Learning journey: competency rubric, engine-graded modules, spaced refresher	shipped
M7 (#37)	Expert review remediation: guardrail cap (#29), honest historical metrics (#30), template fidelity (#31), long-run history (#32), bootstrap Monte Carlo (#33), equal-risk-contribution weights (#34), tax-aware drawdown (#35), code hygiene (#36)	shipped

Headline historical metrics now rest on proxy history for most portfolios; read Known Limitations.md for what the proxies cannot represent.

History

Began in 2025 as a Streamlit tool called Shannon's Demon, was rewritten as a React + Vite SPA in 2026, and renamed Risk Parity Compass when it grew a retirement drawdown engine. "Shannon's Demon" now names only the rebalancing effect the app uses. See docs/intent.md for provenance.

License

MIT — see LICENSE.