Use next-open returns for research eval

scripts/generate_reversal_5d_report.py

@@ -7,7 +7,7 @@ Covers three runs of the same 5-day reversal *signal* under this repo's
     rank_full   : reversal_rank (rank weighting),    full ~5k all-universe
     rank_liquid : reversal_rank (rank weighting),    per-date liquid subset
 
-For each run it checks artifact storage, recomputes no-lookahead research
+For each run it checks artifact storage, recomputes no-lookahead open-to-open research
 metrics, measures how close the constructed portfolio is to the alpha and how
 close the simulated net PnL is to the alpha, and renders a markdown report plus
 PNG visualizations under docs/.
@@ -159,7 +159,7 @@ def _additive_metrics(daily: pd.Series) -> dict:
 
 
 def _research_returns(weights: pd.DataFrame, fwd: pd.DataFrame) -> pd.Series:
-    """w_t · r_{t+1} / sum|w_t| on the signal calendar (no lookahead)."""
+    """w_t · r_open[t+1→t+2] / sum|w_t| on the signal calendar."""
     w = weights
     f = fwd.reindex(index=w.index, columns=w.columns)
     gross = w.abs().sum(axis=1)
@@ -363,7 +363,7 @@ def plot_research_equity(results: dict) -> Path:
                       f"(Sharpe {results[k]['alpha_metrics']['sharpe_annual']:.2f})")
     ax.axhline(1.0, color="#666", linewidth=0.8)
     ax.set_yscale("log")
-    ax.set_title("Costless no-lookahead alpha research equity (log scale)")
+    ax.set_title("Costless next-open-to-next-open alpha research equity (log scale)")
     ax.set_ylabel("growth of 1.0")
     ax.grid(True, which="both", alpha=0.25)
     ax.legend(loc="best")
