Quant Backtest Lab

Quant Backtest Lab

TL;DR — 60-second mental model

每次回测任务，按这个形状走，一次跑通：

1. 取数走 westock：westock-data kline / finance / quote / sector / macro 等结构化 CLI 拿到完整时序，不要用语义搜索类 skill 当回测数据源。
2. 写一个自包含的 <prefix>_backtest.py：纯 Python + pandas，不用 backtrader / vectorbt 之类框架；signal-on-bar-i / execute-on-bar-i+1 防 look-ahead；最后调 export_results(...) 落 3 个标准文件到 cwd。
3. 渲染 index.html 到 cwd：复用 reference/render_dashboard.py + reference/dashboard_template.html，不要手写 HTML，不要手写导航页。
4. 完成 4 步自检：跑得起来 / 5 项 pitfalls 检查 / sanity + 对抗式审查 / 仪表盘本地渲染检查。任何一步红，不允许交付。
5. 回复 A/B/C 三段：实现细节 / 已知偏差 / 结果解读。先讲结论，再列证据；不要列文件名清单，不要喊"已完成 xx 文件生成"。

完整契约在下面。不要漏读「Mandatory」「Hard rule」「Iron rule」标记的小节。

Output-language lock (hard rule)

• 最终回复 + 仪表盘 + 图表 + 表格 + custom_html 全部跟随用户最新提问的语言，不跟标的所在市场。
• 英文提问 + 中港股 → 全英文输出；标的统一用 ticker（600519.SH / 0700.HK），不写中文股票名。
• 中文提问 → 全中文输出；已知中文股票名优先用中文名。
• 渲染仪表盘时显式传 language="zh"|"en"，不要靠隐式 fallback。
• 容易踩的坑：HTML 是英文但口头回复切回中文 / HTML 是中文但 KPI 卡和图例是英文模板默认值。

Trigger Conditions

Trigger this skill when any of the following is true:

• The user asks for a backtest
• The user provides quantitative descriptions such as entry/exit rules, symbols, frequency, or time range
• The user asks for backtest metrics or a report
• The user describes an event / signal / condition and wants to know the subsequent performance. Typical phrasing:
  • "Buy after XX and hold for N days; how did it perform?"
  • "What was the return after event XX?"
  • "After the signal triggers, hold N days and sell"
  • "Run an event study"
  • "Is this strategy effective?"
  • "Screen stocks that satisfy XX and check later performance"
• The user wants multi-symbol stock-selection backtests or portfolio rebalancing

Out of Scope

• Intraday / minute / tick backtesting: this skill only supports daily or lower-frequency data (daily, weekly, monthly). If the user asks for minute bars, 5-minute bars, ticks, and so on, state directly that it is unsupported
• Pricing for special derivatives such as options and convertible bonds
• Full cross-sectional factor stock-selection strategies

User-Facing Communication Rules

During clarification and in the final reply, do not expose code variable names, implementation details, or framework jargon. Everything should be communicated in natural language:

• ❌ "Use pandas rolling to compute MA120"
• ✅ "Calculated the 120-day moving average"
• ❌ "Signal is generated on bar i and executed on bar i+1"
• ✅ "After the signal is confirmed, buy at the next day's open"
• ❌ "A-share T+1 is enforced by entry_bar"
• ✅ "In A shares, you cannot sell on the same day you buy; the earliest sell is the next day"

Implementation details are internal. They must never appear in user-facing text (clarification or result interpretation).

Output-Language Resolution (Hard Rule)

• Output language follows the user's latest query, not the market
• If the user explicitly requests a language, follow that request
• Decide a single output_language = "zh" | "en" first, and route every user-visible string through it
• This rule applies to both layers: 1. the final conversation reply to the user; 2. dashboards / charts / tables and every other deliverable. Do not make the HTML English while the actual reply switches back to Chinese
• When generating the dashboard, always call build_dashboard_data(..., language=output_language) explicitly
• Simplified display rule:
  • output_language="en": all deliverables stay in English; China / Hong Kong stocks default to ticker code such as 600519.SH / 0700.HK
  • output_language="zh": all deliverables stay in Chinese; if a Chinese stock name is known, prefer the Chinese name instead of preserving an English stock name

