QuantConnect Backtest Skill (Phase 3)

Purpose: Run backtests via QuantConnect API and make Phase 3 routing decisions.

Progressive Disclosure: This primer contains essentials only. Full details via qc_backtest.py --help.

---

When to Use This Skill

Load when:

• Running /qc-backtest command
• Uploading strategy files to QuantConnect
• Making Phase 3 routing decisions
• Debugging backtest API errors

Critical Rule: Always store results in PROJECT_LOGS/. See PROJECT_LOGS/README.md for naming.

---

Quick Start: Run a Backtest

Complete workflow (upload + run + evaluate):

python SCRIPTS/qc_backtest.py --run \
    --name "MomentumStrategy_20241110" \
    --file strategy.py \
    --output PROJECT_LOGS/backtest_result.json

What this does:

1. Creates/reuses QC project
2. Uploads strategy.py as Main.py
3. Compiles and runs backtest
4. Polls for completion (every 5s)
5. Saves results to JSON

Output (backtest_result.json):

{
  "project_id": 26135853,
  "backtest_id": "abc123def456",
  "performance": {
    "sharpe_ratio": 0.85,
    "max_drawdown": 0.22,
    "total_trades": 67,
    "win_rate": 0.42,
    "profit_factor": 1.8
  },
  "qc_url": "https://www.quantconnect.com/project/26135853"
}

---

Critical Metrics for Phase 3

Priority order (most important first):

1. sharpe_ratio - Risk-adjusted returns (target: > 0.7)
2. max_drawdown - Risk tolerance (target: < 0.30)
3. total_trades - Statistical significance (need: > 30)
4. win_rate - Overfitting signal (if > 0.75, ESCALATE)

See backtesting-analysis skill for metric interpretation.

---

Phase 3 Decision Integration

After backtest completes:

import json, sys
sys.path.insert(0, 'SCRIPTS')
from decision_logic import evaluate_backtest, route_decision

# Load results and state
with open('PROJECT_LOGS/backtest_result.json') as f:
    results = json.load(f)
with open('iteration_state.json') as f:
    state = json.load(f)

# Evaluate metrics
decision, reason, details = evaluate_backtest(
    results['performance'],
    state['thresholds']
)

# Route to next phase
routing = route_decision("backtest", decision, state['workflow']['iteration'])

print(f"Decision: {decision}")
print(f"Next Action: {routing['next_action']}")

Possible decisions:

• ABANDON_HYPOTHESIS → Start new hypothesis
• PROCEED_TO_OPTIMIZATION → Run /qc-optimize
• PROCEED_TO_VALIDATION → Skip optimize, run /qc-validate
• ESCALATE_TO_HUMAN → Manual review needed

---

Credentials Setup

Required in .env:

QC_USER_ID=your_user_id
QC_API_TOKEN=your_api_token

Get from: https://www.quantconnect.com → Account → API Access

Security: Never commit .env (already in .gitignore)

---

Common Errors & Quick Fixes

1. Strategy Never Trades (0 trades)

Fix: Simplify entry logic

# Start simple - just SMA crossover
if self.sma.IsReady and price > self.sma.Current.Value:
    self.SetHoldings(self.symbol, 1.0)

2. Object Reference Not Set

Fix: Add None checks

def OnData(self, data):
    if not data.ContainsKey(self.symbol):
        return
    if data[self.symbol] is None:
        return
    # Now safe

3. Indicator Not Ready

Fix: Check IsReady

if not self.sma.IsReady:
    return
# Now safe to use indicator

4. Backtest Timeout

Fix: Reduce date range or increase timeout

# Increase timeout
result = api.wait_for_backtest(project_id, backtest_id, timeout=1200)

# Or reduce date range to 3 years
self.SetStartDate(2022, 1, 1)

---

Best Practices

Trade Count Guidelines

Trades	Reliability	Action
0	N/A	Fix entry logic
1-20	Unreliable	Simplify or abandon
30-100	Acceptable	Proceed
100+	Good	High confidence

Date Range Guidelines

Range	Purpose
1-2 years	Initial testing (fast)
3-5 years	Full backtest (recommended)
< 1 year	Too short
> 10 years	Too long (regime changes)

Always Check for Errors

if 'error' in result:
    print(f"Backtest failed: {result['error']}")
    # ESCALATE or fix and retry

---

/qc-backtest Command Flow

The /qc-backtest command executes this sequence:

1. Read iteration_state.json (hypothesis, project_id)
2. Load this skill for patterns
3. Generate strategy.py from hypothesis
4. Run qc_backtest.py --run
5. Evaluate via decision_logic.py
6. Update iteration_state.json
7. Git commit with structured message

---

Reference Documentation (Progressive Disclosure)

Need detailed information? Access via --help:

python SCRIPTS/qc_backtest.py --help

Topics available in reference docs:

• Python API Integration (QuantConnectAPI class methods)
• Complete Backtest Results Structure (25+ metrics explained)
• Error Handling Guide (all errors with solutions)
• Complete Workflow Examples (end-to-end /qc-backtest flows)

Access specific topics:

python SCRIPTS/qc_backtest.py docs                  # List all
python SCRIPTS/qc_backtest.py docs api-integration  # Show specific

The primer above covers 85% of use cases. Use --help and docs for edge cases.

---

Related Skills

• quantconnect - Core strategy development (indicators, orders, risk)
• quantconnect-optimization - Phase 4 optimization (load AFTER backtest)
• quantconnect-validation - Phase 5 validation (walk-forward testing)
• decision-framework - Decision thresholds and routing logic
• backtesting-analysis - Metric interpretation and overfitting detection

---

Summary

This skill covers:

• ✅ Running backtests via QC API (qc_backtest.py --run)
• ✅ Phase 3 decision integration (decision_logic.py)
• ✅ Common errors & quick fixes
• ✅ Best practices (trade count, date ranges)

Load when: Running /qc-backtest or debugging backtest errors

Key Principle: Focus ONLY on backtesting. For optimization, load quantconnect-optimization skill.

---

Version: 2.0.0 (Progressive Disclosure) Last Updated: November 13, 2025 Lines: ~200 (was 458) Context Reduction: 56%