Quant Research Agent Spec v2 (Retail Trader)

A repo-native, agent-agnostic research system for building, testing, and deploying retail-trading strategies with: exploration speed + validation rigor + paranoia against artifacts + self-updating method knowledge.

This is written for a retail trader running strategies on bar/tick data via a broker/platform (e.g., spread betting/CFD/futures/spot), where the “house” isn’t your problem — fills, costs, slippage, gaps, leverage, margin, and survivability are.

0) Desired outcomes

The agent must reliably:

Generate creative strategy ideas (mechanisms, not “try 50 indicators”).
Test ideas fast without drowning in process.
Prevent silent invalid work (wrong session times, missing data, leakage, join explosions).
Produce evidence-backed decisions: discard / iterate / paper trade / go live.
Accumulate an internal playbook of methods used, where/why, and how well they performed in your environment.
Ship retail-realistic results: costs, slippage, latency proxy, gap risk, margin, position sizing, risk of ruin.
Include monitoring + degradation plan for anything that goes live.

1) Operating modes (two-speed system)

Mode A — Exploration (fast, permissive)

Purpose: quickly discover and prune hypotheses.

Allowed:

messy iteration
approximations
pivoting mid-stream

Required (minimum hard gate):

Data Window Validity Gate (Section 3.1)
Minimum Exploration Logging (Section 5.2)

Output: shortlist of candidate hypotheses + next tests with expected information gain.

Mode B — Validation (slow, strict)

Purpose: determine if a strategy is robust enough to deploy.

Required gates:

Data validity + leakage + baseline discipline + OOS + costs + robustness + tail risk + confounding checks.

Output: pass/fail decision with confidence label and deployment recommendation.

Rule: any “this works” claim requires Validation mode.

2) Decision types (retail trading lens)

Every research cycle must end with a clear decision:

Kill Evidence suggests artifact, non-robust, or dominated by baseline.
Iterate Promising but missing a key validation gate or needs targeted improvement.
Paper trade / forward test Backtest passes key gates; now test live conditions (real spreads, slippage, platform behavior).
Go live (small) Paper/forward test stable; deploy with strict risk caps and monitoring.
Scale Stable live performance over defined period; loosen caps cautiously.

Each decision must state:

what evidence drove it
what would change the decision (explicit falsifier)

3) Hard gates (generic invariants)

3.1 Data Window Validity Gate (mandatory in both modes)

Before trusting any computed feature or result over a window (session, first 30m, rolling N bars, etc.), the agent must prove:

Presence

observation count is non-zero and within plausible bounds.

Coverage

timestamps span intended interval; timezone declared.
for “session-based” logic: show empirical first/last observed timestamps per session window.

Non-degeneracy

detect missingness coerced to zeros/constants:
- % zero values
- number of unique values
- variance / IQR
- “constant by session” flags

Hard stop conditions

% windows with 0 observations > tolerance ⇒ experiment marked INVALID (not “failed”; invalid).
% constant/zero outputs > threshold ⇒ investigate missingness/coercion and window definition.

Fallback behavior

If session definition is wrong/ambiguous: infer session boundaries empirically from data (e.g., first bar after a gap) and record the inference as an assumption to validate.
If the market is 24/5 or instruments differ (FX vs equities): treat “session” as “your chosen trading day boundary” and validate that boundary by observed bar distribution.

This catches your “session starts 22:00, no bars, features 0.00” problem immediately.

3.2 Leakage Gate (mandatory before any predictability claim)

Before claiming a signal predicts anything:

feature timestamps must be strictly prior to label horizon
rolling computations must be aligned correctly (no forward shift)
any joins must be checked for future contamination

Hard stop if leakage is plausible and untested.

Fallback

If uncertain: run a “leakage trap” test:
- shift labels forward/back and confirm performance collapses when it should
- run permutation/shuffle labels (Section 3.7)

3.3 Baseline Discipline Gate (mandatory in Validation)

Every strategy result must be compared against:

Always include

Do nothing (flat / no trade)
Naive baseline (random entry with same trade frequency, or constant signal)
Simple domain heuristic baseline (choose appropriate):
- ATR-based stops, fixed RR, simple trend filter, simple mean reversion band, etc.

Strong baseline policy

If you have an existing “best known” strategy in your own repo, include it as Strong Baseline.
If none exists, state “No strong baseline available” and treat results as lower confidence.

Hard stop

If you can’t beat a reasonable baseline after costs, don’t progress to production-grade claims.

3.4 OOS / Walk-forward Gate (mandatory in Validation)

At minimum:

rolling walk-forward evaluation or strict time split
no random shuffles for time series unless justified

Fallback

If data is short: use conservative splits and add heavier robustness checks (Section 3.6) + paper trade earlier.

3.5 Cost & Execution Realism Gate (mandatory in Validation)

Retail reality must be included:

spread + commission + financing where applicable
slippage proxy (at least: adverse slippage proportional to volatility/spread)
gaps and stop behavior (especially for equities/indices around opens/news)

Sensitivity curve

show performance across a range of costs/slippage assumptions (not one number)

Fallback

If execution model is unknown: use pessimistic assumptions until paper trading provides real fill stats.

3.6 Robustness Gate (mandatory in Validation)

Must pass at least two of:

walk-forward stability
regime split (volatility buckets, trend/mean-reversion regimes, day-of-week, hour-of-day)
parameter perturbation (±20% of key thresholds)
subsampling (different instruments, different years, different sessions)
bootstrap of trades (if appropriate)

Hard stop

if performance depends on one small period, one instrument, or one parameter sweet spot, it’s not robust.

3.7 Tail Risk & Concentration Gate (mandatory in Validation)

Retail strategies die from tails and leverage.

Required:

max drawdown (or your chosen risk metric)
worst 1% / 5% outcomes (trade and period)
contribution concentration:
- top N trades contribution to total PnL
stress windows:
- high-volatility periods, major news days (if available), session opens

Hard stop

if returns are dominated by a handful of outliers without a plausible mechanism and without surviving stress tests.

3.8 Confounding / Proxy Validity Gate (mandatory in Validation)

Ask: is the “signal” just a proxy for:

time-of-day
volatility expansion/contraction
spread widening
session open effects
selection bias (only trades in easy conditions)

At least one mitigation test when results look strong:

stratify by the suspected confounder (e.g., vol bucket) and retest
matched sample comparison (same volatility, different signal)
include control features / remove suspect feature and see if performance collapses

3.9 Anti-hallucination Gate (recommended in Validation)

Run at least one:

permutation test / shuffled labels
random signal with same trade frequency
“placebo horizon” test (wrong horizon should not work)

This detects pipelines that “manufacture alpha.”

4) Agent roles (single agent, sequential hats)

Each cycle produces outputs from:

Research Lead

objective, decision, metrics, baselines, constraints, hypothesis shortlist

Skeptic / Auditor

runs gates, tries to falsify, lists “ways wrong”
flags confounds and tail risks

Implementer

minimal code + reproducibility metadata
instrumentation and artifacts

Analyst

reports results + breakdowns + confidence
recommends next step and why

5) The Quant Research Loop

5.1 Validation loop (full)

Frame decision & metrics
Hypothesize mechanisms (3–10) with falsifiers
Pre-register plan (plan.md)
Run pre-flight gates (data validity, leakage traps if needed)
Implement minimal test
Run tests
Analyze results (including tail risk, confounds, breakdowns)
Decide (kill/iterate/paper/go live/scale)
Write everything down + update methods registry