Decide First: Do You Need Clarification?

Principle: only ask questions that are truly necessary to avoid being wrong. Do not dump eight questions on the user at once. Use defaults whenever that is safe. Keep clarification to 1-3 questions.

Must Ask (Wrong if You Don't)

If the information below is missing, the result can change completely. Do not guess; ask.

• Signal definition is ambiguous: the user says "breakout", "volume surge", or "uptrend". Is this a point-in-time event (the instant of crossing) or a persistent state? Without clarification, the generated strategy may be fundamentally different
• Lifecycle is unclear: the prompt says "first", "first buy point", or "buy again on the next golden cross" but does not define reset conditions. Is the event one-time only, or repeatable?
• Compound-exit semantics are unclear: entry is A and B and C, but the user only says "exit on reverse signal". Does "reverse" mean the full mirror condition, or only one sub-condition?

Should Ask (Ask if Ambiguous; Otherwise Use Defaults)

• Backtest range — ask if the user did not specify one; if they say "last three years", it can be inferred
• Position sizing — for single-symbol strategy backtests, default to full position and disclose it; for multi-symbol / portfolio tasks, clarify or ask about weights. If the user mentions "partial allocation", "10%", etc., confirm the actual number
• Execution timing — default is next-day open; if the user says "buy the same day", ask whether that means same-day close or next-day open

Use Defaults Directly (Do Not Ask)

• Fees / slippage: 3 bps for continuous strategies; 0 for event-study style setups
• Data frequency: daily
• T+1 / lot size: enabled automatically for A shares
• Dashboard: generate by default

If the task involves multiple strategies / multiple symbols (priority vs secondary, rotation, hedging, switching), immediately read the "Multi-Strategy Interaction" section in reference/strategy_parsing.md and check priority, preemption, switching timing, and ownership of constraints item by item. If any answer is unclear, ask the user.

The following descriptions implicitly introduce look-ahead bias, so you must point that out and confirm how to handle them:

• "Buy when today's return exceeds X%" -> today's return is only known at the close, not at the open. Two reasonable treatments: (1) buy at the next day's open (no look-ahead), or (2) buy at the same-day close (user must explicitly accept this)
• "Buy when the stock hits limit-up / limit-down today" -> same issue; limit-up state is only final at the close
• "Buy when there is a volume breakout today" -> volume is accumulated throughout the day and is not final before the close
• "Select the top N stocks by this year's / this quarter's return" -> cross-sectional look-ahead; you only know the top performers after the fact. This must be rephrased as "use prior-period ranking" or explicitly disclosed as survivor / hindsight bias
• "Buy at today's close when the close moves above the moving average" -> close > MA is known only at the close; using the close as execution requires user confirmation

Handling principle: do not silently work around the issue. Tell the user: "Your description cannot avoid look-ahead on daily bars; which approximation do you accept?"

The following cases should not be assumed by default:

• A daily-bar strategy that still requires exact intraday execution -> state directly that it is unsupported
• A-share symbols with a strategy description that includes short selling / opening shorts / reversing into shorts: you must ask first. There are three reasonable paths:
  1. The user confirms this is only a theoretical backtest ignoring securities-lending constraints -> implement shorting, but do not pass market="china_a" into export_results (to disable short hard-fail). In the reply, explicitly say: "Naked short selling is not actually allowed in A shares; this backtest ignores borrowing constraints and is for theoretical validation only."
  2. The user wants borrowing semantics -> model borrowing cost, margin requirements, and restrict to borrowable symbols
  3. The user confirms long-only -> reinterpret short signals as exit signals and proceed on the normal market="china_a" path

Quick Flow

1. Mandatory first step: read reference/pitfalls/pandas.md (common pure-Python backtest mistakes) and reference/common_pitfalls.md (the checklist).

2. Read reference/strategy_parsing.md and convert the strategy into a structured form.

3. Write the backtest in pure Python + pandas. Do not use backtrader or any other backtesting framework. The LLM is free to choose the code structure; there is no required template.

4. Load additional references on demand; do not read everything every time.

5. Formal export, dashboard rendering, and strategy-specific modules all follow the later contract sections: strategy backtests use export_results(...) under "Standard Output Files"; event studies write event-level trades.csv directly; dashboards default to the "HTML Dashboard" section; strategy-specific content goes into the main dashboard via custom_html. Do not output a second standalone HTML page. reference/render_dashboard.py is a copyable example, not a mandatory library.

6. Assumptions and known bias should be explained directly in the reply to the user (see part A/B of item 10 and the "Assumptions and Bias" section).

7. HTML dashboard is mandatory after the backtest runs. Once the script produces the 3 standard files, you must render an index.html through build_dashboard_data(...) + the bundled dashboard_template.html (see the "HTML Dashboard" section). This step is not optional — skip it only if the user has explicitly said they do not want a dashboard. Do not hand over results without the rendered HTML.

8. Self-check is mandatory after coding (see the "Self-Check" section): all 4 steps must be completed before delivery — operability (run in cwd + files produced) / pitfalls checklist / sanity check + adversarial review / post-deploy dashboard self-check. Adversarial review cannot be skipped.

9. Default deliverables are defined by the three sections "Standard Output Files / HTML Dashboard / Matplotlib Charts". Only skip the dashboard if the user explicitly says they do not want one. Only skip charts if the user explicitly says they do not want charts.

10. The final reply must include result analysis. This is user-facing text in the conversation. Do not dump the full reply verbatim into the dashboard; however, stable and reviewable parts (such as conclusion summary, key assumptions, limitations, and optimization ideas) may be summarized into text modules in the dashboard. Do not list deliverable files (for example "generated xx.csv / xx.json / xx.html"). Go straight to analysis. The reply must include the following three parts:

    Language-lock addendum — Before sending the final reply, check it once: if output_language="en", then sections A/B/C must all be in English, and China / Hong Kong stock references should default to ticker code; if output_language="zh", then sections A/B/C must all be in Chinese, and known Chinese stock names should stay in Chinese.

    A. Implementation Details — Tell the user exactly how the code works. It is not enough to say "stop-loss was implemented" without explaining how. Any parameter that the prompt did not explicitly specify but the code had to choose must also be explained here, not hidden in comments. You must cover:

    • Which data fields were used for signal evaluation (close / high / low / open) and why
    • Execution timing: next-day open or same-day close, and whether that matches the user's likely expectation
    • Stop-loss / take-profit trigger semantics: use low/high as an intraday approximation, or only use close
    • Position sizing: how size is computed and what the effective exposure becomes after lot rounding
    • The equity_curve accounting convention: how single-name / portfolio / short exposure / negative cash / liabilities are aggregated; rotation, short, and leverage strategies must explain this explicitly instead of just saying "daily equity was recorded"
    • Other key implementation choices: how T+1 is handled, how compound conditions are combined, how the state machine resets, and so on

    B. Limitations and Known Bias — Explain why the backtest should not be taken as reality at face value. Common bias sources include survivor bias, look-ahead, data coverage, and warmup slicing:

    • Daily-bar limitations: stop-loss / take-profit cannot precisely reconstruct intraday order, and the order of high vs low inside one bar is unknown
    • Execution-assumption bias: next-day-open execution can differ substantially from the signal price in volatile periods
    • Slippage and liquidity: the backtest does not model market impact; large real trades will incur slippage
    • Data bias: adjustment method, survivor bias, data coverage, and so on
    • Strategy-specific weakness: which market environments it may fail in, whether parameters may be overfit, and so on
    • You do not need to list everything. Pick the 2-3 items that matter most for this specific run

    C. Result Interpretation — After reading summary.json + trades.csv, choose the 3-5 most informative angles from the list below (you do not need to use all of them):

    • Return attribution: which trades contributed most? Is it a few large wins with many small losses (trend-following), or a high win-rate / small-profit profile?
    • Drawdown analysis: when did the worst drawdown occur? Did the stop mechanism actually help?
    • Trade frequency: how many buys and sells separately (do not just say "N total trades"; break it into "X buys, Y sells"), and is the holding period sensible?
    • Signal quality: how many signals fired? How many were skipped because of capital / lot-size / position constraints?
    • Time-segment performance: are there obvious differences by year or quarter?
    • Strategy limitation: in what market regime is it likely to fail?
    • Event-driven specific: which events contributed the best and worst results? Is the return distribution skewed?
    • Portfolio-specific: is the rebalance frequency or deviation threshold sensible?

    Writing requirement: lead with the conclusion -> support it with concrete trade data -> if the result is poor, say so plainly instead of dressing it up. Parts A/B/C are all required; do not only write C and omit A/B. Keep the answer concise.

On-Demand Loading

• reference/pitfalls/pandas.md — mandatory read (before writing code)
• reference/common_pitfalls.md — mandatory read (self-check after coding)
• reference/china_a_rules.md — for A shares / ETFs / ST / T+1 / lot size / price limits / adjustment
• reference/us_stock_rules.md — for U.S. stocks
• reference/hong_kong_rules.md — for Hong Kong stocks
• reference/export_results.py — called by default after the backtest
• examples/*.py — when the query is clearly a known pattern such as moving averages / grid strategy
• reference/dashboard_schema.md — when generating a dashboard (JSON format, module types, replacement method)
• reference/render_dashboard.py — copyable dashboard example
• reference/dashboard_locales.py — usually not needed for a standard dashboard; read it only when customizing visible copy or adding new modules. Copy it together when reusing render_dashboard.py
• reference/dashboard_template.html — do not read (2000+ lines of CSS/JS intended for the browser; code only needs open + replace)

Core Rules

First Decide: Strategy Backtest or Event Study?

Mandatory Checklist by Scenario (Missing Items = Unreliable Results / Broken Dashboard)

After classifying the task, check the list below item by item. Each item points to where the detailed rule lives.

Mandatory for strategy backtests:

• Handle warmup exactly as defined in the "Warmup vs Evaluation Window" section: load earlier data, gate the evaluation start, and pass export_results(..., start=..., end=...)
• Handle suspension NaNs (see the suspension / mid-sample NaN section in pitfalls/pandas.md)
• Parameterize commissions and deduct them from PnL / equity (see the fees section in pitfalls/pandas.md)
• Force liquidation at the end of the sample (see the open-position handling section in pitfalls/pandas.md)
• Execute signals at next-day open (pending-signal pattern; prevents look-ahead)
• For A shares, pass market="china_a" so short trades hard-fail

Mandatory for event studies:

• Every event must have a non-empty label field (for example "PBOC rate cut by 25bp") — by default the main chart draws one marker per event row; without a label the user cannot interpret it
• Do not simulate cash / position / pending signals; compute pnl_pct = (sell/buy - 1) * 100 directly
• Both the reply and the dashboard must use event-level metrics: average / median / win rate / best / worst event; do not report Sharpe / annualized return / max drawdown
• Use event-level metrics in metric_table, and custom columns in trades_table (event / buy date / sell date / return)
• Event-study dashboards must pass event_overview_mode explicitly instead of relying on inference: for average / median / win rate / best / worst event questions, pass event_overview_mode="stats"; for cumulative performance / curve / time-evolution questions, pass event_overview_mode="timeline"; if you want both stats and time evolution visible, pass event_overview_mode="both"
• If the user's first question did not explicitly ask for cumulative / curve / time-evolution output and the current reply stays in stats mode, add one final sentence offering it: for example, "If you also want cumulative performance / a curve / time evolution, I can add a timeline view as well."
• If an overview_chart exists, validate before rendering that the number of displayable event markers equals the number of event rows where show_marker != False. If not, it means event_date (default = entry_date, but it may also be explicitly anchored to exit_date) does not align to chart points.date
• Do not call export_results; export requirements are defined in the "Standard Output Files" section and the event-study section of dashboard_schema.md

For event-study implementation, remember only two things:

• Do not model cash / position / pending signals; each event should directly become one trade row, with pnl_pct and label as the core fields
• Statistics, reply text, and the dashboard all use event-level interpretation; do not quote portfolio-level summary metrics
• If the dashboard directly calls build_dashboard_data(...), event studies must pass event_overview_mode="stats", "timeline", or "both" explicitly. In timeline/both mode, if no equity_curve is passed, a cumulative event PnL curve is synthesized from trade_history

for event in events:
    buy_price = df.loc[buy_date, 'open']
    sell_price = df.loc[sell_date, 'close']
    return_pct = (sell_price / buy_price - 1) * 100
    trades.append({"entry_date": buy_date, "exit_date": sell_date,
                   "entry_price": buy_price, "exit_price": sell_price,
                   "pnl_pct": return_pct, "label": event_desc, ...})

How to Write Strategy-Backtest Code

• Use pure Python + pandas; do not use any backtesting framework
• The LLM is free to choose the code structure, but it must follow the patterns below:

Separate signal generation from execution (the core anti-look-ahead mechanism):

bar i: generate signals using current and past data -> store in pending_buy / pending_sell
bar i+1: execute pending signals using the open price

Do not "see the signal and fill immediately on the same bar" — on daily bars, that is effectively using the close as an execution price and is a look-ahead shortcut. The code structure should look like this:

for i in range(len(df)):
    row = df.iloc[i]
    # 1. Execute yesterday's pending signal first
    if pending_buy:
        price = row['open']  # next-day-open fill
        ...
        pending_buy = False
    # 2. Generate today's signal (to be executed tomorrow)
    if buy_condition:
        pending_buy = True
    # 3. Record equity
    equity_curve.append({"date": date, "value": cash + position * row['close']})

Indicator calculation: use pandas vectorization. Do not hand-write for loops for MA / RSI / ATR:

df['ma20'] = df['close'].rolling(20).mean()
df['rsi'] = ...  # can be written by hand or via ta-lib

rolling() creates NaNs for the first N-1 rows. Signal generation must skip them (for example if pd.isna(row['ma20']): continue).

Equity calculation: record account equity at the end of every bar. For simple single-name long-only strategies, cash + position * close is fine; for cash equity / ETF rotation, portfolio, rebalancing, short, and leverage strategies, prefer the unified form cash + Σ(position_i × close_i). Represent short exposure with negative position size. If margin borrowing, stock borrow, or other leverage-related liabilities are not already reflected in cash, rewrite it as cash + Σ(position_i × close_i) - liabilities. Financing interest, borrow fee, and other costs must be explicitly reflected in cash or liabilities; do not leave them implicit. This convention does not automatically cover futures, options, perpetuals, or other derivatives. Do not just write "record daily equity" without explaining the accounting convention.

Fees: subtract buy_commission at buy time, and sell_commission + sell_tax at sell time. Use parameterized design (do not hardcode market-specific rates). PnL must be net of fees. See the fee section in pitfalls/pandas.md.

Trade records: every time a position is closed, append to trade_history. Fields must include: entry_date, exit_date, side, size, entry_price, exit_price, pnl, pnl_pct, holding_bars, symbol. PnL is net after commission. Records must be written after execution, not when the signal is generated (see pitfalls/pandas.md). For A shares / Hong Kong stocks, if the stock name is known, prefer writing symbol_name inside trade_history.append({...}) in the generated code; if the code only has name / stock_name / security_name / display_name, export_results will normalize those aliases into the standard display fields, but do not rely on that fallback instead of the standard key. Final dashboard display still follows the language lock: under English output, China / Hong Kong stocks should default to ticker code; under Chinese output, known Chinese names should stay in Chinese.

Forced liquidation at the end: if there is still an open position on the final bar, by default close it at the final bar's close, record a trade, and subtract fees. In the final reply, explicitly say "the last trade is an end-of-sample forced close".

Golden cross / death cross: use the (shift(1) <=) & (current >) pattern to detect the crossing moment. Do not mistake a persistent state for an event.

Strategy Logic

Warmup Segment vs Evaluation Segment (Mandatory for Indicator Strategies)

If the user says "Backtest the 2024 MA120 strategy", then 2024-01-01 is the evaluation start, not the data-load start. The first 119 rows of MA120 are NaN, so if you only load from the evaluation start, the first four months will have no valid signal. You must load an earlier warmup segment.

1. Data-load start = evaluation start - max(indicator_window) × 1.5 (rule of thumb; MA120 -> 180 days earlier; EMA200 -> 300 days earlier; MA5 / MA10 only -> 15 days earlier). When calling the data source, start_date must use this earlier date, not the user-facing backtest range start
2. Warmup bars must not create trading side effects, but they are not forbidden from updating all state. Before the evaluation start, bars may continue to update indicators, streak counters, highest_since_entry, and similar pure historical state. But they must not create trades / equity records, and they must not create future-changing side effects such as pending_buy/pending_sell=True or cash/position changes
3. equity_curve and trade_history should only record evaluation-window data. When calling export_results(), you must pass start / end (= the evaluation window), so Sharpe / annualized return / total return / max drawdown are recomputed on the sliced evaluation window and not polluted by warmup

See reference/pitfalls/pandas.md for the full code skeleton and three typical wrong patterns.

Other Strategy Rules

• Under compound entry conditions, "reverse signal / reverse position" should by default be interpreted as the full mirrored condition. If ambiguous, clarify first
• When the user asks to "write the .py file and run it", the deliverable should be self-contained and runnable in the current environment. Do not hardcode personal paths and do not silently depend on undeclared external CSV files
• By default, save the backtest implementation as a .py script so it can be run with python <script>.py, inspected with rg/grep, adversarially reviewed, and reproduced later
• If the script depends on existing local CSV files, do not assume the filename must equal symbol; maintain an explicit symbol -> file_path mapping, or read the symbol from file contents
• The formal export contract is defined in the "Standard Output Files" section. Strategy backtests must use export_results(). Event studies must not. Whether a dashboard is generated is governed by the "HTML Dashboard" section
• All output languages must be consistent, and they must follow the user's query / explicit language request rather than the market. Do not rely on implicit Chinese fallback: dashboard generation must explicitly pass build_dashboard_data(..., language="zh"|"en")
• Under English output, any Chinese stock name should be replaced by ticker code; under Chinese output, known Chinese stock names should be shown in Chinese
• For A shares, default to 100-share lots and T+1. Do not impose these rules on non-A-share markets
• U.S. stocks default to 1-share minimum and no A-share-style T+1. If the strategy includes short selling, it is allowed by default, but do not automatically model borrow fee / locate / SSR. See reference/us_stock_rules.md
• Hong Kong stocks do not default to A-share-style T+1, but they also should not be treated like unconstrained U.S.-style short-selling. board lot is issuer-specific, and the fee structure is not equivalent to a single commission. See reference/hong_kong_rules.md
• Individual A-share stocks are long-only by default. If the user explicitly asks for A-share shorting, you must clarify first (see the three A-share shorting paths in "Decide First: Do You Need Clarification?"). Do not silently implement it
• For A-share long-only export parameters, follow the "Standard Output Files" section. If the user explicitly confirms the "theoretical backtest ignoring securities-lending constraints" path, then do not pass market="china_a" so short trades can pass — but this must be explicitly disclosed in the reply
• Short naming convention: strategies that contain short exposure (U.S./Hong Kong compliant shorting, or theoretical A-share shorting) must use the following field conventions. Otherwise dashboard rendering and export validation break:
  • trade_history[i].side: "long" for long trades (default), "short" for short trades
  • dashboard marker action: "buy" for opening a long, "sell" for closing a long, "short" for opening a short, "cover" for closing a short
  • the dashboard template recognizes these four actions and renders the corresponding marker types; side="short" is displayed as a short-side pill in trades_table

Assumptions and Bias (Fold into A/B in the Final Reply)

• Do not create a separate fourth section; fold it into the A/B sections above
• Implementation choices belong to A. At minimum, check and explain the following items when relevant:
  • Position-sizing rule (% of equity / fixed amount / lot-based / full position)
  • Fees / slippage / stamp duty (default 0 for event-study-style tasks)
  • Holding-period definition (calendar days / trading days; whether entry day is included)
  • Execution timing (next-day open / same-day close)
  • Lot-size rule (A shares 100-share lots / Hong Kong board lot / U.S. 1 share)
  • Universe source, snapshot date, whether survivor bias exists
  • Adjustment method (A shares / Hong Kong default = forward-adjusted; U.S. default = adjustment-consistent OHLC; write N/A if it cannot be proven from the data source)
• Reliability biases belong to B: survivor bias, look-ahead, data coverage, warmup slicing

Self-Check (Mandatory After Coding)

All 4 steps must be completed before delivery. Step 3 cannot be skipped — the checklist always lags behind, and adversarial review is there to catch bugs the checklist did not cover. Step 4 cannot be skipped — code without bugs still does not guarantee a correct dashboard.

Step 1: Operability

1. Run in cwd: python <script>.py. Fix any error immediately
2. Three files exist: ls *_equity.csv *_trades.csv *_summary.json. All must exist and be non-empty

Step 2: The 5 Key Checks

Run the 5-item checklist at the end of reference/common_pitfalls.md. Item 1 is matched against the user's original words; the rest are verified via grep or direct checks.

Step 3: Sanity Check + Adversarial Review

If a number is outside common sense, you must find the root cause before delivery:

Inspect the first 5 and last 5 rows of trades.csv: entry-price magnitude (Moutai should be around 1500, not 13000, or size may silently round to zero), holding-period distribution (all 1s or all identical values are suspicious), side (A-share long-only should not have short), and whether the first trade date falls inside the evaluation window.

If there is a buy-and-hold baseline: total return should be in the same order of magnitude as buy-and-hold (a 10x difference almost always means a bug). If the strategy is much better than buy-and-hold, you must be able to explain why.

Adversarial review: look for bugs the checklist did not cover. Temporarily forget the checklist and assume there is exactly one bug somewhere in the code. Read through the code from the top and ask four questions on every line:

• Production realism: could this data be known at decision time tomorrow? Is any time t decision using information from time > t?
• Boundary values: what happens when a variable is None / 0 / nan / negative / empty list? Is it silently swallowed or does it raise?
• Mental arithmetic: can the result of this line be checked by hand? If PnL = 100, can you reverse it from entry price / exit price / size?
• Prompt sensitivity: if one word in the prompt changes ("open" -> "close", "daily" -> "weekly", "liquidate fully" -> "sell half"), is this line still correct?

High-risk auxiliary logic (the signal itself is often fine; the bug usually hides here):

• Is size calculation using future data (shift(-N) / iloc[i+1])? It should estimate size using the current bar's close
• Is stop-loss / take-profit based on close or high/low? Is the basis the entry price? Is simultaneous-trigger priority defined for the same bar?
• Is trailing-stop highest price updated before the stop check? That would miss valid triggers
• Warmup segment: are gating and start/end slicing handled exactly as defined in "Warmup vs Evaluation Window"?
• Does lot rounding produce size = 0 with no explicit guard?
• Multi-strategy switching: when the higher-priority signal triggers, is the lower-priority holding handled correctly?
• Does a rebalance-frequency constraint belong to one strategy, or was it accidentally applied globally?

If in doubt, verify: run a minimal reproduction, grep it, compare with examples. Do not rely on mental confidence alone.

Hard constraint: if adversarial review concludes "I did not find anything", you must still list at least 3 things you suspected and ruled out. If you cannot list 3, redo the review.

Bottom line: if any step fails, do not deliver.

Step 4: Local-Render Dashboard Self-Check

If a dashboard is part of the deliverable, then after writing index.html to cwd you must complete the "[Mandatory] Local-Render Self-Check" checklist from the HTML Dashboard section (rendering integrity + content compliance + performance). You must not hand the file path to the user before this is done. This is an extension of self-check: bug-free code does not guarantee correct presentation.

• If output_language="en", add one more check: both the final reply and the dashboard must contain no Chinese user-visible text; China / Hong Kong stocks can simply be displayed as ticker codes.

Standard Output Files (Formal Export Contract)

First distinguish the scenario:

• Strategy backtest: after the backtest completes, always generate 3 files into the current working directory (cwd). Use a prefix such as ma_cross_600519
• Event study: do not use the portfolio-style summary export. Write trades.csv manually, and compute event-level metrics from pnl_pct. Do not fabricate Sharpe / annualized return / max drawdown

The 3 standard files for strategy backtests are:

Implementation for strategy backtests: call reference/export_results.py via export_results(equity_curve, trade_history, prefix, initial_cash, start, end, market):

• equity_curve: [{"date": "2024-01-02", "value": 1000000.0}, ...]
• trade_history: [{"entry_date": ..., "exit_date": ..., "side": "long", "size": 100, "symbol": "600519.SH", "symbol_name": "Kweichow Moutai", ...}, ...]
• If warmup exists, the start/end logic is defined in the "Warmup vs Evaluation Window" section. Export will slice to the evaluation window and recompute Sharpe / annualized return / total return / max drawdown
• For A shares, pass market="china_a" to trigger short hard-fail
• Files must be written directly into cwd; do not create a subdirectory

HTML Dashboard

Unified UI Iron Rules (Violation = Invalid Output)

The model does not need to read dashboard_template.html itself (2000+ lines of CSS/JS are for the browser). It only needs to build the report_data dict and call render_dashboard(report_data, output_path, template_path).

Naming rule:

• In the single-HTML case, the final main dashboard file name is fixed to index.html
• If multiple HTML files are truly needed, the entry page must still be named index.html; only the detail pages may use per-symbol / per-strategy names

Single HTML vs Multiple HTML Files

This section is layout strategy and takes precedence here. reference/dashboard_schema.md mainly defines module schema, field semantics, and recipes for non-typical backtests.

Default recommendation: single HTML + tabs

• Use ui.tabs to configure multiple tabs, one per symbol
• Main-chart choice: for portfolio-style / natural-mainline cases (position weights, rebalancing, multi-symbol rotation — dynamically rotating across N symbols under one strategy), use overview_chart to draw the portfolio NAV as the main line, optionally with overlay_series as supporting lines. For peer comparison / no natural main line cases (one strategy across many stocks, or many strategies on one stock), use line_chart (peer lines) + metric_table (one comparison object per column). Do not force such cases into overview_chart, because that visually promotes one series into the "main line." Rotation strategies must not be misread as peer comparisons; the portfolio-level NAV is the true mainline
• Standard layout for peer-comparison scenarios (hard rule) — applies to both "many stocks, one strategy" and "many strategies, one stock":
  • Tab 1 "Comparison" (ui.active_tab by default): line_chart multi-line comparison + metric_table KPI comparison by column (event studies use event-level metrics; strategy backtests use Sharpe / return / drawdown, etc.)
  • Tab 2+ one tab per comparison target: overview_chart for that target's equity curve (with buy/sell markers and drawdown pane) + trades_table for its detailed trades
  • You may not provide only the comparison chart without per-target detail, because users will want to click into one specific line
• Best fit when the number of symbols is <= 10, content complexity is moderate, and the file stays under 5 MB

Multiple HTML files are allowed (model decides)

• When the symbol count is large, a single page is overloaded, or each symbol requires a fully independent detailed view
• Each symbol HTML must still be rendered through dashboard_template.html
• Navigation / index page (if needed) must also be rendered through dashboard_template.html, using standard modules such as:
  • metric_table — side-by-side comparison across symbols
  • custom_html — card grid, link list (DOM class names must use the bt-custom- prefix)
  • overview_chart + `ove

…(truncated)