Skip to main content
skill CX Codex

adaptive-wfo-epoch — Claude Code skill: per-fold epoch selection

adaptive-wfo-epoch sets how many epochs to train on each walk-forward fold, ranking candidates by walk-forward efficiency rather than one fixed number for the whole run.

MIT 146 installs ★ 3 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill adaptive-wfo-epoch -a claude-code
Open on GitHub

What adaptive-wfo-epoch does

The skill lays out a per-fold routine for choosing training epochs. Each candidate gets a short train-and-test pass; walk-forward efficiency, the out-of-sample Sharpe divided by the in-sample Sharpe, ranks them. A Pareto frontier then keeps the epochs that no other candidate beats on both efficiency and training cost, and the winner becomes the prior for the next fold.

It ships as a markdown reference plus a Python module adaptive_wfo_epoch. AWFESConfig.from_search_space builds a log-spaced candidate grid from your search bounds, and compute_efficient_frontier does the selection. Separate files cover the literature, configuration, guardrails and WFE aggregation. Thresholds: below 0.30 reject, 0.50 warns, 0.70 is the target; the in-sample Sharpe floor is 2/sqrt(n).

The skill trains nothing itself. Its tools are Read, Grep, Glob and Bash, so the training loop and the data stay yours. Watch the aggregation advice: under the null the efficiency ratio follows a Cauchy distribution with no mean, which is why median or pooled figures beat a plain average.

What it helps with

  • pick a training epoch count per fold instead of one global value
  • catch overfitting when out-of-sample Sharpe collapses against in-sample
  • build an efficient frontier of epochs against training time
  • carry the chosen epoch into the next fold as a prior
  • compare folds of different sizes with pooled or median WFE

Example prompts for the agent

  • Choose training epochs for each walk-forward fold using WFE
  • Build the efficient frontier over epoch candidates and carry the pick to the next fold
  • Check whether the epochs are overfit and aggregate WFE by median across folds

How to install adaptive-wfo-epoch

1Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill adaptive-wfo-epoch -a claude-code

2Manually: put the files in place

~/.claude/skills/adaptive-wfo-epoch/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/adaptive-wfo-epoch/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about adaptive-wfo-epoch

How do I install adaptive-wfo-epoch in Claude Code?

Run npx skills add terrylica/cc-skills --skill adaptive-wfo-epoch -a claude-code. The skill file then sits at ~/.claude/skills/adaptive-wfo-epoch/SKILL.md.

What does adaptive-wfo-epoch do?

It describes how to choose training epochs per walk-forward fold: candidates are scored by walk-forward efficiency, a Pareto frontier narrows them down, and the pick is reused as the prior on the next fold.

Is this early stopping?

No. Early stopping watches validation loss during training, while this approach evaluates discrete epoch candidates after a run. It is also not Bayesian optimization or nested cross-validation.

Source text

SKILL.md · MIT
---
name: adaptive-wfo-epoch
description: Adaptive epoch selection for Walk-Forward Optimization. TRIGGERS - WFO epoch, epoch selection, WFE optimization, overfitting epochs.
allowed-tools: Read, Grep, Glob, Bash
---

# Adaptive Walk-Forward Epoch Selection (AWFES)

Machine-readable reference for adaptive epoch selection within Walk-Forward Optimization (WFO). Optimizes training epochs per-fold using Walk-Forward Efficiency (WFE) as the objective.

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## When to Use This Skill

Use this skill when:

- Selecting optimal training epochs for ML models in WFO
- Avoiding overfitting via Walk-Forward Efficiency metrics
- Implementing per-fold adaptive epoch selection
- Computing efficient frontiers for epoch-performance trade-offs
- Carrying epoch priors across WFO folds

## Quick Start