5.2 Exploration loop (minimum viable)

For Exploration mode, keep it light:

hypothesis
data scope (instrument/timeframe/window)
Data Window Validity output (counts + coverage)
quick result snapshot (vs trivial baseline)
next step

If a candidate looks promising → promote into Validation mode and create plan.md.

6) Artifacts and repo structure (system of record)

6.1 Current state

research/CURRENT.md

current objective & constraints (retail: capital, max leverage, max DD tolerance)
hypotheses (ranked)
active experiment(s)
baseline list (including any strong baseline)
known confounds & risks
mode status (Exploration / Validation)

6.2 Experiments

research/experiments/EXP-YYYYMMDD-NN/

plan.md (required for Validation)
config.json (params, dataset ids, instruments, horizon, seeds)
sanity.md (Data Window Validity output)
results.md
decision.md
RUN_METADATA.json (mandatory; Section 6.4)
artifacts/ (parquet/csv outputs, model files)
plots/ (optional)
code_ref.txt (script path + commit hash)

6.3 Logs

research/DECISIONS.md (append-only)

one line per decision referencing experiment id

research/ASSUMPTIONS.md

each assumption has:
- statement
- scope
- risk level
- validation status (untested/weak/strong)
- planned validation

6.4 Reproducibility metadata (mandatory)

RUN_METADATA.json includes:

git commit hash
command executed
environment fingerprint (uv lock hash / pip freeze hash / container digest)
dataset snapshot identifiers (partition date, file hash, query hash)
start/end time
machine info (optional)

7) Method & Skills Map (self-updating with evidence)

7.1 Method catalog

research/methods/METHODS.yml

Each method card:

method_id, name, tags
problem_signals (triggers)
how_to (steps)
assumptions
failure_modes
alternatives
canonical_keywords
status: experimental / preferred / caution / avoid
evidence_refs (auto appended)

7.2 Usage log (append-only “context history”)

research/methods/USAGE_LOG.ndjson

Each usage record:

timestamp
experiment_id
method_id
why_used (trigger + rationale)
how_used (params + notes)
data_scope (instrument/timeframe/window/dataset id)
outcome:
- win / neutral / loss / invalid
- delta_metric vs baseline
- confidence (low/med/high) + reason
- robustness_passed (which gates)
links to artifacts

7.3 Scorecard rollup (generated)

research/methods/METHOD_SCORECARD.csv

uses
invalid rate
median delta vs baseline
robustness pass rate
tail-risk pass rate
last used
recommended_state

7.4 Method lifecycle management (prevents bloat)

New methods start experimental.
Promote to preferred only after:
- ≥3 uses across different windows/instruments
- ≥2 passes through Validation gates (incl. costs + OOS)
- low invalid rate
Demote to avoid if:
- repeated leakage issues
- high invalid rate
- consistently dominated by simpler method
Expiry:
- experimental methods expire after N weeks/months unused unless revived with new evidence.
Using “avoid” requires explicit justification in plan.md.

8) Just-in-time web research (cross-domain learning)

When to search (tight rule)

Search external papers/methods only if at least one:

unknown pattern / no known tool in your method catalog
high-stakes method choice (time or risk)
promising but fragile result needs established robustness approach
you need canonical terminology to proceed

How to ingest external knowledge

create/update a method card with:
- source note (paper/blog/title/date)
- what it claims
- how it could fail in retail trading
- minimal validation test to run next
treat it as a hypothesis until validated and logged in usage history

9) Reporting requirements (retail-relevant)

Every results.md in Validation includes:

Executive summary

what was tested, why, verdict

Metrics vs baselines

include after-cost metrics
include trade frequency / holding time

Breakdowns

year/month
volatility bucket
hour-of-day / session segment (if relevant)
instrument (if multi-instrument)

Tail & concentration

max drawdown
worst percentile outcomes
top-N trade contribution

Confounding checks

what might it be proxying?
mitigation test results

Ways I could be wrong

data validity
leakage
execution realism
multiple testing risk
non-stationarity

Confidence label Exploratory / Promising / Robust / Production-grade …and which gates were passed.
Next step

specific planned experiment(s) or deployment step

10) Deployment pathway (retail)

Paper trade / forward test spec

If “paper trade”:

define broker/platform environment
collect real spreads/slippage
log discrepancies vs backtest assumptions
minimum observation period and stop conditions

Go live (small) spec

If “go live small”:

position sizing rules (fixed fractional, vol targeting, etc.)
max daily loss / max DD / max leverage caps
hard disable conditions (performance drift thresholds, spread regime changes)

Scale spec

Only scale if:

live performance consistent with forward-test expectations
drift metrics stable (Section 11)
tails acceptable under live fills

11) Monitoring & degradation plan (required for production-grade)

For any strategy considered deployable:

feature drift monitoring (distribution changes)
performance drift monitoring (rolling metrics, hit rate, expectancy)
execution drift (spread/slippage vs assumptions)
alert thresholds and rollback plan
revalidation schedule (weekly/monthly depending on frequency)

Decision trigger examples

if slippage exceeds assumed median by X% for Y days → reduce size or halt
if drawdown exceeds modeled stress bound → halt and revalidate
if signal becomes confounded (e.g., only works in one vol regime) → halt

12) Budget & stop policy (prevents infinite wandering)

Per objective:

max experiments per week (or per cycle)
max hypotheses explored before forced reframe
stop criteria:
- “If no candidate beats baseline after costs across OOS after N attempts → pivot mechanism class.”

Exploration is free-form, not infinite.

13) Minimal enforced rules (the smallest set that makes this work)

If you enforce only these, the system still holds:

Data window validity proof before trusting any computed result.
No predictability claims before leakage checks.
No “it works” before strong baselines + OOS + after-cost metrics.
Tail risk + concentration must be reported before deployment decisions.
Every method used must be logged; method scorecard drives future choices.
Every decision must be written, with falsifiers and next steps.
Production-grade requires a monitoring/rollback plan.

14) Practical fallbacks (common retail scenarios)

Scenario: session boundaries unclear / instruments differ

Don’t hardcode “session start.”
Infer empirically from data gaps and bar distributions; record boundary; validate.

Scenario: data quality shaky (missing bars, spikes)

Add “data quality filter” stage:
- remove clearly bad ticks/bars
- enforce monotonic timestamps
- log how much data removed

Scenario: limited history

Reduce claims; move earlier to paper trading.
Emphasize robustness checks and pessimistic execution assumptions.

Scenario: strategy looks too good

Increase paranoia:
- stronger baselines
- permutation tests
- stricter OOS
- confounding mitigation tests If it survives, confidence increases legitimately.

If you want this to become your actual Cursor setup next: I can output (in the exact files you’d drop into a repo) the templates for CURRENT.md, plan.md, sanity.md, results.md, decision.md, plus starter METHODS.yml (retail-focused methods) and the scoring rules for METHOD_SCORECARD.

methods/METHODS.yml

version: 1
purpose: >
  Seed method and skill catalog for a retail-trader quant research agent.
  Methods are used via triggers, logged in USAGE_LOG.ndjson, and scored in METHOD_SCORECARD.csv.
  New methods must be added with evidence refs and lifecycle state (experimental/preferred/caution/avoid).

