var - backtest related and spy runbook

workflows/backtest-strategy/CONTEXT.md

@@ -0,0 +1,51 @@
+# Workspace Context: Strategy Backtest
+
+## Routing
+Given a strategy to backtest, the workflow proceeds through stages:
+
+1. **00_clarify_strategy** - Freeze the strategy rules with the operator into a
+   declarative spec (structure, entries, exits, session, sizing, costs).
+2. **01_verify_data** - Enumerate the contract universe, then verify historical
+   depth (minute-bar range per contract leg, quote-history lookback) with small
+   test pulls. Produce a data manifest with honest date ranges and gaps.
+3. **02_fetch_cache** - Single-pass bulk pull of bars/quotes into the shared
+   SQLite cache, keyed by (contract, timespan, window). Cache-first: existing
+   rows are never re-pulled.
+4. **03_run_backtest** - Author/run the stdlib-only engine over cached data.
+   No look-ahead. Costs from risk-params. Output trades.csv + metrics.json.
+5. **04_report** - Human-readable report: win rate, expectancy, drawdown,
+   per-hour breakdowns. Small-sample results flagged as small-sample.
+
+## Shared Resources
+- _config/: strategy spec template + risk parameters (stable reference).
+- shared/data/: SQLite cache of fetched bars/quotes (built during runs).
+- shared/scripts/: engine + helper scripts (stdlib only, authored at stage exec).
+
+## Data rules (verified 2026-08-27)
+- Options per-contract OHLC bars: minute→month timespans, history back to
+  2014-06-02, max 50,000 bars per pull. Daily summaries + previous-day also exist.
+- Options quote history + tick trade history exist per contract; quote-history
+  lookback depth is UNVERIFIED until stage 01 measures it.
+- Equity bars: custom OHLC (minute-level), daily summaries, grouped-daily
+  (all tickers), previous-day.
+- No historical greeks/IV series anywhere in the catalog: backtests are
+  price/levels-driven. IV-rank conditions are not testable.
+- Live chain snapshots (greeks/IV) are current-tape only — never a backtest source.
+
+## Engine rules
+- Pure Python 3.12 stdlib (json, csv, sqlite3, statistics, math, datetime, urllib).
+  NO pip installs — the operator manages packaging with uv; pyproject.toml
+  declares zero dependencies.
+- A credit spread is two leg pulls stitched: credit = short-leg price − long-leg
+  price at entry; P&L tracked per bar on the leg diff.
+- Costs: conservative slippage default (mid ± half-spread per fill), from
+  _config/risk-params.md.
+- Exits modeled per house style: stop, T1/T2/T3 partials, hard 15:45 ET time exit,
+  optional breakeven-after-T1.
+- RTH is the default session; extended only if the spec says so explicitly.
+
+## Honesty rules
+- Never present a backtest result without N (trade count) and the tested window.
+- Low-N results (<30 trades) must be labeled low-N in the report.
+- If data has gaps (no bars for an era/strike), say so in the manifest and report —
+  never silently interpolate through them.