| name | portfolio-macro-scenario |
| description | Prescriptive macro scenario analysis on a current book. Given a position book (CSV of ticker,shares) and a scenario stated as flags (--rates-bp, --dxy-pct, --oil-pct, --gld-pct), it regresses each position's daily returns on four macro factor ETFs (TLT for rates, UUP for the dollar/DXY, USO for oil, GLD for gold), translates the scenario into factor return shocks, and reports the expected per-position and book-level P&L with a rough 90% band, plus the dominant position and factor contributors. Use when the question is forward-looking and conditional: "what happens to my book if rates keep rising / the dollar keeps rallying / oil spikes / gold falls." This is the prescriptive counterpart to risk-report and portfolio-review, which are descriptive of the past. Runs on any stocks tier (Free Basic works with --sleep 13). |
portfolio-macro-scenario
risk-report and portfolio-review tell you what the book's risk has BEEN:
its realized vol, beta, VaR, drawdown. portfolio-macro-scenario tells you
what happens NEXT under a macro scenario the operator names. You hand it a
book and a scenario ("+50bp rates, +2% dollar"), and it returns the
expected P&L on each position and on the book as a whole, with a rough
confidence band and a ranked list of which positions and which factors are
doing the damage (or the lifting).
It is not a forecast of the scenario. It is a conditional read: IF these
factor moves happen, here is what your book does, grounded in each name's
historical sensitivity to real macro ETF prices, so an LLM does not have
to guess how any individual position responds to rates or the dollar.
When to invoke
- The question is forward-looking and conditional: "what happens to my
book if rates keep rising", "if the dollar keeps rallying", "if oil
spikes to $100", "if gold sells off 5%"
- Stress-testing a book against a macro view before putting on or lifting
a hedge
- The user says "scenario", "what if", "shock my book", "rate sensitivity
of my portfolio", "dollar exposure of my book", "macro stress test"
For the descriptive, past-looking risk picture (realized vol, beta, VaR,
drawdown, concentration) use risk-report. For what the
cross-asset tape is pricing right now (is the dollar strong, is credit
widening) use macro-basket. This skill is the bridge:
it takes the macro variables those skills describe and pushes them through
your specific book.
What you need
--book: a CSV of positions with columns ticker,shares (optional
cost_basis,as_of_date), matching
examples/sample-book.csv. Position
value is shares * latest close.MASSIVE_API_KEY exported in the environment.- Any stocks tier. On Free Basic pass
--sleep 13 so a larger book stays
under the 5-calls/min cap.
The scenario flags (all default 0, so a flat scenario returns zero P&L):
--rates-bp: parallel rate shock in basis points (+50 = rates up 50bp)--dxy-pct: dollar (DXY) shock in percent, applied as the UUP return--oil-pct: oil shock in percent, applied as the USO return--gld-pct: gold shock in percent, applied as the GLD return--lookback (default 252): trading days of returns for the regression
What you get back
Two output layers from one run.
Layer 1: canonical JSON matching
output-schema.json. Per-position betas (one per
factor), r_squared, residual_std, expected_return, pnl_usd, and
per-factor P&L contributions; a book_pnl block with the expected P&L, the
expected return, and the ~90% CI band; dominant_positions and
dominant_factors ranked by contribution; the composed take.
Layer 2: rendered table (output mode table): a sensitivity table
(position x factor beta with R^2 and per-position P&L), the book P&L with
the CI band, the dominant-contributor lists, and the take. See
references/rendering.md.
How it works
- Pull daily aggregates for every position ticker plus the four macro
factor ETFs (TLT, UUP, USO, GLD) over
max(lookback, 252) * 1.6
calendar days, via /v2/aggs/ticker/{T}/range/1/day/{from}/{to}.
- Align daily returns by date, per position against the four factors.
- Regress each position's returns on the four factor returns with an
intercept (numpy
lstsq), producing four betas, a residual std, and an
R^2.
- Shock the factors: convert the scenario flags into factor ETF
returns (the rate shock goes through an assumed TLT effective duration
of ~17 years). The full conversion and its assumptions live in
references/methodology.md.
- Push through the betas: expected position return is the sum of
beta_factor * factor_shock; position P&L is position_value * expected_return; aggregate to the book with a ~90% band.
- Rank contributors and compose the take.
Foundations used
massive-api-patterns for REST auth,
rate-limit handling, and the /v2/aggs daily endpoint conventions.
Output mode: table
The core deliverable is a sensitivity grid (position x factor beta) plus
per-position and book P&L. A table carries that comparison cleanly; the
book P&L line, dominant-contributor lists, and take sit above and below it.
Chains with
risk-report: the descriptive counterpart. Run
risk-report for the realized risk picture, then this skill to stress the
same book against a named macro move. risk-report is the declared
fallback when a scenario cannot be run.macro-basket: reads what the cross-asset tape is
pricing now (rates, dollar, credit, gold, commodities). Use it to pick a
realistic scenario, then feed the numbers here.hedge-suggester: once this skill surfaces the
book's dominant factor exposure, hedge-suggester proposes what to put on
against it.
Doesn't handle (yet)
- Non-linear moves. Shocks are applied linearly through the betas; a
large move has convexity this does not capture. Queued.
- Factor collinearity. The four factors co-move, so individual betas
can be noisy even when the aggregate fit is good. A ridge or orthogonal
factor set would firm them up. Queued.
- Residual correlation. The CI band assumes independent residuals
across names, so the true band is wider. Queued.
- Custom factors. The factor set is fixed at rates/dollar/oil/gold. A
configurable factor list (credit, real yields, a sector ETF) is a clean
extension. Queued.
These are clean PR extensions. The output schema is forward-compatible.