```python
from adaptive_wfo_epoch import AWFESConfig, compute_efficient_frontier

# Generate epoch candidates from search bounds and granularity
config = AWFESConfig.from_search_space(
    min_epoch=100,
    max_epoch=2000,
    granularity=5,  # Number of frontier points
)
# config.epoch_configs → [100, 211, 447, 945, 2000] (log-spaced)

# Per-fold epoch sweep
for fold in wfo_folds:
    epoch_metrics = []
    for epoch in config.epoch_configs:
        is_sharpe, oos_sharpe = train_and_evaluate(fold, epochs=epoch)
        wfe = config.compute_wfe(is_sharpe, oos_sharpe, n_samples=len(fold.train))
        epoch_metrics.append({"epoch": epoch, "wfe": wfe, "is_sharpe": is_sharpe})

    # Select from efficient frontier
    selected_epoch = compute_efficient_frontier(epoch_metrics)

    # Carry forward to next fold as prior
    prior_epoch = selected_epoch
```

## Methodology Overview

### What This Is

Per-fold adaptive epoch selection where:

1. Train models across a range of epochs (e.g., 400, 800, 1000, 2000)
2. Compute WFE = OOS_Sharpe / IS_Sharpe for each epoch count
3. Find the "efficient frontier" - epochs maximizing WFE vs training cost
4. Select optimal epoch from frontier for OOS evaluation
5. Carry forward as prior for next fold

### What This Is NOT

- **NOT early stopping**: Early stopping monitors validation loss continuously; this evaluates discrete candidates post-hoc
- **NOT Bayesian optimization**: No surrogate model; direct evaluation of all candidates
- **NOT nested cross-validation**: Uses temporal WFO, not shuffled splits

## Academic Foundations

| Concept                     | Citation                       | Key Insight                                       |
| --------------------------- | ------------------------------ | ------------------------------------------------- |
| Walk-Forward Efficiency     | Pardo (1992, 2008)             | WFE = OOS_Return / IS_Return as robustness metric |
| Probabilistic Sharpe Ratio  | Bailey & López de Prado (2012) | Sharpe significance for one rule                  |
| Pareto-Optimal HP Selection | Bischl et al. (2023)           | Multi-objective hyperparameter optimization       |
| Warm-Starting               | Nomura & Ono (2021)            | Transfer knowledge between optimization runs      |

See [references/academic-foundations.md](./references/academic-foundations.md) for full literature review.

## Core Formula: Walk-Forward Efficiency

```python
def compute_wfe(
    is_sharpe: float,
    oos_sharpe: float,
    n_samples: int | None = None,
) -> float | None:
    """Walk-Forward Efficiency - measures performance transfer.

    WFE = OOS_Sharpe / IS_Sharpe

    Interpretation (guidelines, not hard thresholds):
    - WFE ≥ 0.70: Excellent transfer (low overfitting)
    - WFE 0.50-0.70: Good transfer
    - WFE 0.30-0.50: Moderate transfer (investigate)
    - WFE < 0.30: Severe overfitting (likely reject)

    The IS_Sharpe minimum is derived from signal-to-noise ratio,
    not a fixed magic number. See compute_is_sharpe_threshold().

    Reference: Pardo (2008) "The Evaluation and Optimization of Trading Strategies"
    """
    # Data-driven threshold: IS_Sharpe must exceed 2σ noise floor
    min_is_sharpe = compute_is_sharpe_threshold(n_samples) if n_samples else 0.1

    if abs(is_sharpe) < min_is_sharpe:
        return None
    return oos_sharpe / is_sharpe
```

## Principled Configuration Framework

All parameters are derived from first principles or data characteristics. `AWFESConfig` provides unified configuration with log-spaced epoch generation, Bayesian variance derivation from search space, and market-specific annualization factors.

See [references/configuration-framework.md](./references/configuration-framework.md) for the full `AWFESConfig` class and `compute_is_sharpe_threshold()` implementation.

## Guardrails (Principled Guidelines)

> **No trial-count corrections (operator rule, 2026-10-15)**: never compute, report, rank by or cite the Deflated Sharpe Ratio, the minimum backtest length (MinBTL) or any other trial-count correction (FWER/FDR procedures such as Holm or Benjamini-Yekutieli, e-LOND and other online multiple testing). Epoch-selection risk is handled by judging parsimony on the model itself (a small, pre-declared candidate set), by registration before runs and by unused data, and each rule reports its own statistics (Sharpe, PSR, MinTRL). The former DSR guardrail was removed on purpose; do not re-add it.

