Track significant decisions to avoid re-debating. Move superseded decisions to
docs/archive/decisions-archive.md.
Date: 2025-02-04 | Status: Decided | Rationale: Full options support (CSPs, bear call spreads, covered calls), free paper trading, institutional-grade reliability, comprehensive market data included. Decision: Interactive Brokers (IBKR) Consequences: Need IBKR account, must run TWS or IB Gateway locally, more complex API integration than Alpaca.
Date: 2025-02-04 | Status: Decided | Rationale: Developer's strong Azure expertise, existing subscription, excellent .NET 8 support, serverless consumption model keeps costs low. Decision: Azure (Functions, Cosmos DB, Key Vault, Application Insights) Consequences: Monthly cost ~$20-40. Deployment via Bicep templates.
Date: 2025-02-04 | Status: Decided | Rationale: AI excels at nuanced analysis; rules are better for deterministic execution. Cost-effective at ~$15-50/month. Decision: Hybrid -- Claude AI for complex analysis (market regime, quality audits, candidate ranking), rule-based execution for orders, position sizing, stop losses, drift calculation, technical signals. Consequences: Two parallel paths in strategy evaluation, need fallback if Claude API fails.
Date: 2025-02-04 | Status: Decided | Rationale: Free, rich embed formatting, mobile notifications, simple webhook implementation. Decision: Discord webhooks Consequences: Human creates Discord server and webhook. Reports formatted as embeds.
Date: 2025-02-04 | Status: Decided | Rationale: Earnings timing is critical for avoiding costly surprises. Reliability worth $29/month. Decision: Polygon.io ($29/month) Consequences: Additional monthly cost, human signs up for Polygon.io account.
Date: 2025-02-04 | Status: Decided (implementation details TBD for Phase 2) | Rationale: Avoids additional costs, IBKR provides historical data, more control over methodology. Decision: Calculate IV Rank/Percentile from IBKR historical volatility data. Consequences: Need to implement calculation in Phase 2 (Week 13-14). Consider whether 1-year lookback is sufficient.
Date: 2025-02-04 | Status: Decided | Rationale: Quarterly frequency means latency acceptable. Claude can synthesize from multiple sources. Free (part of existing API budget). Decision: Claude web search during quarterly audits. Consequences: Quality data may not be 100% accurate -- human should verify. Audit reports should cite sources.
Date: 2025-02-04 | Status: Decided | Rationale: Feature branches isolate work, PR reviews ensure quality, human merge control prevents accidental deployments. Decision: Feature branches off main. All changes via PR. Human reviews and merges.
Date: 2025-02-04 | Status: Decided | Rationale: Conservative defaults with single equity/spread slightly raised for better position sizing. Decision:
| Parameter | Value |
|---|---|
| Per-trade risk | 0.4% |
| Daily stop | 2% |
| Weekly stop | 4% |
| Max single equity | 7.5% (raised from 5%) |
| Max single spread | 3% (raised from 2%) |
| Max gross leverage | 1.2x |
| Issuer cap | 10% |
| Category cap | 40% |
| Consequences: Tunable based on paper trading. Any changes require human approval. |
Date: 2025-02-04 | Status: Decided | Rationale: 12 weeks provides reasonable sample size. "OR S&P 500" allows validation even in down markets. Decision: Minimum 12 weeks. Profitable OR outperform S&P 500. Informational metrics: hit rate ≥ 45%, profit factor ≥ 1.3, max drawdown ≤ 15%. Consequences: Live trading earliest at Week 27. Human approval still required.
Date: 2026-02-09 | Status: Decided | Rationale: The 30% sleeve is focused on multi-leg options strategies (credit spreads, iron condors, CSPs, calendar spreads), not equity swing trades. Name should reflect actual strategy. Decision: Rename "Tactical Sleeve" to "Options Sleeve" throughout the codebase and docs. Consequences: Swing trades may become a future third sleeve. All code references updated.
Date: 2026-02-09 | Status: Decided | Rationale: Claude AI for regime detection is high value/low cost (~1 call/day, $2-5/mo). Screening/ranking candidates algorithmically is sufficient and avoids expensive per-candidate API calls. Decision: Claude AI limited to (1) daily market regime detection for options strategy selection, (2) quarterly income quality audits. All scanning, filtering, entry/exit, position sizing is algorithmic. Consequences: Total Claude API cost ~$2-10/month. System must have rule-only fallback if Claude unavailable.
Date: 2026-02-09 | Status: Decided | Rationale: Options are the core of the 30% sleeve, not an add-on. The system can't function without them. Phase 1 expanded from 8 to 10 weeks to accommodate. Decision: Credit spreads, iron condors, CSPs, and calendar spreads are Phase 1 MVP features. Phase 1 is 10 weeks. Consequences: More complex Phase 1, but the system is complete at end of Phase 1 (not partially functional).
Date: 2026-02-09 | Status: Decided | Rationale: Trading logic errors can lose real money. Non-critical code (notifications, reporting) doesn't need the same rigor. Decision: Rigorous testing (unit + integration + E2E) for trading-critical code (risk engine, order generation, position sizing, options calculations, IV rank). Standard testing (unit + integration) for everything else. Consequences: More test code for core trading logic. PR reviews required for trading-critical changes.
Date: 2026-02-09 | Status: Decided | Rationale: Keep operational costs sustainable. Estimate: Azure ~$10-30, Polygon.io $29, Claude API ~$2-10 = $40-65 total. Decision: Total monthly infrastructure cost must stay under $100. Track costs in logs with alerts if approaching ceiling. Consequences: Constrains AI usage (no expensive per-candidate analysis). May need to revisit if Polygon.io price increases.
Date: 2026-02-10 | Status: Decided | Rationale: Polygon.io is an external data source with its own HTTP client, rate limiting, and DTOs. Separate project keeps boundaries clean and allows independent testing.
Decision: TradingSystem.MarketData.Polygon as a separate project referencing Core.
Consequences: Additional project in solution. Clean dependency graph.
Date: 2026-02-10 | Status: Decided | Rationale: The service orchestrates broker calls with caching and regime detection — it's strategy-layer logic, not broker-layer.
Decision: CachingMarketDataService lives in TradingSystem.Strategies/Services/.
Consequences: Strategies project depends on Core interfaces only, not on IBKR directly.
Date: 2026-02-10 | Status: Decided | Rationale: IV history is expensive to fetch (1-year of daily data from IBKR). Caching to JSON avoids repeated API calls within the same trading day.
Decision: IV history persisted to JSON files per symbol, expires daily (stale if LastUpdated.Date < DateTime.Today).
Consequences: Requires TradingSystem.Storage dependency. First call each day is slow; subsequent calls are fast.
Date: 2026-02-10 | Status: Decided | Rationale: IBKR enforces 50 concurrent market data requests. Need headroom for other data needs. Decision: SemaphoreSlim(45) + 100ms delay between option snapshot requests. Consequences: Option chain retrieval is throttled but stays within IBKR limits. Full chain scan takes ~5-15 seconds depending on strike count.
Date: 2026-02-16 | Status: Decided | Rationale: Fixed 70/30 live allocation is too rigid. Sleeves should earn live capital through paper validation, and activation may be staged. Decision: Run both sleeves in paper validation. For live trading, activate one or both sleeves based on validation results. Human chooses final capital split at live transition. Expected deployable capital range is ~$100,000-$400,000 at decision time, with a minimum of $100,000 per active sleeve account. Consequences: System must provide sleeve-level readiness scorecards and allocation recommendations. Live path must not hard-code 70/30.
Date: 2026-02-16 | Status: Decided | Rationale: Capital movement decisions require human context (taxes, external cash needs, account constraints). Decision: System provides rebalance/transfer/withdrawal recommendations; human executes actual rebalancing and cash movement. For options sleeve, only free cash may be withdrawn (not cash reserved against open options positions). For income sleeve, cash withdrawals and occasional stock sales for withdrawals are allowed. Consequences: Reporting must include recommendation rationale and collateral-aware free-cash calculations. No automatic rebalance/capital-transfer execution.
Date: 2026-02-16 | Status: Decided | Rationale: Unknowns should not stall implementation, but dependent automation must pause for owner input at defined gates. Decision: Add explicit phase-gated checkpoints where Claude prompts the owner before proceeding with dependent automation (options lifecycle rules, recommendation format, paper validation criteria, live activation split, post-live tuning). Consequences: Roadmap/progress docs must maintain gate checkpoints. Claude should stop and prompt at each gate before advancing.
Date: 2026-02-16 | Status: Decided | Rationale: Platform cost control and brokerage activity costs behave differently and should be tracked separately. Decision: The <$100 monthly ceiling applies to platform costs (Azure + Polygon.io + Claude API). Brokerage commissions/fees are tracked and forecasted separately (conservative per contract-side model in reporting). Consequences: Reports must break out platform vs brokerage costs and include activity-based fee forecasts.
Date: 2026-02-16 | Status: Decided | Rationale: Week 8 wiring needs to land before Week 9 risk engine is complete. Scheduled pre-market runs should not hard-fail while IRiskManager is still missing.
Decision: DailyOrchestrator attempts options sleeve execution each pre-market run, but if required options dependencies cannot be resolved, it logs a warning and skips options execution for that run. Broker connect/disconnect handling remains explicit and safe.
Consequences: Timer runs stay healthy during staged integration and retain a defensive skip path for future DI regressions. Options sleeve runtime activation now depends on concrete registrations being present (including IRiskManager).
Date: 2026-02-16 | Status: Decided | Rationale: Stop logic based only on current unrealized P&L is too noisy and does not track true account drawdown over time.
Decision: RiskManager uses ISnapshotRepository baselines for daily/weekly P&L and computes high-water mark/current/max drawdown from persisted snapshots. Stop alerts are sent through IRiskAlertService only on state transitions (new trigger events) to avoid duplicate alert spam.
Consequences: Risk metrics now require snapshot persistence registration in DI. Discord webhook configuration is required for external alert delivery; without it alerts degrade to logs.
Blocking: Options roll/close timing | Needs: Paper trading results from Phase 1 Start with daily batch, assess need for intraday monitoring (especially near-expiry positions). Deferred to post-Phase 1.
Blocking: Strategy optimization | Needs: Decision on simple/medium/full scope Defer until post-live planning.
Blocking: Nothing (independent) | Needs: Options sleeve proven in live trading Potential future addition after options sleeve is validated.
Blocking: Final go-live recommendation logic | Needs: Numeric pass/fail criteria by sleeve Define exact per-sleeve thresholds (return/risk/consistency metrics) that qualify a sleeve for live activation.
Blocking: Live transition execution plan | Needs: Paper validation outputs + owner decision Select which sleeve(s) activate first and final initial capital split/account mapping at live transition.
Phase: 1 — Foundation (Week 9 complete, 418 tests passing)
- Weeks 1-8: IBKR connection, market data, storage, orders, income sleeve, option chains, IV rank, screening, Polygon.io calendar, multi-leg orders, options lifecycle, execution service, orchestration wiring, pre-market tests
- Week 9: Concrete
RiskManagerwith per-trade checks, stop-halt, position/cap enforcement, no-trade windows; snapshot-backed drawdown tracking; Discord stop alerts viaIRiskAlertService; Azure.Identity upgraded to 1.17.1
- Discord webhook: server/channel not yet created — needed for stop alerts to deliver externally
- Claude API key: needed for regime service integration (Week 10)
- Begin Claude regime service integration; prompt for Claude API key at gate
- Validate Discord webhook configuration so stop alerts can deliver
- Add low-friction smoke scenario in
TradingSystem.SmokeTestfor orchestrator path without live IBKR
| ID | Description | Impact | Logged |
|---|---|---|---|
| KD-001 | Discord webhook not configured | Stop alerts silently drop | 2026-02-16 |
| KD-002 | Claude API key not provisioned | Regime service integration blocked | 2026-02-16 |