# Options Vol Regime Transitions

## What it measures
The Vol Regime Transitions dashboard measures how often the platform's volatility regime state changes, how long each state usually persists, and which transitions are empirically common versus rare.

It is built from `vol_regime_transition_series` and the platform's existing options composite regime labels.

The goal is not to predict the next state mechanically. The goal is to provide base rates:
- how sticky is `long_vol_bias`?
- how often does `neutral` flip into `short_vol_bias`?
- when a regime turns, how long does it usually survive?

## Inputs
- `options_signal_series`
  - `vol_regime_score`
  - `signal_state`
- optional context from:
  - `vvix_series`
  - `razor_series`
  - `funding_context_series`

## Derived fields
- `current_state`
  - current regime label for the asset
- trailing transition probabilities such as:
  - `p_neutral_to_long_vol`
  - `p_neutral_to_short_vol`
  - `p_long_vol_to_neutral`
  - `p_short_vol_to_neutral`
- `median_state_duration_hours`
  - rolling median persistence of the active state
- `quality_flag`
  - indicates whether enough state history exists to trust the transition statistics

## How to interpret it
High persistence for `long_vol_bias`:
- long-vol signals have historically clustered instead of immediately mean-reverting
- you should be slower to fade a fresh vol expansion

High persistence for `short_vol_bias`:
- carry-dominant regimes have historically lasted
- outright short-vol trades or short-end carry expressions are more defensible

Frequent `neutral -> long_vol_bias` transitions:
- the asset has a tendency to snap from calm to stress quickly
- short-vol entries should require stronger confirmation

Frequent `long_vol_bias -> neutral` transitions:
- vol shocks tend to compress quickly
- long-vol trades should be sized with shorter holding-period expectations

## Trade usage
Use this dashboard as a sizing and holding-period tool, not a standalone entry trigger.

Examples:
- if `vol_regime_score` flips to `long_vol_bias` and the transition matrix says that state historically lasts `18` hours median, you can size for persistence instead of treating the signal as a one-bar event
- if `short_vol_bias` historically collapses quickly after sharp spot moves, reduce size on fresh short-vol entries even when carry looks rich
- when paired with [Options Funding Context](docs/options-funding-context.md), you can tell whether a funding squeeze is occurring inside a regime that usually extends or usually mean-reverts

## Failure modes and false positives
- Transition statistics are only as good as the amount of recent history available.
- Structural market change can invalidate the trailing transition base rates.
- State definitions inherit any weaknesses in `vol_regime_score`.
- This dashboard is descriptive, not causal; do not use it as the sole reason to hold risk longer.

## Companion dashboards
- Check [Options Signals](docs/options-signals.md) to see the underlying state driver.
- Check [Options Funding Context](docs/options-funding-context.md) to understand whether basis pressure is reinforcing the regime.
- Check [Options Straddle Breakeven](docs/options-straddle-breakeven.md) to see whether the current regime is still paying long gamma or has already become rich.