- **G1: WFE Thresholds** - 0.30 (reject), 0.50 (warning), 0.70 (target) based on practitioner consensus
- **G2: IS_Sharpe Minimum** - Data-driven threshold: `2/sqrt(n)` adapts to sample size
- **G3: Stability Penalty** - Adaptive threshold derived from WFE variance prevents epoch churn
- **G4: Registration and unused data** - The epoch candidate set, WFE thresholds and acceptance criteria are fixed before the sweep; acceptance is judged on test data no selection step has touched. No trial-count correction is applied

See [references/guardrails.md](./references/guardrails.md) for full implementations of all guardrails.

## WFE Aggregation Methods

Under the null hypothesis, WFE follows a **Cauchy distribution** (no defined mean). Always prefer median or pooled methods:

- **Pooled WFE**: Precision-weighted by sample size (best for variable fold sizes)
- **Median WFE**: Robust to outliers (best for suspected regime changes)
- **Weighted Mean**: Inverse-variance weighting (best for homogeneous folds)

See [references/wfe-aggregation.md](./references/wfe-aggregation.md) for implementations and selection guide.

## Efficient Frontier Algorithm

Pareto-optimal epoch selection: an epoch is on the frontier if no other epoch dominates it (better WFE AND lower training time). The `AdaptiveEpochSelector` class maintains state across folds with adaptive stability penalties.

See [references/efficient-frontier.md](./references/efficient-frontier.md) for the full algorithm and carry-forward mechanism.

## Anti-Patterns

| Anti-Pattern                      | Symptom                             | Fix                               | Severity |
| --------------------------------- | ----------------------------------- | --------------------------------- | -------- |
| **Expanding window (range bars)** | Train size grows per fold           | Use fixed sliding window          | CRITICAL |
| **Peak picking**                  | Best epoch always at sweep boundary | Expand range, check for plateau   | HIGH     |
| **Insufficient folds**            | effective_n < 30                    | Increase folds or data span       | HIGH     |
| **Ignoring temporal autocorr**    | Folds correlated                    | Use purged CV, gap between folds  | HIGH     |
| **Overfitting to IS**             | IS >> OOS Sharpe                    | Reduce epochs, add regularization | HIGH     |
| **sqrt(252) for crypto**          | Inflated Sharpe                     | Use sqrt(365) or sqrt(7) weekly   | MEDIUM   |
| **Single epoch selection**        | No uncertainty quantification       | Report confidence interval        | MEDIUM   |
| **Meta-overfitting**              | Epoch selection itself overfits     | Limit to 3-4 candidates max       | HIGH     |

**CRITICAL**: Never use expanding window for range bar ML training. See [references/anti-patterns.md](./references/anti-patterns.md) for the full analysis (Section 7).

## Decision Tree

See [references/epoch-selection-decision-tree.md](./references/epoch-selection-decision-tree.md) for the full practitioner decision tree.

```
Start
  │
  ├─ IS_Sharpe > compute_is_sharpe_threshold(n)? ──NO──> Mark WFE invalid, use fallback
  │         │                                            (threshold = 2/√n, adapts to sample size)
  │        YES
  │         │
  ├─ Compute WFE for each epoch
  │         │
  ├─ Any WFE > 0.30? ──NO──> REJECT all epochs (severe overfit)
  │         │                (guideline, not hard threshold)
  │        YES
  │         │
  ├─ Compute efficient frontier
  │         │
  ├─ Apply AdaptiveStabilityPenalty
  │         │ (threshold derived from WFE variance)
  └─> Return selected epoch
```

## Integration with rangebar-eval-metrics

This skill extends [rangebar-eval-metrics](../opendeviation-eval-metrics/SKILL.md):