method_cards:

  # =========================
  # A) DATA VALIDITY & PIPELINE INTEGRITY (NON-NEGOTIABLE)
  # =========================

  - method_id: data_window_validity_gate
    name: Data Window Validity Gate
    tags: [data_integrity, sanity_checks, time_series, mandatory]
    problem_signals:
      - "Any feature/result computed over a time window (session/rolling/first N minutes)"
      - "Unexpectedly many zeros, constants, or NaNs"
      - "Sparse results or suspiciously clean outputs"
    how_to:
      - "Compute observation counts per window (mean/p1/p50/p99) and % windows with 0 obs."
      - "Compute timestamp coverage: min/max timestamps within each window; validate timezone."
      - "Check degeneracy: % zeros, #unique, variance/IQR per feature."
      - "Hard stop if %0-obs windows exceeds tolerance; mark experiment INVALID."
    assumptions:
      - "Timestamp fields are accurate and comparable after timezone normalization."
      - "Window definition is meaningful for the instrument/data source."
    failure_modes:
      - "Missing data coerced to 0.00 or forward-filled silently."
      - "Wrong session boundary or timezone causes empty windows."
      - "Filtering/join errors drop rows without obvious exceptions."
    alternatives:
      - "None (mandatory invariant)."
    canonical_keywords: ["coverage check", "bar count sanity", "timestamp range validation", "degenerate feature detection"]
    status: preferred

  - method_id: join_integrity_check
    name: Join Integrity & Row Explosion Check
    tags: [data_integrity, joins, sanity_checks]
    problem_signals:
      - "Any join between fact table and dimension/mapping tables"
      - "Metric jumps unexpectedly after adding a join"
      - "Duplicates suspected (same timestamp/instrument repeated)"
    how_to:
      - "Before join: record rowcount and key uniqueness stats."
      - "After join: re-check rowcount and uniqueness; identify multiplicative blow-ups."
      - "Sample problematic keys and inspect join cardinality."
    assumptions:
      - "Join keys have stable semantics (not changing across time)."
    failure_modes:
      - "Many-to-many join duplicates rows."
      - "Key normalization (trim/upper) changes matching unexpectedly."
    alternatives:
      - "Pre-aggregate dimensions; enforce distinct keys; use validated mapping tables."
    canonical_keywords: ["row explosion", "many-to-many join", "duplicate amplification"]
    status: preferred

  - method_id: missingness_semantics
    name: Missingness Semantics (Missing ≠ Zero)
    tags: [data_integrity, preprocessing, sanity_checks]
    problem_signals:
      - "Features show large masses at 0"
      - "Market closed windows or sparse data feeds"
      - "Any imputation/defaulting behavior present"
    how_to:
      - "Explicitly represent missing as NaN/None, not numeric defaults."
      - "Track missingness rate per feature per window."
      - "Run sensitivity: treat missing as drop vs impute vs carry-forward and compare."
    assumptions:
      - "Downstream models can handle missingness appropriately."
    failure_modes:
      - "Default 0 turns 'no data' into a fake signal."
      - "Imputation leaks future info (e.g., forward-fill across gaps)."
    alternatives:
      - "Indicator flags for missingness + model that can use it."
    canonical_keywords: ["missing not zero", "imputation leakage", "missingness indicator"]
    status: preferred

  - method_id: timezone_and_calendar_validation
    name: Timezone & Calendar Validation
    tags: [data_integrity, time_series]
    problem_signals:
      - "Session boundaries, opens/closes, or intraday patterns matter"
      - "Data source unclear about timezone"
      - "Results differ across DST transitions"
    how_to:
      - "Normalize all timestamps to UTC for storage; convert only for reporting."
      - "Plot/summary bar counts by hour-of-day; detect dead zones."
      - "Check DST boundaries explicitly (before/after)."
    assumptions:
      - "Instrument trading schedule can vary (cash vs futures vs FX)."
    failure_modes:
      - "DST shift misaligns features/labels."
      - "Session definitions mismatched to data."
    alternatives:
      - "Empirically infer active trading hours from bar density."
    canonical_keywords: ["DST", "market hours validation", "UTC normalization", "session boundary inference"]
    status: preferred


  # =========================
  # B) LABELS, LEAKAGE & EVALUATION DISCIPLINE
  # =========================

  - method_id: label_definition_horizon_check
    name: Label Definition & Horizon Alignment
    tags: [leakage, labels, time_series, evaluation]
    problem_signals:
      - "Any predictive modeling or signal evaluation"
      - "Forward returns, event labels, barrier-based labels"
    how_to:
      - "Define label: horizon, entry price proxy, exit logic, and when label becomes known."
      - "Ensure features are computed strictly before the label start time."
      - "Check off-by-one: shift feature timestamps and verify no performance 'miracle'."
    assumptions:
      - "Execution proxy chosen is consistent with decision time."
    failure_modes:
      - "Feature uses future bar close when decision is at open."
      - "Label uses information unavailable at decision time."
    alternatives:
      - "Use event-driven labeling (triple barrier) with strict time cutoff."
    canonical_keywords: ["forward return leakage", "horizon alignment", "label availability"]
    status: preferred

  - method_id: leakage_trap_tests
    name: Leakage Trap Tests (Shifts & Placebos)
    tags: [leakage, evaluation, sanity_checks]
    problem_signals:
      - "Strategy performance seems too good"
      - "Complex feature pipelines"
      - "Any new join or aggregation step"
    how_to:
      - "Placebo horizon: evaluate at an intentionally wrong horizon; should not work."
      - "Shift labels forward/back; performance should degrade predictably."
      - "Shuffle labels (within blocks) for a permutation sanity check."
    assumptions:
      - "Placebo setup preserves pipeline structure without true signal."
    failure_modes:
      - "Pipeline manufactures signal from leakage or target encoding."
    alternatives:
      - "Purged CV + embargo (for ML); strict walk-forward for simpler strategies."
    canonical_keywords: ["placebo test", "label shuffle", "time shift leakage test"]
    status: preferred

  - method_id: baseline_discipline
    name: Baseline Discipline (Weak Baselines Forbidden)
    tags: [evaluation, baselines, mandatory]
    problem_signals:
      - "Any claim of improvement"
      - "Comparisons only against trivial baselines"
    how_to:
      - "Always include: do-nothing, random-frequency baseline, simple heuristic baseline."
      - "Include strong baseline if available (best known strategy/model)."
      - "Require after-cost baselines where relevant."
    assumptions:
      - "Baselines reflect realistic constraints (trade frequency, holding time)."
    failure_modes:
      - "Beating a strawman baseline creates false confidence."
    alternatives:
      - "Benchmark against your own last best validated strategy."
    canonical_keywords: ["strong baseline", "strawman baseline", "benchmark discipline"]
    status: preferred

  - method_id: walk_forward_evaluation
    name: Walk-Forward / Rolling Out-of-Sample Evaluation
    tags: [evaluation, time_series, robustness]
    problem_signals:
      - "Time-series prediction or strategy backtesting"
      - "Non-stationarity suspected"
    how_to:
      - "Define rolling train/validate/test windows."
      - "Report metrics per window and aggregated."
      - "Avoid random shuffles unless strictly justified."
    assumptions:
      - "Past resembles future enough for learning, but not identical."
    failure_modes:
      - "Single split hides instability."
    alternatives:
      - "Purged CV + embargo for ML on overlapping labels."
    canonical_keywords: ["walk-forward", "rolling OOS", "time split evaluation"]
    status: preferred


  # =========================
  # C) COSTS, EXECUTION, AND RETAIL REALISM
  # =========================

  - method_id: conservative_execution_model
    name: Conservative Execution Model (Retail)
    tags: [execution, costs, realism]
    problem_signals:
      - "Any strategy test intended to be deployable"
      - "Stops/limits, gaps, or session opens matter"
    how_to:
      - "Use bid/ask (or spread proxy) not mid for fills."
      - "Add slippage proxy: function of volatility and spread (pessimistic by default)."
      - "Model gaps: stop fills at next available price, not stop level."
      - "Include financing where applicable (CFD/spread bet)."
    assumptions:
      - "You can approximate spread and slippage from historical data or broker stats."
    failure_modes:
      - "Mid-price fill fantasy."
      - "Stops assumed perfect under gaps."
    alternatives:
      - "Paper trade to calibrate slippage/spread distributions."
    canonical_keywords: ["bid ask fill", "slippage model", "gap risk", "stop fill realism"]
    status: preferred

  - method_id: cost_sensitivity_curve
    name: Cost Sensitivity Curve
    tags: [execution, costs, robustness]
    problem_signals:
      - "Edge is small"
      - "Trade frequency high"
      - "Broker spread varies by session/volatility"
    how_to:
      - "Re-run metrics across a grid of cost/slippage assumptions."
      - "Plot performance vs costs; identify break-even."
      - "Promote only if edge survives realistic/pessimistic ranges."
    assumptions:
      - "Costs can be parameterized meaningfully."
    failure_modes:
      - "Edge disappears under small cost increase."
    alternatives:
      - "Reduce turnover, add filters, improve entry/exit timing."
    canonical_keywords: ["break-even costs", "slippage sensitivity", "spread sensitivity"]
    status: preferred

  - method_id: position_sizing_risk_caps
    name: Position Sizing & Risk Caps (Retail Survivability)
    tags: [risk, sizing, deployment]
    problem_signals:
      - "Leveraged products"
      - "Strategy has tail risk"
      - "Live deployment planning"
    how_to:
      - "Define max % capital at risk per trade/day."
      - "Use vol targeting or fixed-fractional sizing."
      - "Hard caps: max drawdown, max daily loss, max leverage."
      - "Simulate risk-of-ruin under pessimistic scenario."
    assumptions:
      - "Capital and leverage constraints are known."
    failure_modes:
      - "Backtest looks good but leverage kills it."
    alternatives:
      - "Reduce size; trade fewer instruments; add circuit breakers."
    canonical_keywords: ["risk of ruin", "vol targeting", "max daily loss", "circuit breaker"]
    status: preferred


  # =========================
  # D) STATISTICS & DIAGNOSTICS (RETAIL-RELEVANT)
  # =========================

  - method_id: distribution_and_tail_diagnostics
    name: Distribution & Tail Diagnostics
    tags: [statistics, tails, risk]
    problem_signals:
      - "PnL dominated by few trades"
      - "Large drawdowns"
      - "Fat-tail markets (indices, crypto)"
    how_to:
      - "Report max drawdown; worst 1%/5% periods/trades."
      - "Compute concentration: top N trades contribution to PnL."
      - "Compare median vs mean expectancy."
      - "Stress test high-volatility windows."
    assumptions:
      - "Sufficient sample size for tail estimates."
    failure_modes:
      - "Apparent edge is hidden short-vol or tail exposure."
    alternatives:
      - "Tail hedges, volatility filters, reduced leverage, wider stops."
    canonical_keywords: ["fat tails", "expectancy", "PnL concentration", "max drawdown"]
    status: preferred

  - method_id: regime_bucket_analysis
    name: Regime / Bucket Analysis
    tags: [robustness, non_stationarity, diagnostics]
    problem_signals:
      - "Performance unstable across time"
      - "Different behavior in high vs low vol"
    how_to:
      - "Bucket by volatility, trend strength, hour-of-day, day-of-week."
      - "Report metrics per bucket."
      - "Identify where strategy fails and why."
    assumptions:
      - "Bucketing variables are not leaky."
    failure_modes:
      - "Strategy only works in one regime (overfit)."
    alternatives:
      - "Add regime filter; ensemble strategies; dynamic parameterization."
    canonical_keywords: ["vol buckets", "regime split", "conditioned performance"]
    status: preferred

  - method_id: parameter_perturbation
    name: Parameter Perturbation (±20% Rule)
    tags: [robustness, overfitting]
    problem_signals:
      - "Strategy depends on threshold/indicator parameter"
      - "Sharp optimum in backtest"
    how_to:
      - "Perturb key thresholds ±20%."
      - "Re-evaluate metrics and stability."
      - "Reject strategies with knife-edge tuning."
    assumptions:
      - "Parameters are meaningful and not scale-dependent without normalization."
    failure_modes:
      - "Fragile edge from curve fitting."
    alternatives:
      - "Normalize features; simplify rules; use robust defaults."
    canonical_keywords: ["knife-edge parameter", "curve fit detection", "sensitivity test"]
    status: preferred

  - method_id: multiple_testing_awareness
    name: Multiple Testing Awareness (P-hacking Control)
    tags: [statistics, evaluation, process]
    problem_signals:
      - "Many features/variants tried"
      - "Frequent restarts after bad results"
    how_to:
      - "Pre-register plan for Validation experiments."
      - "Use strict OOS holdout and avoid reusing it repeatedly."
      - "Track number of variants tested; downgrade confidence accordingly."
    assumptions:
      - "You can maintain an experiment registry."
    failure_modes:
      - "One of many trials looks good by chance."
    alternatives:
      - "Nested validation; fresh unseen period; paper trading."
    canonical_keywords: ["p-hacking", "multiple comparisons", "holdout exhaustion"]
    status: preferred


  # =========================
  # E) STRATEGY PATTERN TOOLKIT (RETAIL-FRIENDLY STARTERS)
  # =========================

  - method_id: volatility_targeted_stops
    name: Volatility-Targeted Stops/Targets (ATR/Range Based)
    tags: [strategy_pattern, execution, risk]
    problem_signals:
      - "Stop-outs increase during volatility spikes"
      - "Fixed stops underperform across regimes"
    how_to:
      - "Compute ATR or session range proxy."
      - "Set stop/target distances as k * volatility."
      - "Validate across vol buckets; check tail risk."
    assumptions:
      - "Volatility measure is computed without leakage."
    failure_modes:
      - "Vol proxy lags; widening stops increases tail risk."
    alternatives:
      - "Regime-based sizing; time stops; partial exits."
    canonical_keywords: ["ATR stop", "range stop", "vol scaling"]
    status: experimental

  - method_id: simple_trend_filter
    name: Simple Trend Filter (e.g., MA slope / breakout confirmation)
    tags: [strategy_pattern, regime]
    problem_signals:
      - "Mean-reversion fails in trending regimes"
      - "Chop vs trend separation needed"
    how_to:
      - "Define a simple trend measure."
      - "Trade only when trend conditions meet criteria."
      - "Test for confounding by volatility/time-of-day."
    assumptions:
      - "Trend measure isn’t just volatility proxy."
    failure_modes:
      - "Late entry; whipsaw in transitions."
    alternatives:
      - "Two-regime system; breakout-only; MR-only."
    canonical_keywords: ["trend regime filter", "MA slope", "breakout confirmation"]
    status: experimental

  - method_id: mean_reversion_bands
    name: Mean Reversion Bands (z-score / Bollinger-like)
    tags: [strategy_pattern, time_series]
    problem_signals:
      - "Price oscillates with stable range"
      - "Reversion opportunities in low trend regimes"
    how_to:
      - "Define rolling mean and deviation (robust if heavy-tailed)."
      - "Enter at extremes; exit at mean or time stop."
      - "Validate across regimes; check tail and gap risk."
    assumptions:
      - "Reversion behavior exists in selected market/timeframe."
    failure_modes:
      - "Trend regime breaks bands; large drawdowns."
    alternatives:
      - "Trend filter + MR; volatility filter; adaptive bands."
    canonical_keywords: ["z-score reversion", "bands", "bollinger style"]
    status: experimental


  # =========================
  # F) WEB RESEARCH / CROSS-DOMAIN INGESTION (PROCESS TOOL)
  # =========================

  - method_id: just_in_time_literature_search
    name: Just-in-Time Literature / Technique Search
    tags: [meta, research, web_search]
    problem_signals:
      - "Unfamiliar pattern; no method card fits"
      - "Promising but fragile results need robust evaluation method"
      - "Need canonical terminology to proceed"
    how_to:
      - "Search for canonical terms + 'time series finance' + 'robust' + failure modes."
      - "Extract 2–3 candidate methods; choose simplest viable."
      - "Create/Update method card with source note and minimal validation experiment."
      - "Treat external knowledge as hypothesis until validated."
    assumptions:
      - "Sources are relevant and reputable."
    failure_modes:
      - "Cargo-culting methods without validation."
    alternatives:
      - "Rely on existing preferred methods; paper trade earlier."
    canonical_keywords: ["literature search", "robust backtest method", "cross-domain technique"]
    status: preferred

