| name | quant-alpha-research |
| description | Run adversarial, leakage-safe quantitative alpha research on OHLCV or related market data. Use when creating a research cycle, auditing price data, defining causal features and targets, registering hypotheses, testing predictive information, validating a trading candidate chronologically, modeling fees and execution, preserving failed experiments, or deciding whether an effect is rejected, informative, paper-tradeable, or a candidate executable alpha. |
Quant Alpha Research
Find conditional information that can survive unseen time and realistic
execution. Do not promise profit or optimize toward a pretty backtest. Make
economic usability a hard gate: an effect must survive costs, delay, uncertainty,
concentration, and alternative explanations.
Resolve paths safely
Treat the directory containing this SKILL.md as <skill-dir>. Resolve every
script, asset, and reference relative to <skill-dir>, never relative to the
user's current working directory. Store paths inside cycle manifests relative to
the cycle directory. Reject references to _archive_do_not_use.
Read code-architecture.md before adding or
changing code. Put CLI parsing in actions, orchestration in routines,
quantitative computation in quant-core, optional frameworks in quant-ml,
chart contracts in plotting packages, and report behavior in UI/app packages.
Begin every task
- Read research-mandate.md.
- Read data-and-labels.md before touching data,
features, targets, splits, or execution clocks.
- Read workflow.md before creating or continuing a
full research cycle.
- State the current stage, frozen information boundary, and next falsifiable
decision.
Do not begin alpha testing before a documented data audit. Do not open a locked
holdout before freezing the full selection and execution procedure.
Create a registered research cycle
Run:
python3 <skill-dir>/scripts/new_cycle.py \
--cycle-id 20260713-btcusdt-1m-conditional-alpha \
--asset BTCUSDT \
--venue binance-spot \
--interval 1m \
--objective "Test whether causal OHLCV states change executable future outcomes" \
--data-path data/btcusdt-1m.csv \
--fee-bps-per-side 1.0 \
--spread-bps-round-trip 0.5 \
--slippage-bps-round-trip 0.5
The tool creates a manifest, data card, target matrix, hypothesis and experiment
ledgers, broad experiment matrix, decision record, sealed-holdout marker, and
separate experiment/result directories. It predeclares return, direction,
future-range, and adverse-excursion targets across coarse horizons.
Treat generated placeholders as unresolved research obligations, not boilerplate
to ignore.
Audit OHLCV data
Run:
python3 <skill-dir>/scripts/audit_ohlcv.py <csv-path> \
--interval 1m \
--interval-label 1m \
--timestamp-semantics open_time \
--cycle <cycle-dir> \
--output-dir <cycle-dir>/results/data-audit
Use the generated JSON and Markdown to fill DATA_CARD.md. The optional cycle
argument verifies the audited path, records its hash and audit status, and does
not approve or repair it. Document every repair proposal, affected row count,
and possible research impact. Do not let a script silently mutate source data.
Build the initial past-only feature matrix after accepting the audit:
python3 <skill-dir>/scripts/build_features.py <audited-ohlcv.csv> \
--output <experiment-dir>/results/features.csv \
--lookbacks 5,15,60
Use the output as a causal baseline feature set: normalized candle geometry,
trailing return, path efficiency, relative volume, range position, and realized
volatility. Add new features through the modular indicator layer, not inside the
CLI.
Freeze the economic and information contracts
Before feature testing, fill cycle.json with:
- bar timestamp semantics and feature cutoff;
- decision, order, execution, and exit clocks;
- chronological train, validation, walk-forward, purge, embargo, and locked
holdout boundaries;
- fee, spread, slippage, funding, borrow, impact, and estimation-margin inputs;
- target horizons and overlap structure;
- total variant cap, per-family cap, and applicable hypothesis families.
Use a conservative default: observe completed bar t, decide afterward, and
execute no earlier than bar t+1 open. If using another convention, prove it is
executable.
Register hypotheses before results
Read experiment-catalog.md to cover broad,
logically distinct families. Read feature-library.md
only after selecting a family.
Register each hypothesis with:
python3 <skill-dir>/scripts/new_experiment.py \
--cycle <cycle-dir> \
--id B01-momentum-coarse \
--name "Coarse continuation" \
--observable-state "Past-only return over 5, 15, and 60 bars" \
--future-outcome "Executable log return at registered horizons" \
--expected-relationship "Larger positive formation return shifts future return upward" \
--falsification-test "Reject if signs reverse across ordinary folds or net effect is below costs" \
--promotion-criteria "Same sign in at least 70% of test folds, smooth neighboring horizons, adequate support, and net-positive lower confidence bound" \
--variant-cap 12
Keep every run in EXPERIMENT_LEDGER.csv, including failed variants. Never
replace a registered hypothesis with the explanation suggested by its result.
Search broadly before refining
Use model-free conditional profiles first:
- Establish unconditional drift, distribution, dependence, seasonality, and
volatility structure.
- Use training-defined bins to measure count, mean, median, quantiles, hit rate,
tails, uncertainty, and turnover implications.
- Cover every applicable family without giving any family more than 20% of the
initial variant budget.
- Compare every candidate with unconditional, random, drift, previous-sign,
simple threshold, and simple linear baselines.
- Promote only broad, stable regions with adequate support and economically
meaningful effect size.
Read experiment-template.md for the full
experiment contract.
Translate information into executable value
Separate four possible products:
- directional entry or exit information;
- trade filtering and adverse-selection avoidance;
- volatility/range forecasts for sizing;
- conditional risk forecasts for exposure reduction.
Estimate conditional outcome distributions before defining a strategy. Require:
expected gross edge > fee + spread + slippage + funding/borrow + impact + safety margin
Attribute apparent profit to drift, beta, volatility exposure, leverage, tail
risk, and selection before calling it alpha. Report gross and net effects, long
and short results, exposure, turnover, capacity assumptions, adverse excursion,
and concentration.
For a trade-level CSV containing gross_return_bps and side, run:
python3 <skill-dir>/scripts/evaluate_trades.py <trades.csv> \
--output-dir <experiment-dir>/results/trade-evaluation \
--fee-bps-per-side 1.0 \
--spread-bps-round-trip 0.5 \
--slippage-bps-round-trip 0.5 \
--impact-bps-per-trade 0.2 \
--safety-margin-bps 0.5
Use its gross/net expectancy, dependence-aware interval, long/short split,
drawdown, concentration, break-even cost capacity, and cost stress as economic
evidence. Do not let trade-level profitability bypass selection or leakage
validation.
Validate adversarially
Read validation-and-costs.md. Apply:
- chronological walk-forward selection;
- purge and embargo for overlapping labels;
- train-only normalization, feature selection, thresholds, regimes, and models;
- dependence-aware intervals and effective observation counts;
- explicit multiple-testing correction against the complete ledger;
- nearby-parameter, time, regime, direction, delay, cost, outlier, and
leave-one-period-out stress tests;
- simple-baseline and negative-control comparisons.
Use visual-guide.md to show support, uncertainty,
parameter plateaus, fold dispersion, cost-delay sensitivity, drawdown, and
concentration. A graph must expose how a candidate fails, not only how its best
region performs.
Validate the cycle at any point:
python3 <skill-dir>/scripts/validate_cycle.py <cycle-dir>
python3 <skill-dir>/scripts/validate_cycle.py <cycle-dir> --strict
The validator checks required artifacts, relative paths, costs, target diversity,
purge/embargo, sealed-holdout integrity, family coverage, variant budgets,
registered experiments, archive contamination, and the single-decision rule.
Open the holdout once
Open the locked holdout only after:
- data transformations, features, targets, parameters, policy, costs, and
reporting are frozen;
- ledgers match all work performed;
- promotion criteria are already written;
- the cycle validator has no errors.
Set cycle.json status to frozen, set search_budget.stage to
locked_evaluation, and run:
python3 <skill-dir>/scripts/open_holdout.py <cycle-dir> --procedure-frozen
The command refuses incomplete cycles, hashes the frozen procedure, records the
opening event, and removes the sealed marker. If the holdout fails, record
failure. Do not tune on it or quietly create a new test from the remaining tail.
Close the cycle
Produce the mandate's data card, information boundary, target matrix, hypothesis
ledger, broad experiment matrix, candidate cards, rejected ideas, and ranked
next tests. Select exactly one decision in DECISION.md:
- stop;
- gather more data;
- change target or horizon;
- investigate one candidate;
- run a locked confirmation;
- begin paper trading.
Use only these evidence classifications: rejected, inconclusive, interesting but
not tradable, predictive but economically weak, conditionally useful, or
candidate executable alpha. Never call an effect proven.
Load references only when needed
External sources generate tests; they do not transfer empirical validity to the
current asset, venue, period, or execution model.