| Metric Source         | Used For                                 | Reference                                                                                     |
| --------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| `sharpe_tw`           | WFE numerator (OOS) and denominator (IS) | [range-bar-metrics.md](./references/range-bar-metrics.md)                                     |
| `n_bars`              | Sample size for aggregation weights      | [metrics-schema.md](../opendeviation-eval-metrics/references/metrics-schema.md)               |
| `psr`, `min_trl`      | Final acceptance criteria                | [sharpe-formulas.md](../opendeviation-eval-metrics/references/sharpe-formulas.md)             |
| `prediction_autocorr` | Validate model isn't collapsed           | [ml-prediction-quality.md](../opendeviation-eval-metrics/references/ml-prediction-quality.md) |
| `is_collapsed`        | Model health check                       | [ml-prediction-quality.md](../opendeviation-eval-metrics/references/ml-prediction-quality.md) |
| Extended risk metrics | Deep risk analysis (optional)            | [risk-metrics.md](../opendeviation-eval-metrics/references/risk-metrics.md)                   |

### Recommended Workflow

1. **Compute base metrics** using `rangebar-eval-metrics:compute_metrics.py`
2. **Feed to AWFES** for epoch selection with `sharpe_tw` as primary signal
3. **Validate** on the untouched test split with `psr > 0.85` and enough data for `min_trl` before deployment
4. **Monitor** `is_collapsed` and `prediction_autocorr` for model health

---

## OOS Application Phase

AWFES uses **Nested WFO** with three data splits per fold (Train 60% / Val 20% / Test 20%) with 6% embargo gaps at each boundary. The per-fold workflow: epoch sweep on train, WFE computation on validation, Bayesian update, final model training on train+val, evaluation on test.

See [references/oos-workflow.md](./references/oos-workflow.md) for the complete workflow with diagrams, `BayesianEpochSelector` class, and `apply_awfes_to_test()` implementation. Also see [references/oos-application.md](./references/oos-application.md) for the extended reference.

## Epoch Smoothing Methods

Bayesian updating (recommended) provides principled, uncertainty-aware smoothing. Alternatives include EMA and SMA. Initialization via `AWFESConfig.from_search_space()` derives variances from the epoch range automatically.

See [references/epoch-smoothing-methods.md](./references/epoch-smoothing-methods.md) for all methods, formulas, and initialization strategies. See [references/epoch-smoothing.md](./references/epoch-smoothing.md) for extended mathematical analysis.

## OOS Metrics Specification

Three-tier metric hierarchy for test evaluation:

- **Tier 1 (Primary)**: `sharpe_tw`, `hit_rate`, `cumulative_pnl`, `positive_sharpe_folds`, `wfe_test`
- **Tier 2 (Risk)**: `max_drawdown`, `calmar_ratio`, `profit_factor`, `cvar_10pct`
- **Tier 3 (Statistical)**: `psr`, `binomial_pvalue`, `hac_ttest_pvalue`

See [references/oos-metrics-implementation.md](./references/oos-metrics-implementation.md) for full metric tables, `compute_oos_metrics()`, and fold aggregation code. See [references/oos-metrics.md](./references/oos-metrics.md) for threshold justifications.

## Look-Ahead Bias Prevention

**CRITICAL (v3 fix)**: TEST must use `prior_bayesian_epoch` (from prior folds only), NOT `val_optimal_epoch`. The Bayesian update happens AFTER test evaluation, ensuring information flows only from past to present.

See [references/look-ahead-bias-v3.md](./references/look-ahead-bias-v3.md) for the v3 fix details, embargo requirements, validation checklist, and anti-patterns. See [references/look-ahead-bias.md](./references/look-ahead-bias.md) for detailed examples.

---

## References