version: 1
purpose: >
  Expanded seed quant/statistics method catalog (hedge-fund grade).
  Designed to be used and updated under the Quant Research Loop spec.
  Each method must be logged in USAGE_LOG.ndjson with outcomes and scored.

method_cards:

  # =========================
  # G) FOUNDATIONAL STATISTICS & INFERENCE (DEPENDENCE-AWARE)
  # =========================

  - method_id: eda_distribution_diagnostics
    name: EDA: Distribution Diagnostics & Robust Summaries
    tags: [statistics, eda, robustness]
    problem_signals:
      - "Any new dataset/feature/label"
      - "Unexpected outliers or heavy tails"
    how_to:
      - "Report robust location/scale: median, IQR, MAD; compare to mean/std."
      - "Check skew/kurtosis; QQ-plot conceptually; tail mass via quantiles."
      - "Winsorize/sanitize for exploratory plots; never hide raw distribution in validation."
      - "Check stability over time: rolling medians/IQR."
    assumptions:
      - "Data scale is meaningful; units consistent."
    failure_modes:
      - "Relying on mean/std under heavy tails misleads."
      - "Outliers are data errors vs true tail events (must distinguish)."
    alternatives:
      - "Robust transforms (log, rank, z-score with MAD)."
    canonical_keywords: ["MAD", "IQR", "robust statistics", "heavy tails", "distribution shift"]
    status: preferred

  - method_id: autocorrelation_dependence_checks
    name: Dependence Checks: ACF/PACF, Heteroskedasticity, Serial Correlation
    tags: [time_series, statistics, diagnostics]
    problem_signals:
      - "Time-series data (returns, volatility, spreads)"
      - "Model residuals look structured"
    how_to:
      - "Compute/check autocorrelation (ACF) and partial autocorrelation (PACF)."
      - "Test/diagnose heteroskedasticity patterns (vol clustering)."
      - "For regressions: use HAC/Newey-West style reasoning for dependent errors."
    assumptions:
      - "Sampling frequency and timestamps are correct."
    failure_modes:
      - "Treating dependent observations as IID inflates significance."
    alternatives:
      - "Block bootstrap; time-series CV; explicit volatility models."
    canonical_keywords: ["ACF", "PACF", "Newey-West", "serial correlation", "volatility clustering"]
    status: preferred

  - method_id: block_bootstrap_inference
    name: Block Bootstrap / Stationary Bootstrap for Time-Series Inference
    tags: [statistics, inference, time_series]
    problem_signals:
      - "Need confidence intervals under autocorrelation"
      - "PnL/trade outcomes dependent"
    how_to:
      - "Use block bootstrap over time blocks (choose block length via dependence scale)."
      - "Estimate CI for mean return, Sharpe proxy, hit rate, etc."
      - "Compare to naive IID CI; if they differ materially, use bootstrap results."
    assumptions:
      - "Dependence is local enough for blocks to capture."
    failure_modes:
      - "Wrong block length gives misleading CI."
      - "Structural breaks invalidate stationarity assumptions."
    alternatives:
      - "Subsample by regimes; Bayesian models; robust stress tests."
    canonical_keywords: ["block bootstrap", "stationary bootstrap", "dependent data CI"]
    status: preferred

  - method_id: multiple_hypothesis_control
    name: Multiple Hypothesis Control (Reality Check Discipline)
    tags: [statistics, evaluation, process]
    problem_signals:
      - "Large feature sweeps"
      - "Many strategy variants tested"
    how_to:
      - "Track number of trials; downgrade confidence as trials grow."
      - "Use strict untouched OOS period; avoid reusing holdout."
      - "Use permutation/placebo tests; consider FDR intuition for feature screens."
    assumptions:
      - "You can maintain an experiment registry and keep a clean holdout."
    failure_modes:
      - "False discovery via p-hacking."
    alternatives:
      - "Nested CV; fresh forward period; paper trading."
    canonical_keywords: ["FDR", "multiple comparisons", "false discovery", "holdout exhaustion"]
    status: preferred


  # =========================
  # H) TIME-SERIES FORECASTING / SIGNAL RESEARCH (HEDGE FUND BASICS)
  # =========================

  - method_id: return_predictability_regression
    name: Predictability via Regression (with Proper Controls)
    tags: [time_series, regression, signals]
    problem_signals:
      - "Testing if a feature predicts returns"
      - "Need interpretability of signal direction/strength"
    how_to:
      - "Set up regression of forward returns on features (+ controls like volatility, time-of-day)."
      - "Use robust standard errors / HAC logic."
      - "Check stability of coefficients across time/regimes."
      - "Validate out-of-sample; avoid in-sample storytelling."
    assumptions:
      - "Linear approximation is informative; controls reduce confounding."
    failure_modes:
      - "Spurious regression due to non-stationarity."
      - "Coefficient stability illusion due to regime shifts."
    alternatives:
      - "Nonlinear models; rank-based methods; conditional tests."
    canonical_keywords: ["predictive regression", "HAC errors", "coefficient stability", "spurious regression"]
    status: preferred

  - method_id: feature_screening_ic_rank
    name: Feature Screening: Information Coefficient (IC) / Rank IC
    tags: [signals, feature_engineering, cross_section, time_series]
    problem_signals:
      - "Many candidate features"
      - "Need fast triage before modeling"
    how_to:
      - "Compute correlation between feature and forward return (Pearson + Spearman)."
      - "Do it by bucket/time/regime; report IC mean, IC t-stat (dependence-aware)."
      - "Prefer rank IC for heavy tails."
    assumptions:
      - "Feature and label alignment correct; no leakage."
    failure_modes:
      - "IC inflated by microstructure noise or confounds."
      - "IC not monetizable after costs."
    alternatives:
      - "Simple strategy backtest with costs; mutual information with caution."
    canonical_keywords: ["IC", "rank IC", "factor screening", "signal decay"]
    status: preferred

  - method_id: signal_decay_horizon_analysis
    name: Signal Decay & Horizon Analysis
    tags: [signals, time_series, diagnostics]
    problem_signals:
      - "Signal exists but unclear holding period"
      - "Edge disappears at chosen horizon"
    how_to:
      - "Evaluate predictive power across multiple horizons (e.g., 1, 3, 6, 12 bars)."
      - "Plot decay curve: performance vs horizon."
      - "Choose horizon where net-of-cost edge maximizes risk-adjusted return."
    assumptions:
      - "Costs and execution scale reasonably with horizon."
    failure_modes:
      - "Horizon mining (multiple testing) without holdout."
    alternatives:
      - "Event-driven exits; adaptive horizon by regime."
    canonical_keywords: ["signal decay", "holding period selection", "horizon sweep"]
    status: preferred

  - method_id: volatility_modeling_garch_family
    name: Volatility Modeling (ARCH/GARCH intuition + regimes)
    tags: [time_series, volatility, risk]
    problem_signals:
      - "Vol clustering impacts stops/sizing"
      - "Need risk forecasts"
    how_to:
      - "Model volatility dynamics with rolling realized vol baseline."
      - "Optionally test GARCH-type forecasts; validate out-of-sample."
      - "Use volatility buckets/regimes for strategy conditioning."
    assumptions:
      - "Volatility is forecastable to some extent; regime persistence exists."
    failure_modes:
      - "Overfitting GARCH parameters; ignoring structural breaks."
    alternatives:
      - "EWMA vol; HAR-RV style realized volatility; simple bucket regimes."
    canonical_keywords: ["GARCH", "EWMA volatility", "realized volatility", "vol regime"]
    status: experimental

  - method_id: change_point_detection
    name: Change-Point Detection / Structural Breaks
    tags: [time_series, non_stationarity, regimes]
    problem_signals:
      - "Model performance shifts abruptly"
      - "Feature distribution drift"
    how_to:
      - "Use rolling metrics to detect step changes."
      - "Apply change-point methods (conceptually: detect shifts in mean/variance)."
      - "Re-evaluate strategy per regime; consider retrain/recalibrate."
    assumptions:
      - "Breaks are detectable with available sample size."
    failure_modes:
      - "Overreacting to noise; false break detection."
    alternatives:
      - "Regime bucketing by vol/trend; robust rolling windows."
    canonical_keywords: ["structural break", "change point", "regime shift detection"]
    status: preferred


  # =========================
  # I) CROSS-SECTIONAL / FACTOR QUANT (HEDGE FUND CORE)
  # =========================

  - method_id: cross_sectional_factor_model
    name: Cross-Sectional Factor Model Basics (Ranking, Neutralization)
    tags: [cross_section, factors, portfolio_construction]
    problem_signals:
      - "Trading multiple instruments"
      - "Need to avoid unintended exposures (beta, sector, size)"
    how_to:
      - "Build signals as ranks/z-scores across instruments."
      - "Neutralize exposures to known risk factors (market beta, sector buckets where applicable)."
      - "Evaluate factor returns and stability."
    assumptions:
      - "Cross-sectional universe consistent; survivorship handled."
    failure_modes:
      - "Hidden factor bets drive returns, not the signal."
    alternatives:
      - "Single-instrument strategies; hedged pair trades."
    canonical_keywords: ["factor neutralization", "cross-sectional ranking", "beta neutral", "sector neutral"]
    status: experimental

  - method_id: information_ratio_and_turnover
    name: Information Ratio vs Turnover Tradeoff
    tags: [portfolio_construction, costs, evaluation]
    problem_signals:
      - "High turnover signals"
      - "Net edge sensitive to costs"
    how_to:
      - "Compute turnover; estimate cost drag."
      - "Optimize signal smoothing/holding to maximize net IR."
      - "Report IR per cost assumption."
    assumptions:
      - "Turnover proxy maps to costs reasonably."
    failure_modes:
      - "Over-smoothing kills edge; under-smoothing burns costs."
    alternatives:
      - "Event-based trading; lower frequency horizon."
    canonical_keywords: ["information ratio", "turnover", "net alpha", "trading frictions"]
    status: preferred


  # =========================
  # J) RISK MODELS, PORTFOLIO & BET SIZING (HEDGE FUND EXPECTATIONS)
  # =========================

  - method_id: risk_decomposition_exposures
    name: Risk Decomposition & Exposure Attribution
    tags: [risk, portfolio, diagnostics]
    problem_signals:
      - "Multi-asset trading"
      - "Unexpected drawdowns"
    how_to:
      - "Decompose PnL by instrument, regime, time-of-day, direction."
      - "Compute exposures to market direction and volatility proxies."
      - "Identify concentration and hidden bets."
    assumptions:
      - "Attribution dimensions are correctly defined."
    failure_modes:
      - "Attribution misses true driver due to wrong bucketing."
    alternatives:
      - "Scenario stress tests; factor model attribution."
    canonical_keywords: ["PnL attribution", "risk decomposition", "hidden exposures"]
    status: preferred

  - method_id: kelly_and_fractional_kelly
    name: Kelly Criterion (and Fractional Kelly) as Upper Bound
    tags: [risk, sizing, decision_theory]
    problem_signals:
      - "Need sizing guidance from edge/variance estimates"
      - "Strategy has measurable expectancy"
    how_to:
      - "Estimate edge and variance conservatively; compute Kelly fraction."
      - "Use fractional Kelly (e.g., 0.1–0.25 Kelly) due to estimation error."
      - "Stress test under worse-than-estimated edge."
    assumptions:
      - "Edge and variance estimates are stable enough; usually they aren’t."
    failure_modes:
      - "Overbetting due to estimation error (common)."
    alternatives:
      - "Fixed fractional risk; vol targeting; drawdown-based caps."
    canonical_keywords: ["Kelly sizing", "fractional Kelly", "estimation error"]
    status: experimental

  - method_id: scenario_stress_testing
    name: Scenario & Stress Testing
    tags: [risk, tails, robustness]
    problem_signals:
      - "Tail losses possible (gaps, opens, news)"
      - "Leverage used"
    how_to:
      - "Re-run strategy on stress windows (high vol, crisis periods, big gaps)."
      - "Apply synthetic shocks: spread widening, slippage increase, gap events."
      - "Check risk of ruin and max drawdown under stress."
    assumptions:
      - "Stress scenarios are relevant to traded instrument."
    failure_modes:
      - "Stress not representative; false comfort."
    alternatives:
      - "Paper trade during volatile periods; reduce leverage."
    canonical_keywords: ["stress test", "scenario analysis", "gap stress", "spread widening"]
    status: preferred


  # =========================
  # K) MICROSTRUCTURE AWARENESS (EVEN FOR BAR DATA)
  # =========================

  - method_id: microstructure_noise_awareness
    name: Microstructure Noise Awareness (Even on 1–5 min bars)
    tags: [microstructure, execution, diagnostics]
    problem_signals:
      - "Very short horizons"
      - "Signal disappears with small cost increase"
      - "Performance concentrated at session opens/closes"
    how_to:
      - "Check sensitivity to using bid/ask vs mid proxies."
      - "Evaluate signal after excluding first/last X minutes."
      - "Downsample frequency and see if edge persists."
    assumptions:
      - "Microstructure effects are non-negligible at tested horizons."
    failure_modes:
      - "Signal is just spread capture illusion or open auction artifact."
    alternatives:
      - "Longer horizons; more conservative fills; avoid open/close windows."
    canonical_keywords: ["microstructure noise", "open/close effect", "bid-ask bounce"]
    status: preferred


  # =========================
  # L) MACHINE LEARNING (ONLY THE PARTS YOU NEED, DONE PROPERLY)
  # =========================

  - method_id: time_series_ml_splitting
    name: Time-Series ML Splitting (Purged CV / Embargo Concept)
    tags: [ml, evaluation, leakage]
    problem_signals:
      - "Overlapping labels (e.g., forward returns with overlap)"
      - "ML models on time-series"
    how_to:
      - "Use time-based splits; purge overlapping periods between train/test."
      - "Add embargo buffer if labels overlap."
      - "Validate stability across folds/windows."
    assumptions:
      - "Overlap structure is known."
    failure_modes:
      - "Leakage via overlapping labels; inflated performance."
    alternatives:
      - "Simpler models; event-based labeling to reduce overlap."
    canonical_keywords: ["purged CV", "embargo", "overlapping labels leakage"]
    status: preferred

  - method_id: calibration_and_proper_scoring
    name: Calibration & Proper Scoring (When Predicting Probabilities)
    tags: [ml, statistics, evaluation]
    problem_signals:
      - "Predicting probabilities of up/down or event occurrence"
      - "Threshold-based trading from probabilities"
    how_to:
      - "Evaluate calibration (reliability curve concept)."
      - "Use proper scoring rules (log loss, Brier)."
      - "Check that better score translates to better trading outcomes after costs."
    assumptions:
      - "Probability outputs are meaningful; often they aren’t without calibration."
    failure_modes:
      - "Good classifier metrics but poor trading PnL (thresholding mismatch)."
    alternatives:
      - "Directly optimize trading objective; rank-based decisions."
    canonical_keywords: ["calibration", "Brier score", "log loss", "reliability curve"]
    status: experimental


  # =========================
  # M) META: RESEARCH PROCESS / KNOWLEDGE MANAGEMENT (FROM SPEC)
  # =========================

  - method_id: method_registry_usage_logging
    name: Method Registry + Usage Logging (Evidence-Backed Learning)
    tags: [meta, process, knowledge_management, mandatory]
    problem_signals:
      - "Any method used in an experiment"
      - "Any new technique discovered"
    how_to:
      - "Ensure method card exists/updated."
      - "Append a USAGE_LOG record with why/how/outcome."
      - "Update scorecard rollup; adjust method lifecycle state if warranted."
    assumptions:
      - "Logs remain append-only; scorecard generated deterministically."
    failure_modes:
      - "Knowledge base becomes vibes; no evidence linking to outcomes."
    alternatives:
      - "None (core to system learning)."
    canonical_keywords: ["method evidence", "usage log", "scorecard", "playbook evolution"]
    status: preferred
  # =========================
  # N) CROSS-DOMAIN: POKER SKILLS APPLIED TO TRADING
  # =========================

  - method_id: ev_thinking_expected_value
    name: EV Thinking (Expected Value Over Outcome)
    tags: [poker, decision_theory, process, meta]
    problem_signals:
      - "Judging a strategy based on a small sample of wins/losses"
      - "Strong emotional response to recent outcomes"
      - "Changing rules after a few bad trades"
    how_to:
      - "Separate decision quality from outcome: evaluate trades by expected value given information at entry."
      - "Use a pre-defined edge estimate (even rough) + cost model + risk to compute expected value per trade."
      - "Track EV proxy per trade alongside realized PnL; review divergence as variance, not proof."
    assumptions:
      - "You can approximate EV inputs (hit rate, payoff, costs) even if noisy."
    failure_modes:
      - "Outcome bias: quitting good strategy after a losing streak."
      - "Storytelling: attributing wins to skill and losses to bad luck selectively."
    alternatives:
      - "Forward testing with fixed rules; block bootstrap CI for expectancy."
    canonical_keywords: ["outcome bias", "expected value", "decision quality", "variance vs edge"]
    status: preferred

  - method_id: bankroll_management_risk_of_ruin
    name: Bankroll Management (Risk of Ruin, Not Max Return)
    tags: [poker, risk, sizing, deployment]
    problem_signals:
      - "Leveraged trading where a few losses can blow the account"
      - "Increasing size after wins (heater) or after losses (chasing)"
      - "High-vol strategies with fat tails"
    how_to:
      - "Define bankroll (capital available for strategy) separate from total net worth."
      - "Set max risk per trade/day/week; enforce hard stop-loss rules."
      - "Simulate risk-of-ruin under pessimistic edge/variance assumptions."
      - "Use fractional Kelly only as an upper bound; default to conservative fixed-fractional sizing."
    assumptions:
      - "Edge and variance can be approximated conservatively."
    failure_modes:
      - "Overbetting due to overconfidence / estimation error."
      - "Hidden tail risk causes rare but fatal loss."
    alternatives:
      - "Vol targeting; drawdown-based de-leveraging; circuit breakers."
    canonical_keywords: ["bankroll", "risk of ruin", "fractional Kelly", "table stakes"]
    status: preferred

  - method_id: variance_and_sample_size_discipline
    name: Variance & Sample Size Discipline (Downswings Happen)
    tags: [poker, statistics, evaluation]
    problem_signals:
      - "Interpreting short backtests as proof"
      - "Frequent strategy switching"
      - "Confusing noise with signal"
    how_to:
      - "Estimate variance of outcomes and required sample size for confidence (rough is fine)."
      - "Use block bootstrap / time-based subsampling to get realistic uncertainty."
      - "Set a minimum sample threshold before concluding 'dead' or 'works'."
      - "Maintain a 'confidence label' and downgrade when sample is small or trials are many."
    assumptions:
      - "Outcomes are variable and non-IID; uncertainty must reflect this."
    failure_modes:
      - "Overreacting to noise (tilting strategy selection)."
      - "False discovery from repeated testing."
    alternatives:
      - "Paper trade; strict walk-forward; strong baselines."
    canonical_keywords: ["downswing", "variance", "sample size", "confidence intervals"]
    status: preferred

  - method_id: game_selection_and_edge_hunting
    name: Game Selection (Choose Easier Games / Higher Edge Environments)
    tags: [poker, regimes, strategy_selection]
    problem_signals:
      - "Strategy only works in certain conditions"
      - "Costs/spreads widen in some sessions"
      - "Low-liquidity periods cause slippage"
    how_to:
      - "Treat markets/regimes like poker tables: some are tougher (efficient) and some softer (inefficient)."
      - "Define 'playability filters' (volatility, spread, liquidity proxy, session window)."
      - "Trade only when conditions match where edge historically exists."
      - "Validate filters aren’t just cherry-picking (use OOS and confounding checks)."
    assumptions:
      - "Edge is regime-dependent; you can identify regimes with non-leaky proxies."
    failure_modes:
      - "Filter overfits past conditions; disappears live."
      - "Filter is proxy for lookahead or data artifacts."
    alternatives:
      - "Broader strategy with robust risk controls; longer horizons."
    canonical_keywords: ["game selection", "table selection", "regime filter", "playability"]
    status: preferred

  - method_id: exploitative_vs_gto_tradeoff
    name: Exploitative vs Balanced Strategy (GTO Analogy)
    tags: [poker, strategy_design, robustness]
    problem_signals:
      - "Considering aggressive edge capture that may not generalize"
      - "Strategy depends on specific market behavior"
      - "Live performance differs from backtest"
    how_to:
      - "Balanced strategy (GTO-like): robust across opponents/regimes, lower peak edge."
      - "Exploitative strategy: higher edge in a specific regime but can break when regime shifts."
      - "Decide explicitly which you are building; apply stricter robustness for exploitative strategies."
      - "If exploitative: define regime detector + kill-switch + monitoring thresholds."
    assumptions:
      - "Market changes; opponents adapt; regimes shift."
    failure_modes:
      - "Over-optimization to historical regime; collapses live."
    alternatives:
      - "Ensemble of smaller edges; diversified strategies; slower horizons."
    canonical_keywords: ["GTO vs exploit", "robustness", "regime shift", "adaptation"]
    status: preferred

  - method_id: range_thinking_and_scenario_planning
    name: Range Thinking (Scenario Sets, Not Point Forecasts)
    tags: [poker, probabilistic_thinking, risk]
    problem_signals:
      - "Overconfidence in a single forecast/path"
      - "Ignoring tails (gaps, news)"
      - "Trading around events"
    how_to:
      - "Represent uncertainty as a distribution/range: best case, base case, worst case."
      - "Plan actions for each scenario (size, stop, hedge, no-trade)."
      - "Use stress windows and synthetic shocks to approximate worst-case."
      - "Make 'what will change my mind' explicit before entry."
    assumptions:
      - "Uncertainty is large; tails matter."
    failure_modes:
      - "Point-estimate overconfidence; underestimating tail risk."
    alternatives:
      - "Strict risk caps; avoid event windows; options hedges (if available)."
    canonical_keywords: ["range", "scenarios", "tail planning", "what changes my mind"]
    status: preferred

  - method_id: info_value_and_cost_of_observation
    name: Information Value (Pay for Information Only if It Changes Action)
    tags: [poker, decision_theory, research_process]
    problem_signals:
      - "Feature creep; adding complex indicators without clear purpose"
      - "Endless research without decisions"
    how_to:
      - "For each new feature/test, state: what decision will change if result is positive/negative?"
      - "Estimate expected information gain: probability it changes action × value of change."
      - "Prioritize experiments with high information gain per unit time."
    assumptions:
      - "Not all research is equally valuable; focus matters."
    failure_modes:
      - "Shiny object research; bloated models; wasted time."
    alternatives:
      - "Stick to a small set of hypotheses and validate deeply."
    canonical_keywords: ["information gain", "VOI", "research prioritization"]
    status: preferred

  - method_id: tilt_detection_and_circuit_breakers
    name: Tilt Detection & Circuit Breakers (Psychology as Risk Control)
    tags: [poker, psychology, risk_controls, deployment]
    problem_signals:
      - "Chasing losses, revenge trading"
      - "Breaking rules after drawdowns"
      - "Size increases driven by emotion"
    how_to:
      - "Define objective tilt triggers: consecutive losses, DD threshold, sleep deprivation proxy, missed stops."
      - "Implement circuit breakers: reduce size, pause trading, require review before resuming."
      - "Log rule breaks and treat them as system failures, not personal failures."
    assumptions:
      - "Human factors materially affect results in discretionary or semi-systematic trading."
    failure_modes:
      - "Ignoring tilt signals; compounding losses."
    alternatives:
      - "Fully systematic execution; smaller sizing; automation of risk limits."
    canonical_keywords: ["tilt", "circuit breaker", "revenge trading", "discipline automation"]
    status: preferred

  - method_id: hand_history_review_trade_review
    name: Hand History Review → Trade Review (Process Over Outcome)
    tags: [poker, review, process, improvement]
    problem_signals:
      - "Inconsistent execution"
      - "Unclear why strategy performance changed"
      - "Repeated mistakes"
    how_to:
      - "Maintain a structured trade journal: setup, rationale, entry conditions, exit, execution notes."
      - "Review like poker hands: categorize mistakes (entry, sizing, exit, rule breaks, execution)."
      - "Separate 'bad beat' (variance) from true mistake (process)."
      - "Feed findings into ASSUMPTIONS.md and method updates."
    assumptions:
      - "Logging is consistent and honest."
    failure_modes:
      - "Post-hoc rationalization; selective memory."
    alternatives:
      - "Automated tagging; periodic systematic audits; forward test logs."
    canonical_keywords: ["hand history", "trade journal", "review process", "mistake taxonomy"]
    status: preferred

