Decision Log

This log records product and data-integrity decisions that affect how the Vol Dashboard should calculate, display, and explain trading analytics. Use it alongside the Calculation Reference when reviewing whether dashboard numbers are defensible.

For the current operational explanation of unavailable MSTR/COIN execution benchmarks, forward outcome marks, null P&L, and backfill validation commands, see Trade Performance Data Gaps. For business-facing discussion topics, see Trade Performance Business Discussion Guide. For current opportunity scoring thresholds and confidence penalties, see Opportunity Alignment Rules.

For the sponsor-facing strategy and decision matrix for the next phase, see Regime-Aware Trade Copilot Strategy. For derivative-equivalent identity and proxy mapping policy, see Derivative Identity And Proxy Mapping. For source-authority policy across marks, P&L, estimates, proxies, and unavailable states, see Source Authority Register. For preparatory implementation specifications, see Data Ingestion Readiness Plan, Regime Model Specification, Trade Copilot Evaluation Specification, and SMA Ingestion Requirements.

2026-05-12: Preparatory Specification Pack For Gordon Review

Status: Preparatory specification pack

Linear context: ENG-5169, ENG-5239, ENG-5240, ENG-5241, ENG-5242, ENG-5243, ENG-5244, ENG-5245, ENG-5246, ENG-5247, ENG-5248, ENG-5249, ENG-5250, ENG-5251, ENG-5252

Decision: Create a grouped preparatory documentation pack before implementation so Gordon can review the data-readiness, regime-model, trade-copilot, and SMA-ingestion contracts.

Rationale:

• The remaining work contains business-sensitive assumptions around lookbacks, proxy use, confidence thresholds, warning language, and derivative-equivalent mappings.
• Engineering can safely specify source contracts, reason codes, model provenance, and warning taxonomy without changing production behavior.
• Gordon should be able to read the site reference docs and see exactly what would be implemented before the dashboard starts making stronger model or trade-restructuring statements.

Implementation implications:

• Keep this stage preparatory only.
• Do not change ingestion jobs, model logic, warning logic, candidate rankings, or SMA sync until Gordon reviews the documents.
• Use the new docs as the acceptance source for later implementation tickets.

2026-05-12: Derivative Identity And Proxy Mapping Contract

Status: Preparatory mapping contract

Linear context: ENG-5238

Decision: Create a preparatory contract that separates traded contract identity from market/regime proxy context and valuation source authority before implementing database, backend, or UI identity changes.

Rationale:

• Gordon clarified that SMA, OTC-like trades, custom strikes, custom expiries, adjusted contracts, and proxy tickers are all the same mapping problem.
• A BTC market proxy can explain opportunity backdrop for MSTR/COIN trades, but it cannot validate MSTR/COIN execution marks, liquidity, or P&L.
• Standard-root fallback for adjusted contracts must remain visibly caveated and cannot be mistaken for authoritative adjusted-contract mapping.
• Provider symbols and schemas should be validated rather than assumed from documentation alone.

Implementation implications:

• Future mapping work should distinguish exact_listed, adjusted_authoritative, standard_root_fallback, derivative_equivalent, proxy_context_only, custom_pending_listing, unmapped, unsupported, and needs_review.
• Unknown underlyings must not silently default to BTC.
• Valuation and P&L require both derivative identity and source authority.
• SMA ingestion and provider lookup changes remain deferred until Gordon reviews the strategy and mapping policy.

2026-05-11: Source Authority Register For Decision-Grade Outputs

Status: Preparatory policy register

Linear context: ENG-5253

Decision: Create a source-authority register before backend/UI enforcement so the team can review which source states may feed execution marks, forward marks, terminal marks, realized P&L, model-estimated values, proxy context, and future copilot warnings.

Rationale:

• Gordon should be able to review the source policy before the system turns model outputs into stronger warnings or recommendations.
• Missing, pending, stale, unsupported, estimated, proxy, and not-entitled states are materially different and should not collapse into a single no-data bucket.
• Estimated/model values may be useful for exploration, but they must not be labelled as realized P&L or included in sourced aggregates by default.

Implementation implications:

• Use the register as the source of truth for future backend quality-state enums and UI disclosures.
• Keep backend enforcement and UI gate changes deferred until Gordon has reviewed the strategy and source policy.
• Preserve current behavior that excludes unavailable/pending economics from aggregates and keeps realized P&L unavailable until authoritative source approval.