| Topic                    | Reference File                                                                    |
| ------------------------ | --------------------------------------------------------------------------------- |
| Academic Literature      | [academic-foundations.md](./references/academic-foundations.md)                   |
| Mathematical Formulation | [mathematical-formulation.md](./references/mathematical-formulation.md)           |
| Configuration Framework  | [configuration-framework.md](./references/configuration-framework.md)             |
| Guardrails               | [guardrails.md](./references/guardrails.md)                                       |
| WFE Aggregation          | [wfe-aggregation.md](./references/wfe-aggregation.md)                             |
| Efficient Frontier       | [efficient-frontier.md](./references/efficient-frontier.md)                       |
| Decision Tree            | [epoch-selection-decision-tree.md](./references/epoch-selection-decision-tree.md) |
| Anti-Patterns            | [anti-patterns.md](./references/anti-patterns.md)                                 |
| OOS Workflow             | [oos-workflow.md](./references/oos-workflow.md)                                   |
| OOS Application          | [oos-application.md](./references/oos-application.md)                             |
| Epoch Smoothing Methods  | [epoch-smoothing-methods.md](./references/epoch-smoothing-methods.md)             |
| Epoch Smoothing Analysis | [epoch-smoothing.md](./references/epoch-smoothing.md)                             |
| OOS Metrics Impl         | [oos-metrics-implementation.md](./references/oos-metrics-implementation.md)       |
| OOS Metrics Thresholds   | [oos-metrics.md](./references/oos-metrics.md)                                     |
| Look-Ahead Bias (v3)     | [look-ahead-bias-v3.md](./references/look-ahead-bias-v3.md)                       |
| Look-Ahead Bias Examples | [look-ahead-bias.md](./references/look-ahead-bias.md)                             |
| **Feature Sets**         | [feature-sets.md](./references/feature-sets.md)                                   |
| **xLSTM Implementation** | [xlstm-implementation.md](./references/xlstm-implementation.md)                   |
| **Range Bar Metrics**    | [range-bar-metrics.md](./references/range-bar-metrics.md)                         |
| Troubleshooting          | [troubleshooting.md](./references/troubleshooting.md)                             |

### Related Skills

| Skill                                                                            | Relationship                             |
| -------------------------------------------------------------------------------- | ---------------------------------------- |
| [sharpe-ratio-non-iid-corrections](../sharpe-ratio-non-iid-corrections/SKILL.md) | Generalized Sharpe variance, PSR, MinTRL |
| [opendeviation-eval-metrics](../opendeviation-eval-metrics/SKILL.md)             | Metric definitions consumed by WFE       |

## Full Citations

- Bailey, D. H., & López de Prado, M. (2012). The Sharpe ratio efficient frontier. _Journal of Risk_, 15(2), 3-44.
- Bischl, B., et al. (2023). Multi-Objective Hyperparameter Optimization in Machine Learning. _ACM Transactions on Evolutionary Learning and Optimization_.
- López de Prado, M. (2018). _Advances in Financial Machine Learning_. Wiley. Chapter 7.
- Nomura, M., & Ono, I. (2021). Warm Starting CMA-ES for Hyperparameter Optimization. _AAAI Conference on Artificial Intelligence_.
- Pardo, R. E. (2008). _The Evaluation and Optimization of Trading Strategies, 2nd Edition_. John Wiley & Sons.

## Post-Execution Reflection

After this skill completes, check before closing:

1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

© terrylica · MIT · terrylica/cc-skills

Similar skills

All skills for AI and ML →

From the same set79

The whole set →
clickhouse-architect clickhouse-architect designs ClickHouse v24.4+ table schemas, selects compression codecs, and configures sorting keys for cloud and self-hosted clusters. CX Codex +1 157installs dead-code-detector dead-code-detector finds unreachable code, unused imports, and dead exports across Python, TypeScript, and Rust codebases. Useful before major releases and refactoring sprints. CX Codex +1 150installs plotext-financial-chart plotext-financial-chart builds pure text financial line charts for Markdown files using plotext. It helps display price paths directly in GitHub documentation without external images. CX Codex +1 146installs latex-setup The latex-setup skill sets up and verifies LaTeX on macOS, then configures Skim and SyncTeX. It supports Mac preparation and TeX package troubleshooting. CX Codex +1 146installs log-reader log-reader reads MetaTrader 5 log files and Print() output straight from UTF-16LE daily logs without checking the Experts tab manually. CX Codex +1 145installs adr-code-traceability The adr-code-traceability skill links code to Architecture Decision Records with file headers or inline comments. Use it when an implementation choice needs a clear connection to its decision record. CX Codex +1 144installs mlflow-python mlflow-python is a Claude Code skill for logging backtest parameters and metrics in MLflow, searching experiment runs, and retrieving metric history via the Python API. CX Codex +1 139installs code-clone-assistant code-clone-assistant detects duplicate code using PMD CPD and Semgrep, guides refactoring of DRY violations. Catches both exact clones and similar patterns. CX Codex +1 139installs

Project sponsors

Companies that keep this analytics open