FilesExpand file tree

quant_research_agent_loop_spec.md

Latest commit

History

quant_research_agent_loop_spec.md

File metadata and controls

Quant Research Agent Spec v2 (Retail Trader)

0) Desired outcomes

1) Operating modes (two-speed system)

Mode A — Exploration (fast, permissive)

Mode B — Validation (slow, strict)

2) Decision types (retail trading lens)

3) Hard gates (generic invariants)

3.1 Data Window Validity Gate (mandatory in both modes)

3.2 Leakage Gate (mandatory before any predictability claim)

3.3 Baseline Discipline Gate (mandatory in Validation)

3.4 OOS / Walk-forward Gate (mandatory in Validation)

3.5 Cost & Execution Realism Gate (mandatory in Validation)

3.6 Robustness Gate (mandatory in Validation)

3.7 Tail Risk & Concentration Gate (mandatory in Validation)

3.8 Confounding / Proxy Validity Gate (mandatory in Validation)

3.9 Anti-hallucination Gate (recommended in Validation)

4) Agent roles (single agent, sequential hats)

5) The Quant Research Loop

5.1 Validation loop (full)

5.2 Exploration loop (minimum viable)

6) Artifacts and repo structure (system of record)

6.1 Current state

6.2 Experiments

6.3 Logs

6.4 Reproducibility metadata (mandatory)

7) Method & Skills Map (self-updating with evidence)

7.1 Method catalog

7.2 Usage log (append-only “context history”)

7.3 Scorecard rollup (generated)

7.4 Method lifecycle management (prevents bloat)

8) Just-in-time web research (cross-domain learning)

When to search (tight rule)

How to ingest external knowledge

9) Reporting requirements (retail-relevant)

10) Deployment pathway (retail)

Paper trade / forward test spec

Go live (small) spec

Scale spec

11) Monitoring & degradation plan (required for production-grade)

12) Budget & stop policy (prevents infinite wandering)

13) Minimal enforced rules (the smallest set that makes this work)

14) Practical fallbacks (common retail scenarios)

Scenario: session boundaries unclear / instruments differ

Scenario: data quality shaky (missing bars, spikes)

Scenario: limited history

Scenario: strategy looks too good