2026-05-11: Regime-Aware Trade Copilot Direction

Status: Accepted as planning direction

Linear context: ENG-5237, ENG-5236

Decision: Keep the current dashboard as the reliable measurement and market-context backbone, and extend it toward a regime-aware trade copilot that can evaluate whether proposed trades and restructurings fit the current spot-vol regime, surface shape, conditional distribution, portfolio exposure, liquidity, and source-quality state.

Rationale:

• Gordon validated the existing dashboard as useful as a consolidated display and audit tool.
• The most important new market thesis is that BTC may be shifting locally from spot up / vol down to spot up / vol up, especially in the front month.
• The risk reversal may still reflect the old regime, creating a possible alpha or accident-avoidance opportunity where the smile underprices upside-vol repricing.
• The first useful copilot behavior is not automatic trade selection; it is warning when a proposed adjustment adds exposure in a part of the surface where regime evidence says short vol is dangerous.

Implementation implications:

• Create and maintain a sponsor-facing strategy document with strategic pillars and decision points.
• Prioritize daily measurement reliability, derivative identity/proxy mapping, and source-quality reason codes before strong trade recommendations.
• Segment regime detection by tenor, moneyness, delta bucket, and smile segment rather than only global spot-vol correlation.
• Turn conditional-vs-vanilla density/CDF gaps into explicit decision statements only when stationarity, source quality, and confidence gates support them.
• Keep Model Lab central for risk-free rate, density method, lookback windows, stationarity thresholds, KS p-value settings, blend weights, and candidate filters.

2026-05-07: Performance Headline And Proxy Liquidity Boundary

Status: Accepted

Linear context: ENG-5061

Decision: Present the Performance opportunity read as a percentage of supportive rows among decisive rows, not as a 0-100 grade. Label liquidity coverage as BTC proxy liquidity when it is sourced from BTC market context, and do not treat it as MSTR/COIN execution-quality liquidity.

Current headline formula:

supportive among decisive rows = supportive / (supportive + opposing)

Current grouping:

Rationale:

• The old average alignment score looked like a performance grade and was easy to misread as "we did badly."
• Mixed/no-edge rows are analytically important, but including them in the decisive numerator/denominator obscures whether decisive context was supportive or opposing.
• BTC proxy liquidity can describe broad crypto-vol market backdrop, but it cannot validate whether a specific MSTR/COIN option trade had good execution liquidity.
• Execution-quality liquidity requires traded-contract OI, volume, bid, ask, mid/spread, and quote age at Alpha execution time.

Implementation implications:

• Performance should show the supportive/mixed/opposing distribution next to the headline.
• Missing execution quotes, forward marks, and authoritative realized P&L remain unavailable rather than zero.
• Business users should review Trade Performance Business Discussion Guide and Opportunity Alignment Rules before signing off on thresholds or treating the page as an execution/outcome report.

2026-05-04: Trade Performance Analytics Context Split

Status: Accepted

Linear context: ENG-4940, ENG-4943

Decision: For Alpha trades currently synced from IMST and ICOI, use BTC-linked dashboard context for opportunity and regime attribution, while using the actual TradFi option underlyings for execution and outcome marks.

Current mapping:

Rationale:

• MSTR and COIN option trades are crypto-equity proxy trades, so BTC-linked volatility, gamma, VRP, term-structure, and stationarity context are the relevant dashboard opportunity backdrop.
• Execution quality and mark-to-market outcomes must use the actual traded option market. A MSTR option fill should be benchmarked against MSTR option bid/ask/mark data, not BTC or Deribit option quotes.
• Separating opportunity context from execution/outcome quote source avoids mixing economic interpretation with instrument-level valuation.

Implementation implications:

• Trade-time context enrichment should store both market_proxy and quote_underlying.
• Opportunity alignment can ask: did the trade align with BTC-linked dashboard conditions?
• Execution benchmarking can ask: was the MSTR/COIN option fill good versus the MSTR/COIN option market?
• Outcome attribution can ask: did trades perform under the BTC-linked regime in which they were entered, using sourced marks from the actual traded instruments?
• The UI must label this split clearly so users do not assume MSTR/COIN marks came from BTC option data.

Note for Gordon discussion on 2026-05-06:

• Confirm that BTC is the right regime/opportunity proxy for both MSTR and COIN option trades.
• Confirm whether future non-BTC proxy portfolios need a different mapping, for example ETH-linked or SOL-linked context.