@@ -598,176 +598,455 @@ def render_report(results: dict, data_summary: dict, timings: dict,
             return float("nan")
         return results[run_key]["alpha_metrics"]["cumulative_return"]
 
-    return f"""# 5-Day Reversal — End-to-End Pipeline Report
+    return f"""# Tutorial: Testing a 5-Day Reversal Alpha
 
 Generated: {datetime.now().isoformat(timespec="seconds")}
 
-This report runs the **5-day reversal** signal end to end through the decoupled
-pipeline (`data → alpha → combo → portfolio build → portfolio simulate/eval`) on
-the full downloaded A-share universe, and answers the seven review questions:
-alpha storage, metric sanity, NaN/look-ahead handling, alpha↔portfolio
-closeness, alpha↔PnL closeness, per-phase timing, and visualizations.
+This document is a teaching walkthrough for someone who is new to this research
+framework and only lightly familiar with quant research. We will use one
+concrete experiment, a 5-day reversal alpha on the full downloaded Chinese
+A-share universe, to learn how the framework defines an alpha, stores it, tests
+it, turns it into a portfolio, and explains the gap between a research result
+and simulated trading PnL.
 
-Per this repo's convention an **alpha is a signed cross-sectional position
-weight, not a return predictor**, so evaluation is return / Sharpe / turnover /
-drawdown — there is deliberately **no IC/IR** anywhere.
+The important point is not the timestamp; it is the research method.
 
-## TL;DR
+## The Research Question
 
-The naive built-in `reversal` alpha (raw `-pct_change(5)` then cross-sectional
-**z-score**) loses **{_pct(cum('naive_full'))}** in costless research on the full
-~5,200-name universe. That is **not** evidence the signal is bad — it is an
-artifact of z-score weighting on A-shares: a handful of newly listed /
-post-suspension / limit-up names produce huge `pct_change` outliers, and
-z-scoring pours the book into exactly those names (stored weights reach
-{results['naive_full']['storage']['weight_min']:.0f}σ).
+A quant research project starts with a hypothesis:
 
-Switching only the **weighting** to a bounded cross-sectional **rank**
-(`reversal_rank`) and restricting to a per-date **liquid, non-ST, tradable**
-universe recovers a genuine reversal edge: **{_pct(cum('rank_liquid')) if rliq else float('nan')}**
-costless research cumulative return at Sharpe
-**{results['rank_liquid']['alpha_metrics']['sharpe_annual']:.2f}** with a
-{_pct(results['rank_liquid']['alpha_metrics']['hit_rate']) if rliq else 'n/a'} daily hit rate.
+> If a stock fell a lot over the last few trading days, it may rebound soon; if
+> it rose a lot, it may cool off soon.
 
-The binding constraint is **cost, not signal**: at ~{results['rank_liquid']['alpha_metrics']['turnover_annual']:.0f}×/year
-turnover, a 10 bps one-way per-trade cost (5 bps commission + 5 bps slippage,
-charged on each leg — so ~20 bps per round trip) erases the edge — every variant
-is negative after costs. A tradable 5-day reversal needs
-turnover control, not a different signal.
+This is called **short-horizon reversal**. It is a simple idea: recent losers
+are candidates to buy, and recent winners are candidates to sell or underweight.
+In this repo, the tested version looks back 5 trading days.
 
-## Headline Metrics
+The central research question is:
 
-{headline}
+> Does this 5-day reversal rule create useful portfolio returns after the
+> framework applies realistic storage, portfolio construction, execution
+> constraints, and trading costs?
 
-*Research = costless, no-look-ahead weights · next-day return. Execution = next-open
-fills on the discretized integer book under suspension / price-limit / volume-cap
-constraints, 5 bps commission + 5 bps slippage.*
+The answer from this run is nuanced:
+
+- The naive built-in version is positive under the tradable
+  next-open-to-next-open research convention (**{_pct(cum('naive_full'))}**),
+  but its stored weights still show that raw z-score weighting is too sensitive
+  to A-share outliers.
+- A rank-weighted version on a liquid, non-ST, tradable universe has a positive
+  costless research result: **{_pct(cum('rank_liquid')) if rliq else 'n/a'}**
+  at Sharpe **{results['rank_liquid']['alpha_metrics']['sharpe_annual']:.2f}**.
+- The daily-traded implementation is still not tradable after costs because
+  turnover is too high.
+
+That is a normal research outcome. Good research is not just asking "did the
+backtest go up?" It is asking **which layer explains the result**: signal,
+weighting, universe, construction, execution, or cost.
+
+## How This Framework Defines An Alpha
+
+In many quant textbooks, an alpha is described as a **prediction** of future
+returns. This framework uses a stricter and more practical convention:
+
+> An alpha is a signed cross-sectional position weight.
+
+That sentence is the key to the whole repo.
+
+- **Signed** means positive values are long exposure and negative values are
+  short exposure.
+- **Cross-sectional** means the alpha compares stocks to other stocks on the
+  same date.
+- **Position weight** means the output is already an instruction about what the
+  portfolio wants to own. It is not merely a score to correlate with future
+  returns.
+
+The stored alpha file always has this schema:
+
+| column | meaning |
+| --- | --- |
+| `symbol_id` | Stock identifier such as `sh600000` or `sz000001`. |
+| `date` | The signal date. The alpha is formed using information known by this date's close. |
+| `alpha_name` | A label for this particular run, such as `reversal_5d_all`. |
+| `weight` | Signed desired exposure. Positive means long; negative means short. |
+
+Because the framework treats alphas as position weights, it evaluates them with
+portfolio metrics: return, Sharpe, turnover, drawdown, and hit rate. It does
+**not** use IC/IR, because IC/IR would treat the alpha as a return predictor.
+
+## The Pipeline In One Picture
+
+Every phase reads parquet files and writes parquet files. That makes the system
+easy to inspect and rerun one layer at a time.
+
+```text
+daily bars
+   -> alpha weights
+   -> combined weights
+   -> portfolio targets and integer positions
+   -> simulated fills and PnL
+   -> evaluation metrics
+```
+
+For this experiment, the important phases are:
+
+| phase | command family | what it teaches you |
+| --- | --- | --- |
+| Data | `cli.py data download` | What market data is available. |
+| Alpha compute | `cli.py alpha compute` | How a raw research idea becomes stored weights. |
+| Alpha eval | `cli.py alpha eval` | How close-formed weights perform over the tradable next-open-to-next-open interval. |
+| Combo | `cli.py combo combine` | How one or more alphas become one combined book. |
+| Portfolio build | `cli.py portfolio build` | How weights become target values and integer shares. |
+| Portfolio simulate | `cli.py portfolio simulate` | How the integer book trades at next open with constraints and costs. |
+| Portfolio eval | `cli.py portfolio eval` | How the continuous target portfolio behaves over the same costless open-to-open research interval. |
+
+In a real research workflow, you should learn to pause after every phase and
+inspect the parquet output. Most mistakes are easier to find at the interface
+between two phases than at the final PnL line.
+
+## Step 1: Define The Raw Reversal Signal
+
+The built-in 5-day reversal alpha is implemented as:
+
+```python
+signal = -close.pct_change(5, fill_method=None)
+```
+
+For stock `i` on date `t`, this is approximately:
+
+```text
+signal[i, t] = -(close[i, t] / close[i, t-5] - 1)
+```
+
+So:
+
+- If a stock rose by 10% over the last 5 trading days, the raw signal is `-10%`.
+  It becomes a candidate short or underweight.
+- If a stock fell by 10% over the last 5 trading days, the raw signal is `+10%`.
+  It becomes a candidate long or overweight.
+
+Notice the timing. The signal uses prices through date `t`. It must not use the
+return from `t` to `t+1`, because that is the future. The costless alpha
+evaluator tests the weight formed on date `t` over the tradable interval from
+`open[t+1]` to `open[t+2]`; the later execution simulator is the separate layer
+that trades the constructed integer book at the next open.
+
+## Step 2: Turn A Signal Into Cross-Sectional Weights
+
+By default, `BaseAlpha.to_weights()` does a cross-sectional z-score each date:
+
+```text
+weight[i, t] = (signal[i, t] - mean_signal[t]) / std_signal[t]
+```
+
+This means the framework asks:
+
+> On this date, which stocks have stronger reversal scores than the rest of the
+> market, and by how much?
+
+That is useful, but it has a weakness. If a few stocks have extreme trailing
+returns because they are newly listed, suspended, illiquid, or limit-constrained,
+z-scoring can put a very large amount of relative exposure into exactly those
+names.
+
+That is visible in the naive full-universe run. Stored weights reached about
+`{results['naive_full']['storage']['weight_min']:.0f}` standard deviations. The
+result is positive under the open-to-open convention, but it is much weaker and
+less robust than the rank-weighted versions:
+
+| run | weighting | research cumulative return | research Sharpe | research turnover/year |
+| --- | --- | --- | --- | --- |
+| naive z-score, full universe | z-score | {_pct(cum('naive_full'))} | {results['naive_full']['alpha_metrics']['sharpe_annual']:.4f} | {results['naive_full']['alpha_metrics']['turnover_annual']:.0f}x |
+
+The lesson is not "reversal is solved." The lesson is:
+
+> The same raw signal can become a fragile portfolio if the weighting method
+> reacts badly to outliers.
+
+## Step 3: Make The Weighting More Robust
+
+The repo also has a rank-weighted version, `reversal_rank`. It uses the same raw
+5-day reversal signal, but converts the cross-section to ranks instead of
+z-scores:
+
+```python
+ranks = signal.rank(axis=1)
+weights = ranks.subtract(ranks.mean(axis=1), axis=0)
+```
+
+Rank weighting keeps the ordering of stocks but removes the importance of the
+exact outlier magnitude. A stock can be "the worst recent loser" or "the best
+recent winner," but it cannot become dozens of standard deviations important
+just because its raw percentage move is unusual.
+
+The full-universe rank version was much less pathological, but still not a
+clean signal:
+
+| run | weighting | research cumulative return | research Sharpe | research turnover/year |
+| --- | --- | --- | --- | --- |
+| rank, full universe | rank | {_pct(cum('rank_full')) if rfull else 'n/a'} | {results['rank_full']['alpha_metrics']['sharpe_annual']:.4f} | {results['rank_full']['alpha_metrics']['turnover_annual']:.0f}x |
+
+That tells us the weighting fix helped, but the universe still contains many
+names that are poor candidates for a daily reversal strategy.
+
+## Step 4: Define The Investable Universe
+
+An alpha should be tested on stocks that could plausibly be traded. The liquid
+run applies a per-date mask before weights are created. A stock must be:
+
+- seasoned, with at least 60 observed closes;
+- currently tradable, using `tradestatus == 1`;
+- not ST, using `isST == 0`;
+- inside the top 1000 names by trailing 20-day average traded amount.
+
+This mask is applied to the signal, not to the price history used to compute the
+5-day return. That distinction matters. We still compute `pct_change(5)` on the
+full contiguous price history, then decide which names are eligible to hold on
+each signal date.
+
+The liquid rank result is the cleanest research result:
+
+| run | weighting | universe | research cumulative return | research Sharpe | hit rate |
+| --- | --- | --- | --- | --- | --- |
+| rank, liquid subset | rank | top 1000 liquid, tradable, non-ST | {_pct(cum('rank_liquid')) if rliq else 'n/a'} | {results['rank_liquid']['alpha_metrics']['sharpe_annual']:.4f} | {_pct(results['rank_liquid']['alpha_metrics']['hit_rate']) if rliq else 'n/a'} |
+
+This is the first point where a researcher can say:
+
+> There appears to be a real 5-day reversal effect in a cleaner A-share
+> universe, before trading costs.
+
+That last phrase, **before trading costs**, is essential.
 
 ![Research equity](assets/reversal_5d_research_equity.png)
 
-## 1. Are Alpha Values Properly Stored?
+## Step 5: Check That The Alpha File Is Sane
 
-All alpha artifacts conform to `ALPHA_COLUMNS` (`symbol_id`, `date`, `alpha_name`,
-`weight`), carry no null / non-finite weights, no duplicate `(symbol_id, date)`
-keys, and have numerically-zero daily cross-sectional means (weights are
-demeaned per date).
+Before trusting any metric, inspect the stored alpha artifact. The run checked:
+
+- The columns match `ALPHA_COLUMNS`.
+- There are no null weights.
+- There are no non-finite weights.
+- There are no duplicate `(symbol_id, date)` rows.
+- The daily cross-sectional mean is approximately zero.
+- A one-alpha combo is an exact identity transform.
 
 {storage}
 
-The decisive storage signal is the **weight range**. The naive z-score alpha
-stores weights as extreme as
-`[{results['naive_full']['storage']['weight_min']:.0f}, {results['naive_full']['storage']['weight_max']:.0f}]` —
-single names tens of sigma from the cross-section. Rank weighting is bounded by
-construction, so its stored weights are well-behaved. Same signal, completely
-different book.
+The rank ranges look numerically large because rank weights scale with the
+number of names. That is fine: later evaluation divides by gross exposure, and
+portfolio construction normalizes by `sum(abs(weight))`. The important
+difference is that rank weights are bounded by cross-sectional rank, not by the
+raw size of an abnormal stock move.
 
 ![Weight distributions](assets/reversal_5d_weight_distributions.png)
 
-## 2. Do The Alpha Metrics Make Sense?
+## Step 6: Understand The Alpha Evaluation Formula
 
-Yes, and they tell a coherent story:
+The costless alpha evaluator now asks:
 
-- The **z-score full** run is dominated by a few outlier names; its research
-  Sharpe of {results['naive_full']['alpha_metrics']['sharpe_annual']:.2f} reflects a
-  book that is effectively long/short a tiny set of extreme movers, which in
-  A-shares keep trending — so the reversal bet loses.
-- **Rank full** ({_pct(cum('rank_full')) if rfull else 'n/a'}) is roughly flat:
-  the direction is right (hit rate
-  {_pct(results['rank_full']['alpha_metrics']['hit_rate']) if rfull else 'n/a'}) but
-  the long tail of illiquid / ST / freshly listed names adds noise.
-- **Rank liquid** is the clean result: a positive, monotone reversal premium
-  ({_pct(cum('rank_liquid')) if rliq else 'n/a'}, Sharpe
-  {results['rank_liquid']['alpha_metrics']['sharpe_annual']:.2f}) once the
-  investable universe is sane.
+> If we compute alpha weights after close on date `t`, trade them at `open[t+1]`,
+> and hold them until `open[t+2]`, what return would we earn before costs?
 
-This matches the prior literature that short-horizon reversal is a real but
-liquidity- and cost-sensitive A-share effect.
+This is still a **research-layer approximation**, not the trading simulator. At
+this stage the framework has only an alpha weight file. It has not yet rounded
+shares, checked limits, clipped trades, or paid costs. The purpose is to answer
+a clean signal question: "Do these close-formed weights line up with returns
+over the interval we could actually own after next-open execution?"
 
-## 3. NaN And Look-Ahead Handling
+The daily research return is:
 
-- The raw signal uses `close.pct_change(5, fill_method=None)` — missing prices
-  are **not** forward-filled, so a suspended name does not silently inherit a
-  stale price.
-- Weights are formed at close `t` and earn the **next** close-to-close return
-  `t → t+1`. Forward returns are computed on the full market calendar *before*
-  selecting signal dates, so a sparse signal grid still earns the next
-  *available* return rather than the next signal date. The final signal date,
-  which has no forward return, is dropped from metrics (that is why the
-  research day count is one less than the stored signal-date count).
-- The liquid-universe mask is applied to the **signal**, not to the price
-  history: `pct_change(5)` is always computed on contiguous prices, and the mask
-  only decides what is *held*. It uses `tradestatus`, `isST`, a ≥60-session
-  seasoning rule, and a trailing-20-day liquidity rank — all backward-looking.
+```text
+R[t] = sum_i(weight[i, t] * (open[i, t+2] / open[i, t+1] - 1)) / sum_i(abs(weight[i, t]))
+```
 
-## 4. How Close Are Alpha And Constructed Portfolio?
+This has three important consequences:
 
-`portfolio build` normalizes the alpha to `target_weight = w / Σ|w|` and scales
-by booksize. The continuous target portfolio is an exact normalization of the
-stored alpha (research return correlation ≈ 1.0); the **integer** book then
-diverges because small per-name targets are rounded away under A-share lot
-rules.
+- The alpha is normalized by its gross exposure, so the scale of raw weights
+  does not by itself create a higher return.
+- The new signal does not receive credit for the overnight gap from `close[t]`
+  to `open[t+1]`, because it cannot be traded until `open[t+1]`.
+- The final two signal dates are dropped from performance metrics because they
+  do not have a complete next-open-to-next-open holding interval.
+
+Turnover is still measured from the weights:
+
+```text
+turnover[t] = sum_i(abs(weight[i, t] - weight[i, t-1])) / sum_i(abs(weight[i, t-1]))
+```
+
+The annualized turnover numbers are a warning. Even a positive signal can be
+hard to monetize if it asks the portfolio to trade too much every day.
+
+## Step 7: Build A Portfolio From The Alpha
+
+The alpha file is still an abstract research book. `portfolio build` turns it
+into target exposures and integer shares.
+
+The main normalization is:
+
+```text
+target_weight[i, t] = weight[i, t] / sum_i(abs(weight[i, t]))
+target_value[i, t] = booksize * target_weight[i, t]
+target_shares[i, t] = target_value[i, t] / construction_price[i, t]
+```
+
+Then the framework creates an integer A-share book using lot rules and repair
+logic. This is where a research portfolio starts to become a tradable portfolio.
+
+The continuous target portfolio matched the stored alpha almost exactly:
 
 {closeness}
 
 ![Portfolio tracking](assets/reversal_5d_portfolio_tracking.png)
 
-## 5. How Close Are Alpha Metrics And Final PnL?
+## Step 8: Simulate Execution And Costs
 
-The costless research metric and the simulated net PnL diverge for two
-mechanical reasons, both quantified below: (a) **execution friction** — next-open
-fills, integer shares, and constraints; and (b) **cost** — the dominant term
-here.
+Research returns are not the same as tradable PnL. The simulator executes the
+integer `position_shares` at the next available open and applies constraints:
+
+- suspension;
+- price limit;
+- volume cap;
+- proportional trading cost.
+
+The cost model is:
+
+```text
+cost = abs(traded_shares * open) * (cost_bps + slippage_bps) / 10000
+```
+
+For this run, cost is 5 bps commission plus 5 bps slippage. Slippage is treated
+as cash cost, not as an additional execution price adjustment.
+
+The execution results explain the final research conclusion:
 
 {exec_close}
 
-The research↔execution-net daily-return correlation stays high (the book *does*
-track the signal), but the level collapses after cost. For the liquid run, gross
-costless edge is real yet total cost
-(**{_money(results['rank_liquid']['execution']['total_cost']) if rliq and results['rank_liquid']['execution'].get('exists') else 'n/a'}**)
-swamps it. This is the central finding: 5-day reversal is a signal you must trade
-*slowly* to monetize.
+For the liquid rank run, simulated PnL before cost is about
+{_money(results['rank_liquid']['execution']['total_pnl_before_cost']) if rliq and results['rank_liquid']['execution'].get('exists') else 'n/a'}, but total
+cost is about {_money(results['rank_liquid']['execution']['total_cost']) if rliq and results['rank_liquid']['execution'].get('exists') else 'n/a'}. That is why
+the final net PnL is weak or negative.
+
+This is not a contradiction. It is exactly what a research pipeline should show:
+
+> The signal can exist in the costless layer, but the daily implementation can
+> still trade too much to keep the edge.
 
 ![Execution vs research](assets/reversal_5d_exec_vs_research.png)
 
-## 6. Time Consumption By Phase
+## Step 9: Read The Headline Metrics Like A Researcher
+
+The complete summary is:
+
+{headline}
+
+*Research = costless, no-look-ahead weights over the next-open-to-next-open
+holding interval. Execution = next-open fills on the discretized integer book
+under suspension / price-limit / volume-cap constraints, 5 bps commission + 5
+bps slippage.*
+
+Here is the interpretation:
+
+- **Naive z-score full universe**: positive under open-to-open research, but a
+  less reliable test of the reversal idea because the weighting scheme lets
+  outliers dominate parts of the book.
+- **Rank full universe**: a better test of the same idea, but still noisy
+  because the universe includes too many problematic names.
+- **Rank liquid subset**: the best signal-level test; it finds the cleanest
+  costless reversal effect.
+- **Execution net**: daily rebalancing remains heavily constrained by cost.
+
+A beginner might look only at the final net PnL and say "the alpha failed." A
+researcher should be more precise:
+
+> The raw 5-day reversal idea has signal value in a liquid universe, but the
+> current daily trading rule has too much turnover for the assumed cost model.
+
+## Step 10: Time Consumption By Phase
 
 {timing_tbl}
 
 ![Phase timings](assets/reversal_5d_phase_timings.png)
 
-`portfolio build` dominates because it iterates per signal date and repairs a
-multi-thousand-name integer book under lot rules. The liquid run is faster
-across the board because it carries far fewer non-zero names per date.
+`portfolio build` usually dominates because it iterates per signal date and
+repairs a multi-thousand-name integer book under lot rules. The liquid run is
+faster because it carries fewer non-zero names per date.
 
-## 7. Reproduce The Run
+## Step 11: Reproduce The Experiment
+
+These commands reproduce the important artifacts, assuming the full daily-bar
+dataset already exists at `data/daily_bars/all`.
 
 ```bash
-# naive z-score baseline (full universe) — the built-in alpha, unchanged
+# Naive z-score baseline: built-in reversal alpha, full universe.
 uv run python cli.py alpha compute --data-path data/daily_bars/all \\
-    --alpha-name reversal_5d_all --alpha-type reversal --lookback 5 --output-dir alphas
+    --alpha-name reversal_5d_all --alpha-type reversal --lookback 5 \\
+    --output-dir alphas
 
-# robust rank weighting, full + liquid universe (one script, both runs)
+# Rank-weighted full and liquid runs.
 bash scripts/run_reversal_rank_e2e.sh
 
-# regenerate this report + figures
+# Regenerate figures, diagnostics, and this tutorial report.
 uv run python scripts/generate_reversal_5d_report.py
 ```
 
-## Interpretation & Next Steps
+If you are learning the framework, do not run the whole pipeline blindly. Run
+one phase, inspect the output parquet, then continue.
 
-The pipeline is internally consistent end to end: storage validates, the trivial
-one-alpha combo is an exact identity, the continuous target portfolio matches the
-alpha, and the execution layer cleanly explains the gap to net PnL via friction
-and cost. The premise that 5-day reversal "produces not-bad PnL" holds **at the
-signal level** once weighting and universe are sane (rank + liquid), but **fails
-net of cost** at daily rebalance frequency.
+## How To Research Your Own Alpha
 
-Recommended next diagnostics:
+Use this checklist for a new idea.
 
-- **Turnover control** — the highest-leverage lever: hold bands / no-trade zones,
-  weight smoothing, or longer rebalance spacing to cut the ~150×/yr turnover.
-- Volatility-scaled or decayed reversal to reduce churn.
-- Sweep the liquidity cutoff and lookback to map the cost/edge frontier.
+1. State the hypothesis in plain language.
+   Example: "Stocks with poor 5-day returns may rebound over the next day."
+
+2. Write the raw signal.
+   Implement `signal(close) -> wide DataFrame` in an alpha class. Higher values
+   should mean stronger long preference.
+
+3. Choose the weighting method.
+   The default z-score is useful, but it can be fragile. Consider rank weights,
+   caps, neutralization, or liquidity-aware filters if outliers dominate.
+
+4. Define the investable universe before trusting results.
+   Make sure the strategy is not depending on suspended, ST, newly listed, or
+   illiquid names.
+
+5. Evaluate the alpha as a portfolio, not as a prediction.
+   Check cumulative return, Sharpe, drawdown, hit rate, and turnover over the
+   next-open-to-next-open holding interval. Do not add IC/IR unless the
+   framework's alpha convention changes.
+
+6. Build the portfolio and inspect tracking.
+   Confirm that target weights match the alpha, then check whether integer
+   shares still track the target book.
+
+7. Simulate execution with costs.
+   The final research question is not only "is there a signal?" It is "is there
+   enough signal left after realistic trading?"
+
+8. Diagnose the failure layer.
+   If results are bad, identify whether the problem is the raw signal, weighting,
+   universe, construction, execution constraints, turnover, or cost.
+
+For this 5-day reversal study, the diagnosis is clear: **the signal-level result
+is most promising after robust weighting and a liquid universe filter, but the
+current implementation needs turnover control before it can be considered
+tradable.**
+
+## Next Research Directions
+
+The natural next experiments are:
+
+- Add turnover control: no-trade bands, slower rebalancing, or weight smoothing.
+- Sweep the lookback window: compare 3-day, 5-day, 10-day, and 20-day reversal.
+- Sweep liquidity filters: top 500, top 1000, top 1500 by traded amount.
+- Add position caps so no single name can dominate after normalization.
+- Compare rank weighting with volatility-scaled reversal.
+
+The most important habit is to keep the layers separate. A good alpha research
+workflow does not stop at a single performance number; it explains how the idea
+travels from hypothesis, to signal, to weights, to portfolio, to executable PnL.
 """
 
 
@@ -776,13 +1055,15 @@ def main() -> None:
     DIAGNOSTICS_PATH.parent.mkdir(parents=True, exist_ok=True)
 
     print("loading data ...")
-    data = pd.read_parquet(DATA_PATH, columns=["symbol_id", "date", "close"])
+    data = pd.read_parquet(DATA_PATH, columns=["symbol_id", "date", "open", "close"])
     data["date"] = pd.to_datetime(data["date"])
     data_dates = pd.DatetimeIndex(sorted(data["date"].unique()))
     by_date = data.groupby("date")["symbol_id"].size()
     close = data.pivot_table(index="date", columns="symbol_id", values="close",
                              aggfunc="first").sort_index()
-    fwd = close.pct_change(fill_method=None).shift(-1)
+    open_ = data.pivot_table(index="date", columns="symbol_id", values="open",
+                             aggfunc="first").sort_index()
+    fwd = open_.shift(-2).divide(open_.shift(-1)) - 1.0
     data_summary = {
         "rows": int(len(data)),
         "symbols": int(data["symbol_id"].nunique()),