okama-mcp: Skill for Claude Code

Stress-Testing Portfolios

Overview

A stress test is only as good as the series underneath it. The wrong answers in this work are rarely modelling errors — they are data defects and unit slips the arithmetic absorbs silently: a history window that quietly shrank, a fund whose price was frozen for two years, a nominal withdrawal measured against a real portfolio value.

Run the mechanical gates first, then apply judgment. Both halves are below; neither substitutes for the other.

When to Use

• Backtesting a portfolio across crisis episodes (1998, 2008, 2014-16, 2022)
• Modelling a currency devaluation, inflation regime or rate shock forward
• Any portfolio holding funds (БПИФ/ETF) younger than the episodes tested
• Withdrawal sustainability, survival horizon or tax-consequence questions

Not for: single-asset return lookups, portfolio optimisation, or plain Monte Carlo (call monte_carlo_forecast directly).

Workflow

1. Gate the data. poetry run python stress_test.py check SYM1 SYM2 ... --first 2010-02 Reports the binding history floor and every frozen price run. Do not walk past a finding — resolve it, or state it and its direction of bias in the report.
2. If the episodes predate the floor, build a proxy from long-history indices at the same weights, paired sleeve-to-sleeve.
3. Validate the proxy on the overlap — stress_test.py validate. Full window and each calendar year; an annual outlier is where the defects hide. An unvalidated proxy replay is not a result.
4. Attribute every divergence to a named sleeve before explaining it — stress_test.py attribute --first ... --last ..., one episode window at a time. The contributions must sum to the observed gap.
5. Replay the episodes, then calibrate scenario coefficients from those episodes.
6. Run the forward scenarios and report a range, not a point.

Gates the Script Runs

Gate	What it catches	Why it exists
History floor	okama truncates first_date to the intersection of all series, without raising or warning	first_date=2010-02 on a basket containing LQDT.MOEX silently returns 2020-02 — 120 months shorter. A "2014-16 replay" would have been computed entirely on post-2020 data
Frozen series	runs of an unchanged monthly close	SBCB.MOEX sat at 1055.0 for 22 months (2022-02..2023-11: trading suspended, underlying eurobonds blocked), reading as a flat 0% return
Proxy validation	a proxy that does not track the actual	catches sleeve substitutions that drift
Gap attribution	a divergence explained by a story instead of a sleeve	the fact/proxy gap was first blamed on "the proxy runs hot"; per-sleeve attribution put the bulk of it on the frozen SBCB — the fact understated, the proxy did not overstate. Opposite sign, opposite conclusion
Rebalance thresholds	which threshold binds, per sleeve	see below