2026-05-04: Expiry Outcome Source Boundary

Status: Accepted

Linear context: ENG-4943

Decision: Expiry outcomes should remain unavailable unless the dashboard can source a defensible expiry quote, close, settlement, or equivalent authoritative mark. Do not use model-estimated intrinsic value as an authoritative expiry P&L.

Rationale:

• This is a trading dashboard, so a precise-looking expiry P&L must be backed by sourced market or settlement data.
• Model-estimated intrinsic value can be useful as a labelled estimate, but it should not be presented as the actual outcome.
• Missing expiry data is safer than showing a guessed value that could be interpreted as verified P&L.

Implementation implications:

• Outcome horizons such as 1d, 7d, and 30d may use sourced forward quote marks when available.
• Expiry outcome should use an explicit quality state such as sourced_settlement, sourced_quote, model_estimated, or unavailable.
• The default displayed expiry P&L should be blank/unavailable unless the source quality is authoritative.
• If model-estimated intrinsic value is added later, it must be visually and API-labelled as an estimate, not as actual realized P&L.

Note for Gordon discussion on 2026-05-06:

• Confirm the preferred authoritative expiry source for MSTR/COIN options: exchange settlement, closing quote, official OCC/market close, or Alpha-provided realized outcome if available.
• Confirm whether a separately labelled model estimate is useful for operators or whether it should be omitted entirely.

2026-05-06: Alpha Trade-Level Smile Richness Boundary

Status: Accepted

Linear context: ENG-4978

Decision: Keep smile_rich_cheap intentionally unavailable for Alpha MSTR/COIN trade-performance rows until the dashboard has MSTR/COIN smile data or an approved BTC-proxy smile methodology.

Rationale:

• BTC smile is a contract-surface shape read for BTC options. It is useful on the market analytics screens.
• Alpha trade rows currently represent MSTR and COIN options. Stamping BTC smile richness onto those rows would imply contract-level precision the dashboard does not have.
• Opportunity alignment can still use BTC DVol, VRP, gamma, stationarity, and term-structure proxy context because those are broad regime reads. Smile richness is more strike/DTE/delta-specific and should remain unsourced at trade level.
• Showing not_sourced is more accurate than filling a guessed rich or cheap label.

Implementation implications:

• trade_market_context.smile_rich_cheap remains null for Alpha proxy trades.
• Performance source-group quality labels Smile as intentionally not sourced rather than silently broken.
• Opportunity alignment continues to score from the available signal set and reduces confidence for missing signal coverage.

2026-05-06: Historical Vol Metrics Backfill Boundary

Status: Accepted

Linear context: ENG-4975

Decision: The daily vol_metrics snapshot path may persist current-day live Amberdata values, but historical backfills must not write those live values into old dates unless the source endpoint is explicitly historical/as-of for the target date.

Rationale:

• Several Amberdata scalar metric endpoints return latest values unless queried through a true historical/as-of path.
• Copying current DVol, VRP, IV, or RV into historical trade dates creates precise-looking but wrong opportunity context.
• Historical gaps should remain partial/unavailable until a defensible as-of source is implemented.

Implementation implications:

• Current/future scheduled snapshots continue through the normal daily snapshot path.
• Non-current vol_metrics snapshot requests are skipped instead of fabricating historical rows.
• Alpha context backfill may improve from newly persisted current/future rows, but old historical gaps remain explicit unless sourced.

2026-05-06: Trade Performance Data Gap Interpretation

Status: Accepted

Linear context: ENG-4964, ENG-4965

Decision: Missing MSTR/COIN execution quotes and forward marks must remain explicit source-quality states. Do not display missing execution quality as zero slippage, and do not display missing forward marks as zero P&L.

Rationale:

• Zero slippage means a fill exactly matched a defensible execution-time benchmark mid.
• Zero P&L means the entry and sourced forward mark produced a breakeven outcome.
• Unavailable means the dashboard does not have a defensible source input. It is a data state, not an economic result.

Implementation implications:

• Execution benchmark backfills may persist unavailable rows when no fresh sourced bid/ask/mid exists.
• Forward outcome backfills may persist pending or unavailable rows when horizons have not matured or marks are missing.
• Performance aggregates must exclude unavailable/pending economics from average P&L, hit rate, fill-vs-mid, and spread-capture calculations.
• Operators should read Trade Performance Data Gaps before treating Performance as an execution or outcome report.