meta: id: finance-bp-124-v5.3 version: v6.1 blueprint_id: finance-bp-124 sop_version: crystal-compilation-v6.1 source_language: en compiled_at: '2026-04-22T13:01:01.570350+00:00' target_host: openclaw authoritative_artifact: primary: seed.yaml non_authoritative_derivatives: - SKILL.md (host-generated summary, may lag) - HEARTBEAT.md (host telemetry) - memory/*.md (host conversational memory) rule: On any behavioral decision (preconditions check, OV assertion, EQ rule firing, spec_lock verification), agents MUST re-read seed.yaml. Derivatives are for UI display only and may be out-of-date. execution_protocol: install_trigger: - Execute resources.host_adapter.install_recipes[] in declared order - Verify each package with import check before proceeding execute_trigger: When user intent matches intent_router.uc_entries[].positive_terms AND user uses action verb (run/execute/跑/执行/backtest/fetch/collect) on_execute: - Reload seed.yaml (do not rely on SKILL.md or cached summaries) - Run preconditions[] in declared order; halt on first fatal failure with on_fail message to user - Enter context_state_machine.CA1_MEMORY_CHECKED state - Evaluate evidence_quality.enforcement_rules[]; prepend user_disclosure_template - Translate user_facing_fields to user locale per locale_contract - "[V6 READING ORDER]\nThis crystal contains the following V6 layers. Before answering any business question, the host\ \ MUST read them in order:\n 1. anti_patterns[] — cross-project anti-patterns (with AP-* ids)\n 2. cross_project_wisdom[]\ \ — cross-project wisdom (with CW-* ids)\n 3. domain_constraints_injected[] — domain constraints (SHARED-* ids)\n \ \ 4. known_use_cases[] — concrete business scenarios (KUC-* ids)\n 5. component_capability_map — AST component map\ \ (by module)\n\nWhen answering user questions, proactively cite relevant AP-*/CW-*/SHARED-*/KUC-* ids with source text.\ \ Examples: T+1 rules -> cite SHARED-* constraint; model comparison -> warn via AP-*; follow-holdings strategy -> cite\ \ KUC-* with example file." workspace_resolution: scripts_path: '{host_workspace}/scripts/' skills_path: '{host_workspace}/skills/' trace_path: '{host_workspace}/.trace/' capability_tags: markets: - global activities: - derivatives-pricing upgraded_from: finance-bp-124-v1.seed.yaml upgraded_at: '2026-04-22T13:20:34.223301+00:00' v6_inputs: ast_mind_map: knowledge/sources/finance/finance-bp-124--arch/v6_inputs/ast_mind_map.yaml anti_patterns: null cross_project_wisdom: null examples_kuc: knowledge/sources/finance/finance-bp-124--arch/v6_inputs/examples_kuc.yaml shared_pools_dir: knowledge/sources/finance/_shared anti_patterns: - id: AP-DERIVATIVES-PRICING-001 title: Instrument NPV called without attached pricing engine description: Calling NPV() on a derivatives instrument without first calling setPricingEngine() returns uninitialized garbage values or throws null pointer exceptions. This occurs because the Instrument class relies on the attached PricingEngine to perform actual valuation logic. The consequence is silently incorrect pricing results that appear valid, potentially leading to bad trading decisions. project_source: QuantLib-SWIG (finance-bp-123) severity: high applicable_to_tags: markets: - global activities: - derivatives-pricing _source_file: anti-patterns/derivatives-pricing.yaml - id: AP-DERIVATIVES-PRICING-002 title: BSM forward price ignores dividend yield description: When calculating option prices on dividend-paying stocks using BSM, the forward price must be adjusted as F = S * exp((r-q)*t). Omitting the dividend yield adjustment (using F = S * exp(r*t)) causes systematic mispricing for all dividend-paying assets. The consequence is consistently wrong option prices that diverge from market prices, leading to arbitrage opportunities and trading losses. project_source: py_vollib (finance-bp-127) severity: high applicable_to_tags: markets: - global activities: - derivatives-pricing _source_file: anti-patterns/derivatives-pricing.yaml - id: AP-DERIVATIVES-PRICING-003 title: Negative discount factors passed to log-domain interpolation description: When Numba-jitted interpolation functions perform log transformation on discount factors, negative or zero values cause domain errors. This occurs because log(-x) and log(0) are mathematically undefined. The consequence is runtime crashes in jitted functions and complete failure of discount curve interpolation, blocking all downstream pricing calculations. project_source: FinancePy (finance-bp-101) severity: high applicable_to_tags: markets: - global activities: - derivatives-pricing _source_file: anti-patterns/derivatives-pricing.yaml - id: AP-DERIVATIVES-PRICING-004 title: Non-monotonic time points in discount curve interpolation description: Interpolation over non-monotonically increasing time points produces undefined behavior at crossing times, causing discount factors to be incorrectly computed where time values overlap. This corrupts the entire term structure because the bootstrap algorithm cannot determine which discount factor corresponds to which maturity. The consequence is incorrect present value calculations across all downstream products priced against the curve. project_source: FinancePy (finance-bp-101) severity: high applicable_to_tags: markets: - global activities: - derivatives-pricing _source_file: anti-patterns/derivatives-pricing.yaml - id: AP-DERIVATIVES-PRICING-005 title: Bootstrap calibration instruments not in maturity order description: When building yield curves from market instruments (deposits, FRAs, swaps), the instruments must be provided in strictly increasing maturity order. Out-of-order instruments cause the bootstrap algorithm to solve for discount factors at incorrect time points, corrupting the entire term structure. The consequence is wrong forward rates and discount factors that propagate into all priced instruments. project_source: FinancePy (finance-bp-101) severity: high applicable_to_tags: markets: - global activities: - derivatives-pricing _source_file: anti-patterns/derivatives-pricing.yaml - id: AP-DERIVATIVES-PRICING-006 title: Option Exercise type mismatches VanillaOption constructor description: VanillaOption requires both a StrikedTypePayoff and a matching Exercise object. Using wrong Exercise type (e.g., AmericanExercise for European option) causes compilation failures in C++ or runtime errors in SWIG bindings. The consequence is the pricing system cannot initialize options, blocking all option pricing workflows. project_source: QuantLib-SWIG (finance-bp-123) severity: high applicable_to_tags: markets: - global activities: - derivatives-pricing _source_file: anti-patterns/derivatives-pricing.yaml - id: AP-DERIVATIVES-PRICING-007 title: NaN/inf values in ARCH model input data description: ARCH model estimation relies on recursive variance computations and scipy optimize. Non-finite input values (NaN, inf) cause optimizers to produce NaN results and recursive variance calculations to fail. The consequence is complete model estimation failure with meaningless outputs that appear valid, leading to incorrect volatility forecasts and risk misestimation. project_source: arch (finance-bp-124) severity: high applicable_to_tags: markets: - global activities: - derivatives-pricing _source_file: anti-patterns/derivatives-pricing.yaml - id: AP-DERIVATIVES-PRICING-008 title: ARCH parameter array concatenation in wrong order description: 'ARCHModel composes from three components (mean, volatility, distribution) and requires parameter arrays concatenated in fixed order: [mean_params, volatility_params, distribution_params]. Incorrect ordering causes _parse_parameters to assign wrong values to wrong components, producing mathematically invalid models (e.g., volatility parameters interpreted as distribution parameters). The consequence is invalid conditional variance forecasts.' project_source: arch (finance-bp-124) severity: high applicable_to_tags: markets: - global activities: - derivatives-pricing _source_file: anti-patterns/derivatives-pricing.yaml - id: AP-DERIVATIVES-PRICING-009 title: Zero or negative time-to-expiration in option pricing description: Option pricing formulas (Black-Scholes, Black model) compute sqrt(t) in the denominator. Zero time causes division by zero; negative time produces NaN in d1/d2 calculations. The consequence is invalid option prices (NaN, inf) that break downstream Greeks calculations and hedging workflows. project_source: py_vollib (finance-bp-127) severity: high applicable_to_tags: markets: - global activities: - derivatives-pricing _source_file: anti-patterns/derivatives-pricing.yaml - id: AP-DERIVATIVES-PRICING-010 title: Black model applies spot price instead of forward price description: The Black model is designed for options on futures/forwards and expects futures price F as input, not spot price S. Using spot directly causes incorrect pricing because the Black formula assumes the underlying follows geometric Brownian motion with drift equal to the risk-free rate (i.e., forward dynamics). The consequence is systematically wrong forward option prices. project_source: py_vollib (finance-bp-127) severity: high applicable_to_tags: markets: - global activities: - derivatives-pricing _source_file: anti-patterns/derivatives-pricing.yaml - id: AP-DERIVATIVES-PRICING-011 title: Missing discount factor in Black model pricing description: Black model pricing must apply time value discounting with deflater = exp(-r*t) to undiscounted option prices. Omitting the discount factor produces forward option prices that exceed their fair value by the risk-free compounding amount. The consequence is violation of time value of money principles and prices that cannot be used for fair valuation or hedging. project_source: py_vollib (finance-bp-127) severity: medium applicable_to_tags: markets: - global activities: - derivatives-pricing _source_file: anti-patterns/derivatives-pricing.yaml - id: AP-DERIVATIVES-PRICING-012 title: Invalid flag parameter ('c'/'p') passed to py_vollib without validation description: py_vollib binary_flag dict only contains keys 'c' and 'p'. Passing any other flag value causes KeyError exception. The library lacks input validation and crashes on invalid inputs. The consequence is unhandled exceptions in production systems when flag values come from external sources with unexpected formats. project_source: py_vollib (finance-bp-127) severity: medium applicable_to_tags: markets: - global activities: - derivatives-pricing _source_file: anti-patterns/derivatives-pricing.yaml - id: AP-DERIVATIVES-PRICING-013 title: Evaluation date not set before QuantLib term structure construction description: QuantLib requires ql.Settings.instance().evaluationDate to be set before constructing yield term structures and instruments. Without an explicit evaluation date, the curve reference date becomes undefined, causing date calculations to fail or produce incorrect settlement dates. The consequence is wrong discount factors and NPV calculations across the entire portfolio. project_source: QuantLib-SWIG (finance-bp-123) severity: medium applicable_to_tags: markets: - global activities: - derivatives-pricing _source_file: anti-patterns/derivatives-pricing.yaml - id: AP-DERIVATIVES-PRICING-014 title: Market quotes passed without QuoteHandle wrapper description: QuantLib's observer pattern requires all market quotes to be wrapped in QuoteHandle before passing to rate helpers. Raw quote values bypass the observable notification mechanism, causing dependent instruments to never recalculate when market data updates. The consequence is stale pricing that doesn't reflect current market conditions. project_source: QuantLib-SWIG (finance-bp-123) severity: medium applicable_to_tags: markets: - global activities: - derivatives-pricing _source_file: anti-patterns/derivatives-pricing.yaml - id: AP-DERIVATIVES-PRICING-015 title: Implied volatility computed without proper bounds validation description: When computing implied volatility, option prices outside theoretical bounds (below intrinsic value or above maximum) must raise appropriate exceptions. Returning invalid IV values (negative volatility or extreme values) violates mathematical definitions and leads to incorrect pricing, risk calculations, and hedging ratios. The consequence is systemic pricing errors across all vol-dependent derivatives. project_source: py_vollib (finance-bp-127) severity: medium applicable_to_tags: markets: - global activities: - derivatives-pricing _source_file: anti-patterns/derivatives-pricing.yaml cross_project_wisdom: - wisdom_id: CW-DERIVATIVES-PRICING-001 source_project: FinancePy, QuantLib-SWIG pattern_name: Strict input validation before financial calculations description: Both FinancePy and QuantLib-SWIG enforce strict validation of all input parameters before any financial computation. FinancePy validates day count types, date arguments, tolerance parameters, and max iterations. QuantLib-SWIG validates exercise types and swap direction enums. This pattern prevents corrupted calculations and provides clear error messages. Apply this pattern by validating all inputs at function entry points. applicable_to_activity: derivatives-pricing _source_file: cross-project-wisdom/derivatives-pricing.yaml - wisdom_id: CW-DERIVATIVES-PRICING-002 source_project: FinancePy, QuantLib-SWIG pattern_name: Bootstrap requires ordered instrument calibration description: Both FinancePy and QuantLib-SWIG require calibration instruments to be provided in strict maturity order for curve bootstrapping. FinancePy enforces monotonically increasing time points and validates instrument sequencing (deposits before FRAs before swaps). QuantLib-SWIG uses bootstrap helpers (DepositRateHelper, FraRateHelper, SwapRateHelper) that assume ordered inputs. This ensures the bootstrap algorithm solves for discount factors at mathematically correct time points. applicable_to_activity: derivatives-pricing _source_file: cross-project-wisdom/derivatives-pricing.yaml - wisdom_id: CW-DERIVATIVES-PRICING-003 source_project: QuantLib-SWIG pattern_name: Handle pattern for lazy evaluation chains description: QuantLib-SWIG requires wrapping market data (quotes, term structures) in Handle objects to enable lazy evaluation and automatic recalculation. QuoteHandle for market quotes and Handle for term structures enable the observer pattern. When market data updates, all dependent instruments automatically recalculate. This pattern is essential for live pricing systems where prices must reflect current market conditions. applicable_to_activity: derivatives-pricing _source_file: cross-project-wisdom/derivatives-pricing.yaml - wisdom_id: CW-DERIVATIVES-PRICING-004 source_project: arch pattern_name: Parameter composition requires fixed ordering and partitioning description: arch enforces a strict parameter composition pattern where mean, volatility, and distribution parameters must be concatenated in fixed order with explicit offset partitioning. The offsets array partitions the unified parameter vector into components. This pattern prevents parameter assignment errors that would corrupt model components. Apply this when composing financial models from multiple sub-components. applicable_to_activity: derivatives-pricing _source_file: cross-project-wisdom/derivatives-pricing.yaml - wisdom_id: CW-DERIVATIVES-PRICING-005 source_project: arch, py_vollib pattern_name: Strict mathematical constraint enforcement description: 'Both arch and py_vollib enforce strict mathematical constraints: arch enforces volatility model stationarity constraints (A.dot(params) - b >= 0) for SLSQP optimization; py_vollib validates implied volatility is positive and option prices within intrinsic/maximum bounds. Violating these constraints produces mathematically invalid results. Always enforce domain constraints on all financial model parameters.' applicable_to_activity: derivatives-pricing _source_file: cross-project-wisdom/derivatives-pricing.yaml - wisdom_id: CW-DERIVATIVES-PRICING-006 source_project: py_vollib pattern_name: Forward price adjustment for dividend yield in BSM description: 'py_vollib demonstrates the correct BSM implementation: compute forward price F = S * exp((r-q)*t) to adjust for continuous dividend yield before passing to the pricing engine. This pattern is essential for all options on dividend-paying assets. Forgetting the dividend adjustment causes systematic mispricing for the entire equity derivatives book.' applicable_to_activity: derivatives-pricing _source_file: cross-project-wisdom/derivatives-pricing.yaml - wisdom_id: CW-DERIVATIVES-PRICING-007 source_project: FinancePy pattern_name: Monotonicity validation for interpolation arrays description: FinancePy enforces strictly monotonically increasing time arrays before interpolation operations. This prevents undefined behavior at crossing times and ensures each time point maps to exactly one discount factor. Apply this validation whenever implementing interpolation over financial time series (discount curves, volatility surfaces, forward rates). applicable_to_activity: derivatives-pricing _source_file: cross-project-wisdom/derivatives-pricing.yaml - wisdom_id: CW-DERIVATIVES-PRICING-008 source_project: py_vollib pattern_name: Production vs reference implementation selection description: py_vollib explicitly distinguishes between ref_python (slow, educational) and production (fast, C-based lets_be_rational) implementations. Using the reference implementation in production causes 10-100x performance degradation. Always select the appropriate implementation tier based on use case requirements—reference for testing/education, optimized for production trading systems. applicable_to_activity: derivatives-pricing _source_file: cross-project-wisdom/derivatives-pricing.yaml domain_constraints_injected: [] resources_injected: {} known_use_cases: - kuc_id: KUC-101 source_file: examples/bootstrap_examples.ipynb business_problem: Computes statistical inference (confidence intervals, standard errors) for the Sharpe Ratio using bootstrap methods to quantify uncertainty in risk-adjusted performance metrics. intent_keywords: - bootstrap - sharpe ratio - statistical inference - confidence intervals - stationary bootstrap stage: factor_computation data_domain: financial_data type: research_analysis - kuc_id: KUC-102 source_file: examples/multiple-comparison_examples.ipynb business_problem: Compares 500 predictive models against a benchmark using the Superior Predictive Ability (SPA) test to determine if any models significantly outperform the benchmark. intent_keywords: - model comparison - SPA test - multiple models - benchmark comparison - superior predictive ability stage: factor_computation data_domain: financial_data type: research_analysis - kuc_id: KUC-103 source_file: examples/unitroot_cointegration_examples.ipynb business_problem: Tests for cointegration relationships between WTI and Brent crude oil prices to identify mean-reverting spread opportunities using Engle-Granger and Phillips-Ouliaris tests. intent_keywords: - cointegration - unit root - ADF test - Engle-Granger - oil prices - mean reversion stage: factor_computation data_domain: financial_data type: research_analysis - kuc_id: KUC-104 source_file: examples/unitroot_examples.ipynb business_problem: Tests for stationarity in credit spreads (BAA-AAA) using Augmented Dickey-Fuller tests to determine if mean-reversion trading strategies are applicable. intent_keywords: - unit root - ADF test - stationarity - credit spread - mean reversion stage: factor_computation data_domain: financial_data type: research_analysis - kuc_id: KUC-105 source_file: examples/univariate_forecasting_with_exogenous_variables.ipynb business_problem: Forecasts univariate time series using Autoregressive models with exogenous variables (ARX) to capture the impact of external factors on the target variable. intent_keywords: - ARX - exogenous variables - forecasting - autoregressive - regression stage: factor_computation data_domain: financial_data type: research_analysis - kuc_id: KUC-106 source_file: examples/univariate_using_fixed_variance.ipynb business_problem: Demonstrates how to specify a HARX mean model with fixed/external variance inputs and iteratively fit volatility models using the estimated conditional volatility. intent_keywords: - fixed variance - HARX - volatility modeling - GARCH - VIX stage: factor_computation data_domain: financial_data type: research_analysis - kuc_id: KUC-107 source_file: examples/univariate_volatility_forecasting.ipynb business_problem: Forecasts future volatility of S&P 500 returns using GARCH models, including multi-step ahead forecasts and rolling window out-of-sample predictions. intent_keywords: - GARCH - volatility forecasting - S&P 500 - conditional variance - out-of-sample stage: factor_computation data_domain: financial_data type: research_analysis - kuc_id: KUC-108 source_file: examples/univariate_volatility_modeling.ipynb business_problem: Fits and compares different GARCH volatility model specifications (symmetric, asymmetric, power) with various error distributions to characterize S&P 500 return volatility dynamics. intent_keywords: - GARCH - volatility modeling - S&P 500 - model comparison - asymmetric GARCH - t-distribution stage: factor_computation data_domain: financial_data type: research_analysis - kuc_id: KUC-109 source_file: examples/univariate_volatility_scenarios.ipynb business_problem: Generates multiple volatility scenarios for NASDAQ returns using simulation-based forecasting methods, useful for risk management and option pricing applications. intent_keywords: - volatility scenarios - simulation - NASDAQ - GARCH - scenario analysis - risk management stage: factor_computation data_domain: financial_data type: research_analysis component_capability_map: project: finance-bp-124--arch scan_date: '2026-04-22' stats: total_files: 7 total_classes: 40 total_functions: 0 total_stages: 7 modules: data_input_&_validation: class_count: 4 stage_id: data_input stage_order: 1 responsibility: Accept time series data (numpy/pandas), validate finiteness, convert to contiguous float64 arrays for core computation. Provides type flexibility while ensuring memory layout efficiency for downstream numeric operations. classes: - name: ARCHModel.__init__ file: data_input_&_validation/archmodel-init.py line: 0 kind: required_method signature: '' - name: ensure1d file: data_input_&_validation/ensure1d.py line: 0 kind: required_method signature: '' - name: to_array_1d file: data_input_&_validation/to-array-1d.py line: 0 kind: required_method signature: '' - name: Input type coercion file: data_input_&_validation/input-type-coercion.py line: 0 kind: replaceable_point design_decision_count: 2 model_specification: class_count: 7 stage_id: model_specification stage_order: 2 responsibility: Allow users to compose mean model + volatility process + distribution as pluggable components. Each component implements a common interface for unified likelihood computation and forecasting. classes: - name: ARCHModel.fit file: model_specification/archmodel-fit.py line: 0 kind: required_method signature: '' - name: ARCHModel.forecast file: model_specification/archmodel-forecast.py line: 0 kind: required_method signature: '' - name: GARCH.__init__ file: model_specification/garch-init.py line: 0 kind: required_method signature: '' - name: HARX.__init__ file: model_specification/harx-init.py line: 0 kind: required_method signature: '' - name: Mean model file: model_specification/mean-model.py line: 0 kind: replaceable_point - name: Volatility model file: model_specification/volatility-model.py line: 0 kind: replaceable_point - name: Distribution file: model_specification/distribution.py line: 0 kind: replaceable_point design_decision_count: 5 parameter_estimation: class_count: 5 stage_id: parameter_estimation stage_order: 3 responsibility: Jointly estimate mean+volatility+distribution parameters via constrained maximum likelihood. Uses SLSQP with bounds and inequality constraints derived from stationarity/coerciveness requirements. classes: - name: ARCHModel.fit file: parameter_estimation/archmodel-fit.py line: 0 kind: required_method signature: '' - name: ARCHModelResult.summary file: parameter_estimation/archmodelresult-summary.py line: 0 kind: required_method signature: '' - name: ARCHModelResult.conf_int file: parameter_estimation/archmodelresult-conf-int.py line: 0 kind: required_method signature: '' - name: Starting values file: parameter_estimation/starting-values.py line: 0 kind: replaceable_point - name: Covariance type file: parameter_estimation/covariance-type.py line: 0 kind: replaceable_point design_decision_count: 4 forecasting_&_simulation: class_count: 5 stage_id: forecasting stage_order: 4 responsibility: Generate multi-step volatility/mean forecasts using analytic formulas, simulation, or bootstrap. Handles alignment (origin vs target), reindexing, and exogenous regressors. classes: - name: ARCHModelResult.forecast file: forecasting_&_simulation/archmodelresult-forecast.py line: 0 kind: required_method signature: '' - name: VarianceForecast._analytic_forecast file: forecasting_&_simulation/varianceforecast-analytic-forecast.py line: 0 kind: required_method signature: '' - name: VarianceForecast._simulation_forecast file: forecasting_&_simulation/varianceforecast-simulation-forecast.py line: 0 kind: required_method signature: '' - name: Forecasting method file: forecasting_&_simulation/forecasting-method.py line: 0 kind: replaceable_point - name: Alignment file: forecasting_&_simulation/alignment.py line: 0 kind: replaceable_point design_decision_count: 3 unit_root_&_cointegration_testing: class_count: 7 stage_id: unitroot_testing stage_order: 5 responsibility: Test time series for stationarity (unit roots) and cross-series cointegration relationships. Supports ADF, DFGLS, PhillipsPerron, KPSS, ZivotAndrews, VarianceRatio, Engle-Granger, Phillips-Ouliaris, DOLS, FMOLS. classes: - name: ADF.__init__ file: unit_root_&_cointegration_testing/adf-init.py line: 0 kind: required_method signature: '' - name: UnitRootTest.stat file: unit_root_&_cointegration_testing/unitroottest-stat.py line: 0 kind: required_method signature: '' - name: CointegrationTestResult.stat file: unit_root_&_cointegration_testing/cointegrationtestresult-stat.py line: 0 kind: required_method signature: '' - name: DynamicOLS.__init__ file: unit_root_&_cointegration_testing/dynamicols-init.py line: 0 kind: required_method signature: '' - name: Test statistic file: unit_root_&_cointegration_testing/test-statistic.py line: 0 kind: replaceable_point - name: Lag selection method file: unit_root_&_cointegration_testing/lag-selection-method.py line: 0 kind: replaceable_point - name: Covariance kernel file: unit_root_&_cointegration_testing/covariance-kernel.py line: 0 kind: replaceable_point design_decision_count: 1 bootstrap_&_multiple_comparison: class_count: 7 stage_id: bootstrap_inference stage_order: 6 responsibility: Time-series bootstrap for standard errors/confidence intervals; multiple comparison procedures (MCS, StepM, SPA) for model selection. Supports block bootstrap (circular, stationary, moving) and independent resampling. classes: - name: IIDBootstrap.conf_int file: bootstrap_&_multiple_comparison/iidbootstrap-conf-int.py line: 0 kind: required_method signature: '' - name: StationaryBootstrap.__init__ file: bootstrap_&_multiple_comparison/stationarybootstrap-init.py line: 0 kind: required_method signature: '' - name: MCS.__init__ file: bootstrap_&_multiple_comparison/mcs-init.py line: 0 kind: required_method signature: '' - name: SPA.__init__ file: bootstrap_&_multiple_comparison/spa-init.py line: 0 kind: required_method signature: '' - name: Bootstrap type file: bootstrap_&_multiple_comparison/bootstrap-type.py line: 0 kind: replaceable_point - name: Confidence interval method file: bootstrap_&_multiple_comparison/confidence-interval-method.py line: 0 kind: replaceable_point - name: Multiple comparison procedure file: bootstrap_&_multiple_comparison/multiple-comparison-procedure.py line: 0 kind: replaceable_point design_decision_count: 4 results_reporting_&_visualization: class_count: 5 stage_id: results_reporting stage_order: 7 responsibility: Format and display estimation results (summary tables, R², AIC/BIC, parameter table with std_err/tvalues/pvalues), residual diagnostics (ARCH-LM test), and visualization (hedgehog plots, residual plots). classes: - name: ARCHModelResult.summary file: results_reporting_&_visualization/archmodelresult-summary.py line: 0 kind: required_method signature: '' - name: ARCHModelResult.conf_int file: results_reporting_&_visualization/archmodelresult-conf-int.py line: 0 kind: required_method signature: '' - name: ARCHModelResult.arch_lm_test file: results_reporting_&_visualization/archmodelresult-arch-lm-test.py line: 0 kind: required_method signature: '' - name: WaldTestStatistic file: results_reporting_&_visualization/waldteststatistic.py line: 0 kind: required_method signature: '' - name: Output format file: results_reporting_&_visualization/output-format.py line: 0 kind: replaceable_point design_decision_count: 1 data_flow_hints: [] locale_contract: source_language: en user_facing_fields: - human_summary.what_i_can_do.tagline - human_summary.what_i_can_do.use_cases[] - human_summary.what_i_auto_fetch[] - human_summary.what_i_ask_you[] - evidence_quality.user_disclosure_template - post_install_notice.message_template.positioning - post_install_notice.message_template.capability_catalog.groups[].name - post_install_notice.message_template.capability_catalog.groups[].description - post_install_notice.message_template.capability_catalog.groups[].ucs[].name - post_install_notice.message_template.capability_catalog.groups[].ucs[].short_description - post_install_notice.message_template.call_to_action - post_install_notice.message_template.featured_entries[].beginner_prompt - post_install_notice.message_template.more_info_hint - preconditions[].description - preconditions[].on_fail - intent_router.uc_entries[].name - intent_router.uc_entries[].ambiguity_question - architecture.pipeline - architecture.stages[].narrative.does_what - architecture.stages[].narrative.key_decisions - architecture.stages[].narrative.common_pitfalls - constraints.fatal[].consequence - constraints.regular[].consequence - output_validator.assertions[].failure_message - acceptance.hard_gates[].on_fail - skill_crystallization.action locale_detection_order: - explicit_user_declaration - first_message_language - system_locale translation_enforcement: trigger: on_first_user_message action: Render user_facing_fields in detected locale, preserving all IDs (BD-/SL-/UC-/finance-C-) and code identifiers verbatim violation_code: LOCALE-01 violation_signal: User receives untranslated English Human Summary when detected locale != en evidence_quality: declared: evidence_coverage_ratio: 1.0 evidence_verify_ratio: 0.4722222222222222 evidence_invalid: 38 evidence_verified: 34 evidence_auto_fixed: 0 audit_coverage: 53/53 (100%) audit_pass_rate: 3/53 (5%) audit_fail_total: 32 audit_finance_universal: pass: 1 warn: 9 fail: 10 audit_subdomain_totals: pass: 2 warn: 9 fail: 22 enforcement_rules: - id: EQ-01 trigger: declared.evidence_verify_ratio < 0.5 action: MUST invoke traceback lookup for all cited BD-IDs in output before emitting business code — read LATEST.yaml sections for each BD referenced violation_code: EQ-01-V violation_signal: Generated script references BD-IDs but no tool_call to read LATEST.yaml preceded code generation user_disclosure_template: '[QUALITY NOTICE] This crystal was compiled from blueprint finance-bp-124. Evidence verify ratio = 47.2% and audit fail total = 32. Generated results may have uncaptured requirement gaps. Verify critical decisions against source files (LATEST.yaml / LATEST.jsonl).' traceback: source_files: blueprint: LATEST.yaml constraints: LATEST.jsonl mandatory_lookup_scenarios: - id: TB-01 condition: Two constraints have apparently conflicting enforcement rules lookup_target: LATEST.jsonl — find both constraint IDs, compare `consequence` + `evidence_refs` to determine priority - id: TB-02 condition: A business decision rationale is unclear or disputed lookup_target: LATEST.yaml — locate BD-ID under business_decisions, read `rationale` + `alternative_considered` fields - id: TB-03 condition: evidence_invalid > 0 in evidence_quality.declared lookup_target: LATEST.yaml _enrich_meta — cross-check specific BD `evidence_refs` fields for invalid markers - id: TB-04 condition: User asks where a rule comes from lookup_target: LATEST.jsonl — find constraint by ID, read `confidence.evidence_refs` for source file + line number - id: TB-05 condition: Generated code does not match expected ZVT API behavior lookup_target: LATEST.yaml stages[].required_methods — verify method signature and evidence locator in source code degraded_lookup: no_fs_access: 'Ask the user to paste the relevant LATEST.yaml section or LATEST.jsonl lines for the BD-/finance-C- IDs in question. Crystal ID: finance-bp-124-v5.0.' trace_schema: event_types: - precondition_check - spec_lock_check - evidence_rule_fired - evidence_rule_skipped - locale_translation_emitted - hard_gate_passed - hard_gate_failed - skill_emitted - false_completion_claim preconditions: - id: PC-01 description: zvt package installed and importable check_command: python3 -c 'import zvt; print(zvt.__version__)' on_fail: 'Run: python3 -m pip install zvt then re-run: python3 -m zvt.init_dirs to initialize data directories' severity: fatal - id: PC-02 description: K-data exists for target entities (required before backtesting) check_command: python3 -c "from zvt.api.kdata import get_kdata; df = get_kdata(entity_ids=['stock_sh_600000'], limit=1); assert df is not None and len(df) > 0, 'No kdata found'" on_fail: 'Run recorder first: python3 -m zvt.recorders.em.em_stock_kdata_recorder --entity_ids stock_sh_600000 (replace with your target entity IDs)' severity: fatal applies_to_uc: - UC-101 - UC-102 - UC-103 - UC-104 - UC-105 - UC-106 - UC-107 - UC-108 - UC-109 - id: PC-03 description: ZVT data directory initialized (~/.zvt or ZVT_HOME) check_command: 'python3 -c "import os; from pathlib import Path; zvt_home = Path(os.environ.get(''ZVT_HOME'', Path.home() / ''.zvt'')); assert zvt_home.exists(), f''ZVT home not found: {zvt_home}''"' on_fail: 'Run: python3 -m zvt.init_dirs' severity: fatal - id: PC-04 description: SQLite write permission for ZVT data directory check_command: python3 -c "import os, tempfile; from pathlib import Path; zvt_home = Path(os.environ.get('ZVT_HOME', Path.home() / '.zvt')); test_f = zvt_home / '.write_test'; test_f.touch(); test_f.unlink()" on_fail: 'Check directory permissions: chmod u+w ~/.zvt or set ZVT_HOME environment variable to a writable location' severity: warn intent_router: uc_entries: - uc_id: UC-101 name: Sharpe Ratio Bootstrap Statistical Inference positive_terms: - bootstrap - sharpe ratio - statistical inference - confidence intervals - stationary bootstrap data_domain: financial_data negative_terms: - GARCH - volatility forecasting - unit root - cointegration - model comparison ambiguity_question: Are you looking to compute statistical inference on performance metrics like Sharpe Ratio using bootstrap methods? - uc_id: UC-102 name: Multiple Model Comparison with SPA Test positive_terms: - model comparison - SPA test - multiple models - benchmark comparison - superior predictive ability data_domain: financial_data negative_terms: - GARCH - volatility forecasting - unit root - cointegration - bootstrap ambiguity_question: Do you want to test whether multiple models can significantly beat a benchmark predictor? - uc_id: UC-103 name: Oil Price Cointegration Analysis positive_terms: - cointegration - unit root - ADF test - Engle-Granger - oil prices - mean reversion data_domain: financial_data negative_terms: - GARCH - volatility forecasting - bootstrap - model comparison ambiguity_question: Are you testing whether two related financial series (like crude oil prices) move together in a long-run equilibrium? - uc_id: UC-104 name: Credit Spread Stationarity Testing positive_terms: - unit root - ADF test - stationarity - credit spread - mean reversion data_domain: financial_data negative_terms: - cointegration - GARCH - volatility forecasting - bootstrap ambiguity_question: Are you testing whether a time series (like credit spreads) is stationary or has a unit root? - uc_id: UC-105 name: ARX Forecasting with Exogenous Variables positive_terms: - ARX - exogenous variables - forecasting - autoregressive - regression data_domain: financial_data negative_terms: - GARCH - volatility modeling - cointegration - unit root ambiguity_question: Do you want to forecast a time series while accounting for the effect of external/exogenous variables? - uc_id: UC-106 name: HARX Volatility Modeling with Fixed Variance positive_terms: - fixed variance - HARX - volatility modeling - GARCH - VIX data_domain: financial_data negative_terms: - cointegration - unit root - exogenous variables - bootstrap ambiguity_question: Do you want to model volatility using a pre-specified or externally computed variance series? - uc_id: UC-107 name: S&P 500 GARCH Volatility Forecasting positive_terms: - GARCH - volatility forecasting - S&P 500 - conditional variance - out-of-sample data_domain: financial_data negative_terms: - cointegration - unit root - bootstrap - model comparison ambiguity_question: Do you need to forecast future volatility levels for the S&P 500 or similar assets? - uc_id: UC-108 name: S&P 500 GARCH Volatility Model Comparison positive_terms: - GARCH - volatility modeling - S&P 500 - model comparison - asymmetric GARCH - t-distribution data_domain: financial_data negative_terms: - cointegration - unit root - bootstrap - exogenous variables ambiguity_question: Are you fitting GARCH volatility models to characterize return variance dynamics? - uc_id: UC-109 name: NASDAQ Volatility Scenario Generation positive_terms: - volatility scenarios - simulation - NASDAQ - GARCH - scenario analysis - risk management data_domain: financial_data negative_terms: - cointegration - unit root - bootstrap - model comparison ambiguity_question: Do you need to generate multiple simulated volatility scenarios for stress testing or risk analysis? context_state_machine: states: - id: CA1_MEMORY_CHECKED entry: Task started exit: All memory queries attempted and recorded; memory_unavailable set if failed timeout: 30s — skip memory, mark memory_unavailable=true, proceed to CA2 - id: CA2_GAPS_FILLED entry: CA1 complete exit: 'All FATAL-priority required inputs answered: target market (A-share/HK/US), data source, time range, strategy type' timeout: NOT skippable — FATAL inputs MUST be user-answered before proceeding - id: CA3_PATH_SELECTED entry: CA2 complete exit: intent_router matched single use case with confidence gap > 20% over next candidate, no data_domain ambiguity timeout: Trigger ambiguity_question for top-2 candidates, await user selection - id: CA4_EXECUTING entry: CA3 complete + user explicit confirmation received exit: All hard gates G1-Gn passed and output files written timeout: NOT skippable — user confirmation of execution path required enforcement: Code generation is PROHIBITED before CA4_EXECUTING. Any regression to earlier state MUST be announced to user. buy/sell ordering SL-01 check runs at CA4 entry. spec_lock_registry: semantic_locks: - id: SL-01 description: Execute sell orders before buy orders in every trading cycle locked_value: sell() called before buy() in each Trader.run() iteration violation_is: fatal source_bd_ids: - BD-018 - id: SL-02 description: Trading signals MUST use next-bar execution (no look-ahead) locked_value: due_timestamp = happen_timestamp + level.to_second() violation_is: fatal source_bd_ids: - BD-014 - BD-025 - id: SL-03 description: Entity IDs MUST follow format entity_type_exchange_code locked_value: stock_sh_600000 | stockhk_hk_0700 | stockus_nasdaq_AAPL violation_is: fatal source_bd_ids: [] - id: SL-04 description: DataFrame index MUST be MultiIndex (entity_id, timestamp) locked_value: df.index.names == ['entity_id', 'timestamp'] violation_is: fatal source_bd_ids: [] - id: SL-05 description: 'TradingSignal MUST have EXACTLY ONE of: position_pct, order_money, order_amount' locked_value: XOR enforcement in trading/__init__.py:68 violation_is: fatal source_bd_ids: [] - id: SL-06 description: 'filter_result column semantics: True=BUY, False=SELL, None/NaN=NO ACTION' locked_value: factor.py:475 order_type_flag mapping violation_is: fatal source_bd_ids: [] - id: SL-07 description: Transformer MUST run BEFORE Accumulator in factor pipeline locked_value: 'compute_result(): transform at :403 before accumulator at :409' violation_is: fatal source_bd_ids: [] - id: SL-08 description: 'MACD parameters locked: fast=12, slow=26, signal=9' locked_value: factors/algorithm.py:30 macd(slow=26, fast=12, n=9) violation_is: fatal source_bd_ids: - BD-036 - id: SL-09 description: 'Default transaction costs: buy_cost=0.001, sell_cost=0.001, slippage=0.001' locked_value: sim_account.py:25 SimAccountService default costs violation_is: warning source_bd_ids: - BD-029 - id: SL-10 description: A-share equity trading is T+1 (no same-day close of buy positions) locked_value: sim_account.available_long filters by trading_t violation_is: fatal source_bd_ids: [] - id: SL-11 description: Recorder subclass MUST define provider AND data_schema class attributes locked_value: contract/recorder.py:71 Meta; register_schema decorator violation_is: fatal source_bd_ids: [] - id: SL-12 description: Factor result_df MUST contain either 'filter_result' OR 'score_result' column locked_value: result_df.columns.intersection({'filter_result', 'score_result'}) non-empty violation_is: fatal source_bd_ids: [] implementation_hints: - id: IH-01 hint: 'Use AdjustType enum exactly: qfq (pre-adjust), hfq (post-adjust), bfq (none) — contract/__init__.py:121' - id: IH-02 hint: For A-share kdata, default to hfq for long-term analysis (dividend-adjusted) — trader.py:538 StockTrader - id: IH-03 hint: SQLite connection MUST use check_same_thread=False for multi-threaded recorders - id: IH-04 hint: Accumulator state serialization uses JSON with custom encoder/decoder hooks — contract/base_service.py - id: IH-05 hint: Factor.level MUST match TargetSelector.level (enforced at add_factor) — factors/target_selector.py:84 preservation_manifest: required_objects: business_decisions_count: 107 fatal_constraints_count: 77 non_fatal_constraints_count: 151 use_cases_count: 9 semantic_locks_count: 12 preconditions_count: 4 evidence_quality_rules_count: 2 traceback_scenarios_count: 5 architecture: pipeline: data_collection -> data_storage -> factor_computation -> target_selection -> trading_execution -> visualization stages: - id: data_collection narrative: does_what: TimeSeriesDataRecorder and FixedCycleDataRecorder fetch OHLCV and fundamental data from providers (eastmoney, joinquant, baostock, akshare) and persist domain objects (Stock1dKdata, BalanceSheet) to SQLite via df_to_db(). key_decisions: BD-002 chose evaluate_start_end_size_timestamps for incremental fetch (not full refresh) because comparing to get_latest_saved_record avoids redundant API calls; BD-003 chose get_data_map field transformation to keep domain schema provider-agnostic. common_pitfalls: 'Don''t forget SL-11: Recorder subclass MUST declare both provider and data_schema class attributes else initialization fails with assertion error; finance-C-001 fatal violation.' business_decisions: [] - id: data_storage narrative: does_what: StorageBackend persists DataFrames to per-provider SQLite databases at {data_path}/{provider}/{provider}_{db_name}.db using path templates from _get_path_template; Mixin.record_data and Mixin.query_data provide uniform read/write interface. key_decisions: BD-004 chose StorageBackend abstraction (not hardcoded SQLite) to allow future cloud storage swap; BD-006 derives db_name from data_schema __tablename__ for per-domain database isolation. common_pitfalls: SL-04 violation (wrong DataFrame index) causes factor pipeline failures downstream; always ensure df.index.names == ['entity_id', 'timestamp'] before calling record_data. business_decisions: [] - id: factor_computation narrative: does_what: Factor.compute() applies Transformer (stateless, e.g. MacdTransformer) then Accumulator (stateful, e.g. MaStatsAccumulator) to produce filter_result or score_result columns; EntityStateService persists per-entity rolling state across batches. key_decisions: BD-007 chose Factor inheriting DataReader for composable data access; SL-08 locks MACD at (fast=12, slow=26, n=9) — chose standard Appel parameters not adaptive because interpretability matters for practitioners. common_pitfalls: 'SL-07: Transformer MUST run before Accumulator — swapping order causes NaN propagation; SL-12: result_df must contain filter_result OR score_result column or TargetSelector silently drops all signals.' business_decisions: [] - id: target_selection narrative: does_what: TargetSelector.add_factor() registers Factor instances; get_targets() returns entity_ids passing threshold filter at a specific timestamp, enabling point-in-time historical backtesting without look-ahead. key_decisions: BD-012 chose registrable factor list (not hardcoded) for runtime customization; BD-013 chose timestamp-specific filtering not current-only because backtests need historical point-in-time correctness. common_pitfalls: Factor.level MUST match TargetSelector.level (IH-05); mismatched levels cause silent empty target lists that look like no signals but are actually level-mismatch bugs. business_decisions: [] - id: trading_execution narrative: does_what: Trader.run() calls sell() before buy() each cycle, generates TradingSignals with due_timestamp = happen_timestamp + level.to_second() for next-bar execution, and applies on_profit_control() for stop-loss/take-profit before regular target selection. key_decisions: SL-01 locks sell-before-buy order because available_long check in sim_account depends on it — chose this over symmetric ordering to prevent implicit leverage; BD-039 chose long=AND/short=OR multi-level logic to reflect risk asymmetry. common_pitfalls: 'SL-02 violation (immediate execution instead of next-bar) introduces look-ahead bias and makes backtest results unreproducible in live trading; SL-10: A-share T+1 constraint — backtesting without it overstates returns.' business_decisions: [] - id: visualization narrative: does_what: Drawer.draw() combines kline main chart with factor overlays and Rect annotations for entry/exit signals using Plotly; Drawable interface on Factor enables consistent chart rendering across data types. key_decisions: BD-019 chose drawer_rects subclass override for custom annotations not hardcoded markers — allows traders to define entry/exit visuals without modifying base drawing logic. common_pitfalls: draw_result=True by default (BD-055) is fine for development but set draw_result=False in production/headless environments to avoid Plotly server startup overhead. business_decisions: [] - id: cross_cutting_concerns narrative: does_what: 'Invariants and utilities that span multiple pipeline stages — collected from 21 source groups: arch.bootstrap(2), arch.covariance(2), arch.unitroot(11), arch.unitroot.critical_values.simulation(2), arch.univariate(11), bandwidth_selection(1), and 15 more.' key_decisions: 107 BDs merged here because they apply to more than one main stage (e.g. algorithm helpers, default value choices, ordering contracts, error handling). Agent should inspect individual BD summaries and link back to affected main stages via shared IDs. common_pitfalls: Cross-cutting concerns frequently surface as bugs when changes to one main stage unintentionally break another. Check constraints referencing these BDs and verify invariants still hold after any stage-local modification. business_decisions: - id: BD-030 type: B summary: Use Politis-White optimal block length formula for Stationary and Circular Block Bootstrap - id: BD-054 type: B/BA summary: Use Stationary Bootstrap with geometric block length distribution - id: BD-035 type: B summary: Use Bartlett kernel with automatic bandwidth for long-run covariance in KPSS - id: BD-053 type: B summary: Use Quadratic Spectral kernel for Andrews-optimal long-run covariance - id: BD-031 type: B/BA summary: Use BIC as default lag selection method for ADF test - id: BD-032 type: B/BA summary: Use MacKinnon critical value regression surface for ADF/PP p-values - id: BD-033 type: B/BA summary: Use automatic max_lags formula 12*(nobs/100)^(1/4) for ADF when not specified - id: BD-041 type: B summary: Use Elliott-Rothenberg-Stock GLS detrending for DFGLS test - id: BD-042 type: B/RC summary: Use Engle-Granger two-step cointegration test on cross-sectional regression residuals - id: BD-043 type: B summary: Use Dynamic OLS with leads and lags for cointegrating vector estimation - id: BD-044 type: B/BA summary: Use Newey-West automatic bandwidth for KPSS with Hobijn et al. formula - id: BD-045 type: B/BA summary: Use Zivot-Andrews structural break test with single-break assumption - id: BD-046 type: B/BA summary: Use Phillips-Ouliaris Za/Zt/Pu/Pz tests with kernel-based long-run covariance - id: BD-047 type: B summary: Use Variance Ratio test with heteroskedasticity-robust inference for random walk - id: BD-055 type: B/BA summary: Use OLS with t-stat threshold of 1.645 for lag selection in t-stat method - id: BD-052 type: B summary: Use Weighted Least Squares for critical value surface estimation in simulations - id: BD-057 type: B summary: Use 250,000 simulations for critical value surface estimation - id: BD-034 type: B summary: Use GARCH recursion with power transformation for variance bounds - id: BD-036 type: B summary: Use EWMA recursion with lambda=0.94 for RiskMetrics2006 variance - id: BD-037 type: B/BA summary: Use Student's t distribution with kurtosis-based starting values for ARCH models - id: BD-038 type: B/BA summary: Use 0.94^i exponential decay backcast for GARCH initialization - id: BD-039 type: B summary: Use FIGARCH with ARCH(infinity) representation for long-memory volatility - id: BD-040 type: B/BA summary: Use EGARCH with log-variance for asymmetric volatility modeling - id: BD-048 type: B/BA summary: Use Skew Student's t with Hansen (1994) parameterization for asymmetric returns - id: BD-049 type: B/RC summary: Use Generalized Error Distribution with nu>1 for flexible tail modeling - id: BD-050 type: B/BA summary: Use HAR (Heterogeneous Autoregressive) model for financial volatility forecasting - id: BD-051 type: B summary: Use scipy.optimize.minimize with L-BFGS-B for ARCH model maximum likelihood - id: BD-056 type: B/BA summary: Use APARCH with delta=1 for TARCH specification and power parameter - id: BD-028 type: B summary: Auto-bandwidth selection for KPSS test - id: BD-007 type: B/BA summary: sqrt(T) as default bootstrap block size - id: BD-008 type: B/BA summary: Stationary Bootstrap as default for MCS - id: BD-009 type: B/BA summary: 1000 bootstrap replications for MCS - id: BD-013 type: B/BA summary: 2500 bootstrap replications for Sharpe ratio - id: BD-019 type: B summary: Two-sided p-values using normal SF - id: BD-026 type: B/BA summary: 'Bootstrap confidence intervals: ''basic'' and ''percentile'' methods' - id: BD-022 type: B/BA summary: EWMA decay parameter 0.94 for variance bounds - id: BD-023 type: B summary: 'Variance bounds: [var/1e6, var*1e6] with floor/ceiling' - id: BD-027 type: B/BA summary: 'Parametric constraints: alpha[i] > 0, beta[i] > 0, sum < 1' - id: BD-003 type: B/BA summary: 100 * pct_change() for returns calculation - id: BD-GAP-001 type: DK summary: 'Missing: as-of vs processing time' - id: BD-GAP-002 type: DK summary: 'Missing: Point-in-Time data availability' - id: BD-GAP-003 type: DK summary: 'Missing: Stale data detection and expiry' - id: BD-GAP-004 type: DK summary: 'Missing: Model/data version snapshot binding' - id: BD-GAP-005 type: B summary: 'Missing: Currency/unit explicit annotation' - id: BD-GAP-006 type: RC summary: 'Missing: Settlement and delivery time' - id: BD-GAP-007 type: RC summary: 'Missing: Price and quantity precision' - id: BD-GAP-008 type: B summary: 'Missing: 协方差矩阵 PSD 修复策略' - id: BD-GAP-009 type: B summary: 'Missing: 协方差估计量选择与收缩' - id: BD-GAP-010 type: B summary: 'Missing: VaR/CVaR 置信水平与窗口' - id: BD-GAP-011 type: DK summary: 'Missing: 版本化写入与快照语义' - id: BD-GAP-012 type: DK summary: 'Missing: ** "Implement explicit timezone annotation policy: each DatetimeIndex inputs must be UTC-normalized with explicit tz_localize before processing; add a validate_timezone() helper' - id: BD-GAP-013 type: M summary: 'Missing: ** "Add Hessian condition number check before np.linalg.inv() in arch/univariate/base.py:979 and in cointegration module; warn or regularize if cond > 1e10' - id: BD-GAP-014 type: B summary: 'Missing: ** "Add PSD (positive semi-definite) validation to kernel covariance estimator output in arch/covariance/kernel.py; symmetrize + eigenfloor any non-PSD estimates' - id: BD-GAP-015 type: M summary: 'Missing: ** "Add explicit DataScaleWarning behavior description for poorly-scaled data: document the 1-1000 scale recommendation and add a rescale helper' - id: BD-GAP-016 type: M summary: 'Missing: ** "Add optional ConvergenceDiagnosis object that stores: iteration history, log-likelihood path, parameter trajectory, for post-hoc convergence quality assessment' - id: BD-GAP-017 type: B summary: 'Missing: ** "Add explicit annualized_volatility() helper with configurable compounding convention (252, 365, simple); clarify that each volatility is in frequency-of-data units' - id: BD-GAP-018 type: B summary: 'Missing: ** "Add backtest validation framework: automatic train/test split with historical VaR/CVaR/realized PnL tracking for volatility models' - id: BD-GAP-019 type: DK summary: 'Missing: as-of vs processing time' - id: BD-GAP-020 type: DK summary: 'Missing: Point-in-Time data availability' - id: BD-GAP-021 type: DK summary: 'Missing: Stale data detection and expiry' - id: BD-GAP-022 type: M/DK summary: 'Missing: Day count convention' - id: BD-GAP-023 type: B summary: 'Missing: Currency/unit explicit annotation' - id: BD-GAP-024 type: RC summary: 'Missing: Settlement and delivery time' - id: BD-GAP-025 type: RC summary: 'Missing: Price and quantity precision' - id: BD-060 type: BA/DK summary: GARCH power=2.0 defaults to standard GARCH; power!=2.0 blocks analytic forecasts - id: BD-061 type: B/BA summary: ConstantVariance() and Normal() are hardcoded ARCHModel defaults - id: BD-066 type: BA/M summary: Backcast uses exponential decay tau=min(75, nobs) with 0.94^weight - id: BD-069 type: BA summary: hold_back=0 by default; each observations used in estimation - id: BD-072 type: T summary: BCa confidence intervals require equal-length datasets across args/kwargs - id: BD-004 type: B/BA summary: Analytic forecast method as default - id: BD-005 type: B/BA summary: 1000 simulations for simulation/bootstrap forecasting - id: BD-014 type: B/DK summary: Rolling window forecasts with 20 replications - id: BD-020 type: B summary: 3-d array for multiple exogenous variable forecasts - id: BD-029 type: B/BA summary: Simulation-based forecasting for multi-step GARCH with power!=2 - id: BD-073 type: BA/DK summary: 'INTERACTION: BD-002 (Normal distribution) × BD-017 (Student''s T distribution) → CONTRADICTION: Gaussian default vs heavy-tail reality' - id: BD-074 type: BA/DK summary: 'INTERACTION: BD-003 (100*pct_change returns) × BD-012 (Sharpe annualization 12x) → HIDDEN DEPENDENCY: Return scaling propagates to performance metrics' - id: BD-075 type: BA/DK summary: 'INTERACTION: BD-001 (GARCH(1,1)) × BD-015 (GJR-GARCH leverage) × BD-041 (EGARCH log-variance) → RISK CASCADE: Asymmetric volatility models cascade through VaR estimation' - id: BD-076 type: BA/M summary: 'INTERACTION: BD-010 (AIC for ADF) × BD-032 (BIC for ADF) → CONTRADICTION: Conflicting lag selection defaults across codebase' - id: BD-077 type: BA/DK summary: 'INTERACTION: BD-004 (Analytic forecast) × BD-030 (Simulation for power!=2) × BD-061 (power blocks analytic) → RISK CASCADE: Power specification determines forecast method availability' - id: BD-078 type: BA/M summary: 'INTERACTION: BD-006 (EWMA backcast tau=75) × BD-022 (lambda=0.94 decay) × BD-037 (RiskMetrics lambda=0.94) → AMPLIFICATION: Consistent EWMA parameters amplify initialization sensitivity' - id: BD-079 type: BA/M summary: 'INTERACTION: BD-007 (sqrt(T) block size) × BD-008 (Stationary Bootstrap) × BD-031 (Politis-White optimal block) → AMPLIFICATION: Multiple block length selection mechanisms interact' - id: BD-080 type: BA/DK summary: 'INTERACTION: BD-021 (Bollerslev-Wooldridge robust SE) × BD-028 (GARCH constraints alpha+beta<1) → HIDDEN DEPENDENCY: Robust inference requires correctly specified volatility model' - id: BD-081 type: BA summary: 'INTERACTION: BD-070 (hold_back=0 default) × BD-014 (20 rolling windows) → CONTRADICTION: Full-sample estimation vs out-of-sample validation requirements' - id: BD-082 type: BA summary: 'INTERACTION: BD-033 (MacKinnon critical values) × BD-043 (Engle-Granger cointegration) × BD-047 (Phillips-Ouliaris tests) → RISK CASCADE: Critical value surface accuracy cascades through each unit roo' - id: BD-065 type: B/BA summary: CircularBlockBootstrap inherits from IIDBootstrap with block_length override - id: BD-006 type: B/BA summary: EWMA backcast with lambda=0.94 and tau=75 - id: BD-062 type: DK summary: 'Parameter ordering: [mean_params, vol_params, dist_params] with computed offsets' - id: BD-063 type: DK summary: 'Loglikelihood computation order: resid -> sigma2 -> distribution.loglikelihood' - id: BD-070 type: DK summary: 'rescale threshold: variance must be in [0.1, 10000) to avoid rescaling' - id: BD-001 type: B/BA summary: GARCH(1,1) as default volatility model - id: BD-002 type: B/BA summary: Normal (Gaussian) distribution as default error distribution - id: BD-010 type: B/BA summary: AIC as default lag selection criterion for ADF - id: BD-011 type: B/BA summary: Constant as default ADF deterministic trend - id: BD-015 type: B/BA summary: GJR-GARCH with o=1 captures leverage effect - id: BD-016 type: B/BA summary: TARCH (power=1.0) models absolute volatility - id: BD-017 type: B/BA summary: Student's T distribution for heavy-tailed returns - id: BD-018 type: B summary: R-squared adjusted for degrees of freedom - id: BD-024 type: B/BA summary: Fixed parameters via fix() method for counterfactuals - id: BD-058 type: T summary: fit() MUST be called before forecast() on ARCHModelResult - id: BD-059 type: T summary: Bootstrap clone() requires fresh fit data - old fit indices persist - id: BD-068 type: T summary: fit() closed-form path requires Normal() dist AND ConstantVariance volatility - id: BD-025 type: B summary: 'Horizon naming: ''h.1'', ''h.2'', ... for forecast columns' - id: BD-021 type: B summary: Bollerslev-Wooldridge robust covariance estimator - id: BD-064 type: M/DK summary: 'Strategy pattern: VolatilityProcess/Distribution are pluggable strategy objects' - id: BD-067 type: M/DK summary: Starting values search uses fixed grid of (alpha, gamma, beta) tuples - id: BD-071 type: B summary: Numba JIT compilation fallback to Python in _cov_kernel - id: BD-012 type: B/BA summary: Sharpe Ratio annualized with 12 multiplier resources: packages: - name: pandas version_pin: ==1.5.3 - name: numpy version_pin: ==1.24.4 - name: matplotlib version_pin: '>=2' - name: requests version_pin: ==2.31.0 - name: scipy version_pin: '>=1.3.0' - name: scikit-learn version_pin: '>1.4.2' - name: pytest version_pin: '>=8.3' strategy_scaffold: entry_point_name: run_backtest output_path: result.csv execution_mode: backtest conditional_entry_points: backtest: entry_point_name: run_backtest output_path: result.csv collector: entry_point_name: run_collector output_path: result.json factor: entry_point_name: run_factor output_path: result.parquet training: entry_point_name: run_training output_path: result.json serving: entry_point_name: run_server output_path: result.json research: entry_point_name: run_research output_path: result.json tail_template: "# === DO NOT MODIFY BELOW THIS LINE ===\nif __name__ == \"__main__\":\n result = run_backtest() #\ \ implement above\n from validate import enforce_validation\n enforce_validation(result, output_path=\"{workspace}/result.csv\"\ )\n# === END DO NOT MODIFY ===" host_adapter: target: openclaw timeout_seconds: 1800 shell_operator_restriction: 'exec tool intercepts && / ; / | — never chain: ''pip install X && python Y''. Use separate exec calls.' install_recipes: - python3 -m pip install zvt credential_injection: JoinQuant/QMT credentials require user-side '!' prefix shell login. Never hardcode credentials in generated scripts. path_resolution: '{workspace} resolves to ~/.openclaw/workspace/doramagic at execution time.' file_io_tooling: Use openclaw 'write' tool for .py/.sql files; 'exec' tool for python3 /absolute/path/script.py (absolute paths only). constraints: fatal: - id: finance-C-001 when: When implementing data input for ARCH model initialization action: validate that input data contains only finite values using np.all(np.isfinite) before any numeric computation severity: fatal kind: domain_rule modality: must consequence: Optimizers and recursive variance computations will produce NaN/inf results, causing the entire model estimation to fail silently with meaningless outputs stage_ids: - data_input - id: finance-C-002 when: When implementing data input for ARCH model initialization action: convert each input data to contiguous float64 arrays using np.ascontiguousarray before storing in self._y severity: fatal kind: domain_rule modality: must consequence: Non-contiguous arrays or non-float64 types will cause buffer errors in Cython/Numba optimized recursive computations, leading to segmentation faults or incorrect variance calculations stage_ids: - data_input - id: finance-C-009 when: When initializing ARCH models with data action: pass None as input data without raising RuntimeError when attempting to fit the model severity: fatal kind: domain_rule modality: must_not consequence: Fitting attempt with no data will cause cryptic errors in scipy optimize or segfault in Cython recursions stage_ids: - data_input - id: finance-C-013 when: When implementing an ARCH model with custom components action: verify input data y contains only finite values without NaN or inf severity: fatal kind: domain_rule modality: must consequence: NaN or inf values in the input data cause the model to fail silently or produce invalid likelihood computations during optimization, leading to incorrect parameter estimates stage_ids: - model_specification - id: finance-C-014 when: When plugging in a volatility component to ARCHModel action: verify the volatility parameter inherits from VolatilityProcess abstract base class severity: fatal kind: domain_rule modality: must consequence: Using a non-VolatilityProcess subclass causes TypeError during initialization, and incompatible volatility processes will fail during variance computation and forecasting stage_ids: - model_specification - id: finance-C-015 when: When plugging in a distribution component to ARCHModel action: verify the distribution parameter inherits from Distribution abstract base class severity: fatal kind: domain_rule modality: must consequence: Using a non-Distribution subclass causes TypeError during initialization, and incompatible distributions will fail during log-likelihood computation stage_ids: - model_specification - id: finance-C-016 when: When implementing custom volatility or distribution classes action: implement the constraints() method returning (A, b) arrays where A.dot(params) - b >= 0 severity: fatal kind: domain_rule modality: must consequence: Missing or incorrect constraints implementation causes optimization to use invalid parameter regions, producing mathematically invalid volatility models (e.g., negative variances) stage_ids: - model_specification - id: finance-C-019 when: When implementing custom volatility processes action: provide compute_variance() method that fills sigma2 array with conditional variances severity: fatal kind: domain_rule modality: must consequence: Missing or incorrect compute_variance implementation causes the likelihood function to fail, making parameter estimation impossible stage_ids: - model_specification - id: finance-C-020 when: When implementing custom distribution classes action: provide loglikelihood() method for likelihood evaluation during optimization severity: fatal kind: domain_rule modality: must consequence: Missing loglikelihood implementation causes the optimization to fail during parameter estimation, as log-likelihood is the objective function for SLSQP stage_ids: - model_specification - id: finance-C-029 when: When composing ARCHModel from three components action: 'concatenate parameter arrays in the fixed order: [mean_params, volatility_params, distribution_params]' severity: fatal kind: architecture_guardrail modality: must consequence: Incorrect parameter ordering causes _parse_parameters to assign wrong values to each component, leading to mathematically invalid models (e.g., volatility parameters interpreted as mean parameters) stage_ids: - model_specification - id: finance-C-030 when: When constructing constraints for ARCH model fitting action: stack constraint matrices from mean model, volatility, and distribution in parameter order severity: fatal kind: architecture_guardrail modality: must consequence: Incorrect constraint stacking causes the optimizer to enforce wrong constraints on wrong parameters, producing invalid or non-stationary models stage_ids: - model_specification - id: finance-C-031 when: When constructing starting values for ARCH model fitting action: concatenate starting values from mean model, volatility (computed from resids), and distribution (computed from std_resids) severity: fatal kind: architecture_guardrail modality: must consequence: Incorrect starting values concatenation causes the optimizer to use wrong initial values for wrong parameters, leading to poor convergence or wrong solutions stage_ids: - model_specification - id: finance-C-035 when: When implementing SLSQP constrained optimization action: enforce inequality constraints a.dot(params) - b >= 0 for each parameters severity: fatal kind: domain_rule modality: must consequence: Volatility model parameters violating stationarity constraints produce invalid conditional variances, causing downstream risk misestimation and potential trading losses stage_ids: - parameter_estimation - id: finance-C-036 when: When computing conditional variance in optimization loop action: verify sigma2 (conditional variance) >= 0 for each observations severity: fatal kind: domain_rule modality: must consequence: Negative variance values cause loglikelihood to produce NaN, invalidating parameter estimates and causing downstream computations to fail silently stage_ids: - parameter_estimation - id: finance-C-040 when: When constructing the unified parameter vector action: use offsets array to partition parameters into mean|volatility|distribution components severity: fatal kind: architecture_guardrail modality: must consequence: Incorrect parameter partitioning causes wrong component parameters to be passed to mean model, volatility model, and distribution, producing invalid results stage_ids: - parameter_estimation - id: finance-C-041 when: When assembling inequality constraints for joint estimation action: combine constraints from mean model, volatility model, and distribution in correct order severity: fatal kind: architecture_guardrail modality: must consequence: Incorrect constraint ordering places volatility constraints in wrong parameter positions, allowing invalid parameters that violate stationarity or positivity requirements stage_ids: - parameter_estimation - id: finance-C-051 when: When estimating volatility persistence close to 1.0 action: check that persistence = sum(alpha) + sum(gamma)/2 + sum(beta) < 1 for stationarity severity: fatal kind: domain_rule modality: must consequence: Persistence >= 1 violates covariance stationarity, producing non-mean-reverting variance that explodes over time, invalidating long-horizon forecasts stage_ids: - parameter_estimation - id: finance-C-052 when: When implementing ARCH model forecasting code action: verify forecast variances are finite and non-negative throughout the forecast horizon severity: fatal kind: domain_rule modality: must consequence: Non-finite or negative variance forecasts indicate mathematical errors in the ARCH recursion, producing invalid statistical inferences and potentially misleading risk estimates stage_ids: - forecasting - id: finance-C-054 when: When validating forecast horizon parameter action: require horizon to be a positive integer (>= 1) severity: fatal kind: domain_rule modality: must consequence: Invalid horizon values cause undefined forecast behavior or silent data corruption in downstream risk calculations stage_ids: - forecasting - id: finance-C-055 when: When forecasting with EGARCH volatility models action: use analytic method for horizons greater than 1 severity: fatal kind: resource_boundary modality: must_not consequence: EGARCH variance evolves in logarithmic space, not squares. Analytic multi-step formulas require variance to evolve in squares, producing mathematically invalid forecasts stage_ids: - forecasting - id: finance-C-063 when: When validating forecasting method parameter action: accept only 'analytic', 'simulation', or 'bootstrap' as valid method values severity: fatal kind: architecture_guardrail modality: must consequence: Invalid method strings cause undefined behavior or silent fallback to incorrect forecasting algorithm stage_ids: - forecasting - id: finance-C-068 when: When comparing backtested forecast performance to live trading action: claim backtest returns equal expected live trading returns severity: fatal kind: claim_boundary modality: must_not consequence: Backtest results exclude transaction costs, slippage, liquidity constraints, and market impact that affect live execution. Claiming equivalence misleads risk assessment stage_ids: - forecasting - id: finance-C-070 when: When implementing unit root tests that use lag selection action: enforce non-negative integer lags by raising ValueError for negative lags severity: fatal kind: domain_rule modality: must consequence: Negative lag values produce invalid regression specifications with wrong degrees of freedom, causing misleading test statistics and invalid statistical inference stage_ids: - unitroot_testing - id: finance-C-071 when: When running ADF, DFGLS, or KPSS tests action: validate trend against the test-specific supported trends before computation severity: fatal kind: domain_rule modality: must consequence: Invalid trend specification causes wrong statistical distribution assumptions, leading to incorrect critical values and p-values that invalidate test conclusions stage_ids: - unitroot_testing - id: finance-C-072 when: When implementing ADF or DFGLS test regression action: verify sample size exceeds minimum requirement of 3 + trend_order + lag_len observations severity: fatal kind: domain_rule modality: must consequence: Insufficient observations cause singular or near-singular regression matrices, leading to unstable or undefined test statistics stage_ids: - unitroot_testing - id: finance-C-073 when: When computing test statistics for unit root tests action: verify the statistic is finite and within the interpolation bounds of critical value tables severity: fatal kind: domain_rule modality: must consequence: Non-finite or out-of-range statistics produce undefined p-values (0.0 or 1.0) that miss actual stationarity patterns or create false rejections stage_ids: - unitroot_testing - id: finance-C-074 when: When implementing VarianceRatio test action: enforce lags parameter to be an integer >= 2 before computation severity: fatal kind: domain_rule modality: must consequence: Lags less than 2 produce undefined multi-period variance ratios, causing division by zero or mathematically invalid test statistics stage_ids: - unitroot_testing - id: finance-C-075 when: When implementing ZivotAndrews test trim parameter action: validate trim is a float in range [0, 1/3] to verify valid break period calculation severity: fatal kind: domain_rule modality: must consequence: Invalid trim values cause incorrect break point exclusion regions, leading to structural break misdetection and invalid unit root conclusions stage_ids: - unitroot_testing - id: finance-C-076 when: When implementing DFGLS test action: use trend values other than 'c' or 'ct' severity: fatal kind: resource_boundary modality: must_not consequence: Unsupported trends produce GLS-detrending coefficients outside valid ranges (-7.0 for 'c', -13.5 for 'ct'), causing undefined test statistics stage_ids: - unitroot_testing - id: finance-C-077 when: When implementing cointegration tests action: verify y and x have identical number of observations before cross-sectional regression severity: fatal kind: domain_rule modality: must consequence: Misaligned observation counts produce incorrect cointegrating vectors and residuals, leading to spurious cointegration conclusions stage_ids: - unitroot_testing - id: finance-C-080 when: When implementing Engle-Granger cointegration test action: limit the number of cross-sectional variables (num_x) to range [1, 12] severity: fatal kind: resource_boundary modality: must consequence: Cross-sectional variables outside [1,12] lack pre-computed critical value tables, causing KeyError or invalid cointegration inference stage_ids: - unitroot_testing - id: finance-C-081 when: When using MacKinnon critical value functions action: use regression='ctt' with dist_type='dfgls' since DFGLS only supports 'c' and 'ct' severity: fatal kind: resource_boundary modality: must_not consequence: Invalid regression-dist_type combination causes KeyError when accessing non-existent critical value table entries stage_ids: - unitroot_testing - id: finance-C-083 when: When computing automatic bandwidth for KPSS test action: require at least 2 observations in the input series severity: fatal kind: domain_rule modality: must consequence: Single observation series causes division by zero or undefined bandwidth, leading to crashes in KPSS test execution stage_ids: - unitroot_testing - id: finance-C-084 when: When running PhillipsPerron test action: allow zero or negative regression coefficient standard error severity: fatal kind: domain_rule modality: must_not consequence: Zero variance indicates constant-value series or perfect multicollinearity, producing undefined PP test statistics stage_ids: - unitroot_testing - id: finance-C-085 when: When implementing ZivotAndrews test action: validate regressor matrix rank to detect singular matrices from constant regions severity: fatal kind: architecture_guardrail modality: must consequence: Singular regressor matrices cause undefined OLS estimates, producing NaN test statistics and invalid structural break conclusions stage_ids: - unitroot_testing - id: finance-C-093 when: When implementing confidence interval calculation using conf_int method action: use size parameter strictly between 0 and 1 severity: fatal kind: domain_rule modality: must consequence: Invalid CI size produces undefined behavior or runtime ValueError, breaking statistical inference and producing meaningless intervals that cannot be interpreted for decision-making stage_ids: - bootstrap_inference - id: finance-C-094 when: When implementing confidence interval calculation using conf_int method action: use tail parameter as one of 'two', 'lower', or 'upper' severity: fatal kind: domain_rule modality: must consequence: Invalid tail parameter causes ValueError and fails to produce one-sided or two-sided confidence intervals needed for directional hypothesis testing stage_ids: - bootstrap_inference - id: finance-C-095 when: When implementing Model Confidence Set (MCS) with multiple_comparison module action: provide losses array with at least two columns (models) severity: fatal kind: domain_rule modality: must consequence: MCS with fewer than 2 models cannot compute pairwise comparisons, resulting in ValueError and failure to produce any model confidence set output stage_ids: - bootstrap_inference - id: finance-C-096 when: When implementing BCa (bias-corrected and accelerated) confidence interval method action: verify empirical probability p is strictly between 0 and 1 severity: fatal kind: domain_rule modality: must consequence: BCa fails when empirical probability is 0 or 1 (extreme statistics), causing RuntimeError and preventing bias correction for distributions not well-approximated by normal in finite samples stage_ids: - bootstrap_inference - id: finance-C-097 when: When implementing bootstrap-based forecasting using _bootstrap_forecast action: verify start index includes more than 100 observations severity: fatal kind: domain_rule modality: must consequence: Bootstrap forecast with fewer than 100 observations produces unreliable standard errors and confidence intervals, invalidating volatility forecasts for risk management decisions stage_ids: - bootstrap_inference - id: finance-C-098 when: When implementing bootstrap confidence intervals action: validate confidence interval size as strictly between 0 and 1 severity: fatal kind: domain_rule modality: must consequence: Invalid CI size causes ValueError and prevents computation of statistically valid confidence intervals needed for parameter uncertainty quantification stage_ids: - bootstrap_inference - id: finance-C-103 when: When implementing MCS or SPA action: require each input arrays to have the same number of elements in axis 0 severity: fatal kind: resource_boundary modality: must consequence: Misaligned data causes silent misalignment in bootstrap resampling, producing incorrect standard errors and invalid confidence intervals that appear valid stage_ids: - bootstrap_inference - id: finance-C-106 when: When implementing SPA p-value calculation action: compute pvalue argument must be strictly between 0 and 1 for critical values severity: fatal kind: operational_lesson modality: must consequence: Invalid p-value causes ValueError and prevents computation of critical values needed for model selection decisions stage_ids: - bootstrap_inference - id: finance-C-107 when: When implementing bootstrap-based model comparison action: call compute() before accessing pvalues or included/excluded model sets severity: fatal kind: architecture_guardrail modality: must consequence: Accessing results before compute() causes RuntimeError and prevents retrieval of MCS/SPA results stage_ids: - bootstrap_inference - id: finance-C-109 when: When implementing bootstrap data validation action: verify each input data types are numpy ndarray, pandas DataFrame, or pandas Series severity: fatal kind: architecture_guardrail modality: must consequence: Unsupported data types cause TypeError and prevent bootstrap from resampling data for inference stage_ids: - bootstrap_inference - id: finance-C-110 when: When implementing PRNG for bootstrap action: use NumPy Generator or RandomState as PRNG source severity: fatal kind: architecture_guardrail modality: must consequence: Invalid PRNG type causes TypeError and prevents bootstrap from generating random indices for resampling stage_ids: - bootstrap_inference - id: finance-C-116 when: When computing t-statistics for model parameters action: compute tvalues as the ratio of params divided by std_err severity: fatal kind: domain_rule modality: must consequence: Incorrect t-statistics will lead to wrong hypothesis testing conclusions, causing invalid statistical inference about parameter significance stage_ids: - results_reporting - id: finance-C-117 when: When computing p-values for parameter t-statistics action: compute pvalues using two-sided normal distribution survival function on absolute tvalues severity: fatal kind: domain_rule modality: must consequence: Incorrect p-values will cause wrong conclusions about parameter significance, leading to improper model specification decisions stage_ids: - results_reporting - id: finance-C-118 when: When constructing parameter confidence intervals action: compute confidence intervals using normal distribution quantile with specified alpha coverage severity: fatal kind: domain_rule modality: must consequence: Incorrect confidence interval coverage will misrepresent the precision of parameter estimates, violating statistical guarantees stage_ids: - results_reporting - id: finance-C-119 when: When computing ARCH-LM test statistic action: compute the ARCH-LM statistic as nobs multiplied by the R-squared of the auxiliary regression severity: fatal kind: domain_rule modality: must consequence: Incorrect ARCH-LM statistic will produce wrong diagnostic conclusions about remaining heteroskedasticity in model residuals stage_ids: - results_reporting - id: finance-C-120 when: When computing standard errors from parameter covariance action: extract standard errors as the square root of diagonal elements of the parameter covariance matrix severity: fatal kind: domain_rule modality: must consequence: Incorrect standard errors propagate to all downstream inference, affecting t-statistics, p-values, and confidence intervals stage_ids: - results_reporting - id: finance-C-121 when: When computing model fit statistics action: compute AIC as negative two times loglikelihood plus two times number of parameters severity: fatal kind: domain_rule modality: must consequence: Incorrect AIC will lead to wrong model selection decisions when comparing different ARCH specifications stage_ids: - results_reporting - id: finance-C-122 when: When computing Schwarz/Bayesian Information Criteria action: compute BIC as negative two times loglikelihood plus log of observations times number of parameters severity: fatal kind: domain_rule modality: must consequence: Incorrect BIC will cause improper model selection, potentially choosing over-parameterized or under-fitted models stage_ids: - results_reporting - id: finance-C-123 when: When computing adjusted R-squared action: compute adjusted R-squared using the degrees of freedom correction formula severity: fatal kind: domain_rule modality: must consequence: Incorrect adjusted R-squared will misrepresent model explanatory power after accounting for parameter count stage_ids: - results_reporting - id: finance-C-124 when: When displaying model estimation summary action: display parameter table with columns for coefficient, standard error, t-statistic, p-value, and confidence interval severity: fatal kind: architecture_guardrail modality: must consequence: Missing columns in summary output will prevent users from performing valid statistical inference on model parameters stage_ids: - results_reporting - id: finance-C-125 when: When displaying fit statistics in summary action: display R-squared, adjusted R-squared, log-likelihood, AIC, and BIC in the summary header severity: fatal kind: architecture_guardrail modality: must consequence: Missing fit statistics will prevent users from assessing model quality and performing model comparison stage_ids: - results_reporting - id: finance-C-128 when: When running ARCH-LM test for residual diagnostics action: require at least 3 non-nan observations for valid test results severity: fatal kind: domain_rule modality: must consequence: ARCH-LM test with insufficient observations produces unreliable test statistics and misleading diagnostic conclusions stage_ids: - results_reporting - id: finance-C-130 when: When computing R-squared for model fit assessment action: handle implicit constant detection to verify correct total sum of squares computation severity: fatal kind: domain_rule modality: must consequence: Incorrect R-squared when model contains implicit constant leads to wrong assessment of model explanatory power stage_ids: - results_reporting - id: finance-C-135 when: When testing ARCH-LM with default lag selection action: compute default lags using the formula ceil(12 * (nobs/100)^(1/4)) bounded by half the sample size severity: fatal kind: domain_rule modality: must consequence: Incorrect default lag selection will produce either under-powered or over-fitted ARCH-LM tests, leading to wrong diagnostic conclusions stage_ids: - results_reporting - id: finance-C-136 when: When initializing an ARCHModel with input data action: Convert y to float64 contiguous array and validate each values are finite (no NaN or inf) severity: fatal kind: domain_rule modality: must consequence: Non-finite values (NaN/inf) in the input data will cause variance computations to produce NaN, leading to failed optimization and meaningless model results stage_ids: - data_input - model_specification - id: finance-C-137 when: When converting input data to the internal representation action: Verify input y is converted to 1D float64 contiguous array via to_array_1d severity: fatal kind: domain_rule modality: must consequence: Multi-dimensional or non-contiguous arrays will cause index errors in variance recursions and parameter estimation stage_ids: - data_input - model_specification - id: finance-C-139 when: When combining starting values from mean, volatility, and distribution action: 'Concatenate starting values in the correct order: mean params, volatility params, distribution params' severity: fatal kind: domain_rule modality: must consequence: Incorrect parameter ordering will cause parameter parsing (_parse_parameters) to assign wrong values to mean/volatility/distribution, producing invalid models stage_ids: - model_specification - parameter_estimation - id: finance-C-140 when: When combining bounds from mean, volatility, and distribution action: 'Extend bounds list in the same order as parameters: mean bounds first, then volatility bounds, then distribution bounds' severity: fatal kind: domain_rule modality: must consequence: Misaligned bounds will cause SLSQP optimizer to enforce wrong constraints on wrong parameters, potentially producing invalid parameter values stage_ids: - model_specification - parameter_estimation - id: finance-C-141 when: When constructing linear constraints from each model components action: Block-diagonalize constraint matrix A so each component's constraints only affect its own parameters severity: fatal kind: domain_rule modality: must consequence: Non-block-diagonal constraints will incorrectly constrain unrelated parameters, causing optimization to fail or produce wrong parameter values stage_ids: - model_specification - parameter_estimation - id: finance-C-144 when: When passing fitted parameters from estimation to forecasting action: Parse params using _parse_parameters to extract mean/volatility/distribution parameter subsets severity: fatal kind: architecture_guardrail modality: must consequence: Using raw params array without parsing will pass wrong parameter subsets to variance recursions, producing incorrect forecasts stage_ids: - parameter_estimation - forecasting - id: finance-C-159 when: When initializing an ARCHModel with input data (y parameter) action: Provide only finite values in the data array — NaN and inf values are not permitted and cause a ValueError severity: fatal kind: domain_rule modality: must consequence: NaN or inf values in the input time series cause the model's loglikelihood computation to produce NaN results, corrupting all parameter estimates and forecasts - id: finance-C-160 when: When implementing a new VolatilityProcess subclass action: Verify each computed conditional variance values (sigma2) are non-negative throughout the variance recursion — values below the lower var_bounds are clamped up, and values above the upper bound are log-adjusted severity: fatal kind: domain_rule modality: must consequence: Negative sigma2 values cause the distribution loglikelihood to receive invalid inputs (e.g., sqrt of negative for Normal), producing NaN loglikelihood and corrupted parameter estimates - id: finance-C-161 when: When constructing variance bounds (var_bounds) for any volatility model action: Format var_bounds as a 2-column array of shape (nobs, 2) where column 0 is the lower bound and column 1 is the upper bound for each observation severity: fatal kind: domain_rule modality: must consequence: Incorrectly formatted var_bounds causes the bounds_check function to misread lower/upper bounds, allowing invalid sigma2 values to pass through and corrupt the loglikelihood - id: finance-C-162 when: When providing a user-supplied backcast value to the volatility model's backcast_transform action: Verify the backcast value is strictly positive — negative backcast values cause a ValueError severity: fatal kind: domain_rule modality: must consequence: Negative backcast causes the volatility recursion to start with an invalid initial sigma2 value, producing invalid loglikelihood values and corrupted estimates - id: finance-C-163 when: When implementing a new VolatilityProcess or Distribution subclass action: Return constraint arrays (a, b) where parameters satisfy a.dot(params) - b >= 0 for each rows of a — this linear constraint format is required by the SLSQP optimizer severity: fatal kind: domain_rule modality: must consequence: Incorrectly formatted constraint arrays cause SLSQP to receive invalid constraints, producing undefined optimization behavior and potentially invalid parameter estimates - id: finance-C-171 when: When implementing a new mean model, volatility model, or distribution action: 'Verify the concatenated parameter array follows the fixed ordering: [mean_params, vol_params, dist_params], using the pre-computed offsets array to slice each sub-parameter set' severity: fatal kind: architecture_guardrail modality: must consequence: Incorrect parameter ordering causes _parse_parameters to return wrong slices for mean, volatility, and distribution parameters, producing invalid loglikelihood values and corrupted estimates - id: finance-C-172 when: When computing the loglikelihood in the ARCHModel._loglikelihood method action: 'Follow the fixed three-step computation order: (1) compute resids from the mean model, (2) compute sigma2 using volatility.compute_variance(), (3) call distribution.loglikelihood() with the computed resids and sigma2' severity: fatal kind: architecture_guardrail modality: must consequence: Skipping or reordering any step produces an incorrect loglikelihood value, leading to wrong parameter estimates during optimization - id: finance-C-173 when: When calling forecast() on an ARCHModelResult action: Call fit() first to produce an ARCHModelResult with estimated params — forecast() requires the params attribute which is only populated after successful fit() execution severity: fatal kind: architecture_guardrail modality: must consequence: Calling forecast() before fit() causes an AttributeError because params is None, preventing any forecast generation - id: finance-C-174 when: When implementing a new VolatilityProcess subclass that is NOT ConstantVariance action: Set closed_form = False — only ConstantVariance has closed_form = True; each other volatility processes must explicitly set closed_form = False or accept the default severity: fatal kind: architecture_guardrail modality: must_not consequence: Setting closed_form = True on a non-ConstantVariance volatility process causes the fit() method to incorrectly enter the closed-form path, producing mathematically invalid parameter estimates - id: finance-C-175 when: When using the Normal/Gaussian distribution with any ARCH volatility model action: Set num_params = 0 on the Normal distribution — Normal has no additional parameters beyond those estimated by the mean and volatility models severity: fatal kind: architecture_guardrail modality: must consequence: Incorrectly setting num_params > 0 on the Normal distribution disrupts the parameter offset calculations in fit(), causing parameter slicing errors and wrong estimates - id: finance-C-210 when: When processing price and quantity data in financial calculations action: Assume infinite precision for monetary calculations using native float types — floating-point representation causes rounding errors in price aggregation and P&L computation severity: fatal kind: claim_boundary modality: must_not consequence: Using float for price and quantity causes accumulated rounding errors in high-frequency trading; a 0.01 cent error per trade compounds to significant P&L discrepancies in live trading derived_from_bd_id: BD-GAP-007 - id: finance-C-230 when: When setting APARCH model parameters in volatility estimation action: Change the delta parameter to values other than 1 when intending TARCH specification — delta=1 recovers standard absolute return specification required for threshold ARCH severity: fatal kind: architecture_guardrail modality: must_not consequence: Setting delta!=1 fundamentally alters the APARCH power transformation, breaking the TARCH nesting property and producing incorrect asymmetric volatility estimates that misrepresent downside risk derived_from_bd_id: BD-056 regular: - id: finance-C-003 when: When implementing input type detection in ARCH model action: track whether the original input was a pandas DataFrame or Series using isinstance(y, (pd.DataFrame, pd.Series)) severity: high kind: architecture_guardrail modality: must consequence: Results reporting will return incorrect types (numpy array instead of Series), breaking user API expectations and causing downstream type errors stage_ids: - data_input - id: finance-C-004 when: When implementing data input for ARCH model initialization action: store the original input data unchanged in _y_original before any transformation for results reporting severity: high kind: architecture_guardrail modality: must consequence: Results and forecasts will be reported using transformed/scaled data instead of original user input, making results unintelligible to users stage_ids: - data_input - id: finance-C-005 when: When implementing input coercion in ARCH library action: handle various input types (Series, DataFrame, numpy arrays, lists, scalars) by converting to consistent 1D format using ensure1d severity: high kind: resource_boundary modality: must consequence: Incompatible input types will raise unexpected TypeErrors, preventing users from using common data formats like pandas Series or numpy arrays stage_ids: - data_input - id: finance-C-006 when: When implementing array conversion in ARCH library action: verify each converted arrays are 1D and float64 dtype using to_array_1d for downstream numeric operations severity: high kind: resource_boundary modality: must consequence: Multi-dimensional or non-float64 arrays will cause shape mismatches in matrix operations and optimize.outer calls, producing incorrect log-likelihood values stage_ids: - data_input - id: finance-C-007 when: When implementing rescale logic in ARCH model fitting action: apply scale factor consistently to original data when rescaling is triggered, then update model state via _scale_changed() severity: high kind: architecture_guardrail modality: must consequence: Parameter estimates and forecasts will be on wrong scale, making results meaningless for users who expect outputs in original data units stage_ids: - data_input - id: finance-C-008 when: When implementing data validation in ARCH model action: raise ValueError immediately when encountering non-1D-reshapable input, with clear message indicating dimensionality requirement severity: high kind: domain_rule modality: must consequence: Multi-dimensional data will silently produce incorrect results in variance calculations, leading to misleading ARCH parameter estimates stage_ids: - data_input - id: finance-C-010 when: When implementing automatic data rescaling action: warn users when data variance is outside [0.1, 10000) range to prevent numerical instability in optimization severity: medium kind: operational_lesson modality: should consequence: Poorly scaled data causes optimizer convergence failure or excessive iterations, wasting computational resources and producing unreliable parameter estimates stage_ids: - data_input - id: finance-C-011 when: When implementing ARCH model forecasting action: claim that forecast outputs equal actual realized returns or that backtest returns predict live trading performance severity: high kind: claim_boundary modality: must_not consequence: ARCH forecasts represent conditional variance estimates based on historical patterns; presenting these as predictions of actual returns violates fundamental statistical principles and may mislead users into financial losses stage_ids: - data_input - id: finance-C-012 when: When handling pandas Series input with ensure1d action: preserve the Series name attribute during conversion when series=True, or set name from provided name parameter severity: medium kind: architecture_guardrail modality: must consequence: Results will have unlabeled or incorrectly labeled output Series, making downstream data analysis and debugging difficult stage_ids: - data_input - id: finance-C-017 when: When implementing custom volatility processes action: provide starting_values() method returning valid initial parameter values severity: high kind: domain_rule modality: must consequence: Invalid or poorly-chosen starting values cause the SLSQP optimizer to fail convergence or converge to local optima, producing suboptimal parameter estimates stage_ids: - model_specification - id: finance-C-018 when: When implementing custom volatility processes action: provide bounds() method returning list of (lower, upper) tuples for each parameter severity: high kind: domain_rule modality: must consequence: Missing bounds causes the optimizer to use unbounded parameter search, potentially producing numerically unstable or invalid parameter values stage_ids: - model_specification - id: finance-C-021 when: When using the arch library for volatility modeling action: claim real-time trading capability since arch is a pure backtesting and forecasting framework severity: high kind: claim_boundary modality: must_not consequence: Claiming live trading capability when arch only provides estimation and simulation leads to operational misuse and potential financial losses from attempting to deploy estimation-only code in production trading stage_ids: - model_specification - id: finance-C-022 when: When presenting ARCH model estimation results action: present backtest simulation results as equivalent to live trading performance severity: high kind: claim_boundary modality: must_not consequence: Simulated backtest returns systematically differ from live trading due to execution slippage, transaction costs, market impact, and liquidity constraints not captured in the estimation framework stage_ids: - model_specification - id: finance-C-023 when: When estimating ARCH models on financial time series action: claim parameter estimates are the true population parameters severity: medium kind: claim_boundary modality: must_not consequence: ARCH model parameters are estimated via maximum likelihood on finite samples, introducing estimation uncertainty. Standard errors and confidence intervals must be reported to avoid overstating precision stage_ids: - model_specification - id: finance-C-024 when: When initializing ARCHModel with default components action: use ConstantVariance as the default volatility process since it has closed-form estimation severity: medium kind: resource_boundary modality: must consequence: Using non-ConstantVariance volatility without explicit specification causes the model to require iterative optimization, increasing computation time and potential convergence issues stage_ids: - model_specification - id: finance-C-025 when: When initializing ARCHModel with default components action: use Normal distribution as the default since it has no shape parameters (closed-form fit available) severity: medium kind: resource_boundary modality: must consequence: Using heavy-tailed distributions (StudentsT, SkewStudent) without explicit selection may cause optimization to fail if starting values are poorly chosen stage_ids: - model_specification - id: finance-C-026 when: When optimizing ARCH model parameters action: use SLSQP optimizer since it supports both bound constraints and linear inequality constraints severity: high kind: resource_boundary modality: must consequence: Using optimizers without proper constraint support (L-BFGS-B, Nelder-Mead) cannot enforce ARCH parameter constraints, producing mathematically invalid models stage_ids: - model_specification - id: finance-C-027 when: When estimating ARCH models with HAR or other lag-based mean models action: set hold_back parameter to exclude pre-sample observations that would cause look-ahead bias severity: high kind: operational_lesson modality: must consequence: HAR models use historical average calculations that can include pre-sample data if hold_back is not set, causing look-ahead bias where information not yet available affects current estimates stage_ids: - model_specification - id: finance-C-028 when: When using closed-form estimation path action: verify volatility has closed_form=True AND distribution has num_params=0 AND volatility is ConstantVariance severity: medium kind: operational_lesson modality: must consequence: Failing to meet all three conditions forces the model through iterative optimization instead of closed-form estimation, significantly increasing computation time stage_ids: - model_specification - id: finance-C-032 when: When implementing volatility process starting values action: compute volatility starting values using residuals from the mean model fit severity: high kind: architecture_guardrail modality: must consequence: Using raw data instead of residuals for volatility starting values produces incorrect initial variance estimates, potentially causing divergence in optimization stage_ids: - model_specification - id: finance-C-033 when: When implementing distribution starting values action: compute distribution starting values using standardized residuals from volatility severity: high kind: architecture_guardrail modality: must consequence: Using non-standardized residuals for distribution starting values produces incorrect shape parameter initialization, especially for heavy-tailed distributions stage_ids: - model_specification - id: finance-C-034 when: When validating user-provided starting values action: check starting values satisfy both bounds and constraint inequalities before optimization severity: high kind: architecture_guardrail modality: must consequence: Starting values outside bounds or violating constraints cause the optimizer to either fail immediately or produce invalid intermediate results stage_ids: - model_specification - id: finance-C-037 when: When estimating parameter covariance matrix action: verify the parameter covariance matrix is positive definite severity: high kind: domain_rule modality: must consequence: Non-positive-definite covariance matrix produces invalid standard errors, t-statistics, and confidence intervals, corrupting statistical inference stage_ids: - parameter_estimation - id: finance-C-038 when: When constructing residuals in parameter estimation action: produce mean-zero residuals by subtracting the conditional mean severity: high kind: domain_rule modality: must consequence: Non-zero mean residuals bias volatility estimation, as the ARCH variance equation assumes mean-zero shocks, leading to systematic risk mismeasurement stage_ids: - parameter_estimation - id: finance-C-039 when: When implementing SLSQP optimization for ARCH models action: skip convergence status validation based on 'looks reasonable' assessment severity: high kind: architecture_guardrail modality: must_not consequence: Non-zero optimizer status indicates the solution may be suboptimal or infeasible, producing biased parameter estimates that corrupt volatility forecasts stage_ids: - parameter_estimation - id: finance-C-042 when: When setting up backcasting for variance recursion action: use EWMA(0.94) with tau=75 for backcast computation severity: medium kind: resource_boundary modality: must consequence: Incorrect backcast values bias initial variance estimates, affecting convergence speed and potentially producing suboptimal parameter estimates stage_ids: - parameter_estimation - id: finance-C-043 when: When executing likelihood computation in ARCH estimation action: use Numba JIT compilation with nopython=True for speed, with graceful pure Python fallback severity: medium kind: resource_boundary modality: must consequence: Without JIT compilation, likelihood evaluation becomes prohibitively slow for large datasets, making estimation impractical stage_ids: - parameter_estimation - id: finance-C-044 when: When the optimizer returns non-zero convergence status action: emit ConvergenceWarning to alert user about potential optimization difficulty severity: high kind: operational_lesson modality: must consequence: Silent acceptance of non-converged optimization produces unreliable parameter estimates that may not represent the true optimum, misleading downstream risk calculations stage_ids: - parameter_estimation - id: finance-C-045 when: When providing custom starting values for optimization action: validate starting values satisfy both bounds and inequality constraints before use severity: high kind: operational_lesson modality: must consequence: Invalid starting values cause optimization to start from an infeasible point, potentially converging to invalid parameters or failing to converge stage_ids: - parameter_estimation - id: finance-C-046 when: When estimating ARCH models with SLSQP optimizer action: tolerate non-zero convergence status as common in ARCH estimation due to constraint boundaries severity: medium kind: operational_lesson modality: must consequence: Treating non-zero status as fatal error prevents valid estimates from being returned when optimizer reaches constraint boundaries (common in volatility models) stage_ids: - parameter_estimation - id: finance-C-047 when: When presenting ARCH model estimation results action: claim that backtested volatility forecasts equal expected live trading performance severity: high kind: claim_boundary modality: must_not consequence: ARCH volatility estimates are conditional on historical data; structural breaks, regime changes, and market conditions cause live performance to diverge from backtested results stage_ids: - parameter_estimation - id: finance-C-048 when: When computing parameter covariance using numerical derivatives action: skip numerical Hessian inversion when hessian is near-singular severity: high kind: domain_rule modality: must_not consequence: Near-singular Hessian indicates model identification issues; blind matrix inversion produces unreliable standard errors and invalid inference stage_ids: - parameter_estimation - id: finance-C-049 when: When the optimizer status is non-zero but parameters look reasonable action: dismiss the convergence warning as 'false alarm' without investigation severity: high kind: rationalization_guard modality: must_not consequence: Dismissing convergence warnings based on superficial parameter inspection ignores constraint boundary conditions that invalidate stationarity guarantees stage_ids: - parameter_estimation - id: finance-C-050 when: When constraints appear satisfied and optimization completes action: skip validation that each inequality constraints a.dot(params) - b >= 0 hold for final parameters severity: medium kind: rationalization_guard modality: must_not consequence: Optimizer may return parameters at constraint boundaries that technically satisfy a.dot(params) - b >= 0 but produce numerically unstable or invalid variance forecasts stage_ids: - parameter_estimation - id: finance-C-053 when: When implementing multi-step ARCH variance forecasting action: verify first-horizon multi-step variance equals one-step variance due to ARCH model structure severity: high kind: domain_rule modality: must consequence: Violation indicates incorrect implementation of ARCH recursion, causing forecast variance to diverge from true model dynamics at h=1 stage_ids: - forecasting - id: finance-C-057 when: When using bootstrap forecasting method action: require at least 10 initial observations and horizon/start ratio less than 20% severity: high kind: resource_boundary modality: must consequence: Bootstrap with insufficient burn-in or excessive extrapolation ratio produces unreliable variance estimates with high sampling bias stage_ids: - forecasting - id: finance-C-058 when: When setting simulation count for Monte Carlo forecasting action: use default of 1000 simulations to balance Monte Carlo error against computation time severity: medium kind: resource_boundary modality: should consequence: Insufficient simulations increase variance of forecast estimates; excessive simulations waste computation without meaningful accuracy gains stage_ids: - forecasting - id: finance-C-059 when: When forecasting with FixedVariance volatility process action: rely on simulation method producing meaningful variance forecasts severity: high kind: resource_boundary modality: must_not consequence: FixedVariance process returns NaN for all forecast paths when using simulation method, as the variance is predetermined and cannot be simulated stage_ids: - forecasting - id: finance-C-060 when: When forecasting with ARCHInMean models action: attempt to generate forecasts as this model variant does not support prediction severity: high kind: resource_boundary modality: must_not consequence: ARCHInMean models raise NotImplementedError because the ARCH-in-mean specification makes multi-step forecasting mathematically undefined stage_ids: - forecasting - id: finance-C-061 when: When validating simulation output shape action: verify simulated_paths/variances have shape (horizons x simulations x reindex_dim) severity: high kind: operational_lesson modality: must consequence: Incorrect simulation shape causes downstream indexing errors or silent misalignment between forecast paths and their variance estimates stage_ids: - forecasting - id: finance-C-062 when: When forecasting models with exogenous regressors action: limit horizon to 1 or accept NaN-filled columns for multi-step forecasts severity: medium kind: operational_lesson modality: must consequence: Multi-step exogenous variable forecasts require aligned out-of-sample values that are typically unavailable, producing NaN columns stage_ids: - forecasting - id: finance-C-065 when: When validating forecasting capability before computation action: call _check_forecasting_method to verify method compatibility with model type and horizon severity: high kind: architecture_guardrail modality: must consequence: Skipping method validation allows unsupported forecast types (e.g., EGARCH analytic multi-step) to reach computation stage stage_ids: - forecasting - id: finance-C-066 when: When using bootstrap method for variance forecasting action: wrap standardized residual sampling through BootstrapRng to enable simulation-based path generation severity: high kind: architecture_guardrail modality: must consequence: Direct bootstrap sampling without BootstrapRng wrapper produces non-reproducible results and breaks the RNG interface contract for simulation paths stage_ids: - forecasting - id: finance-C-067 when: When presenting simulation-based forecast results action: claim exact reproducibility without setting random_state or provide identical random seed severity: medium kind: claim_boundary modality: must_not consequence: Simulation paths contain inherent Monte Carlo randomness; presenting them as deterministic produces misleading risk estimates stage_ids: - forecasting - id: finance-C-069 when: When using simulation or bootstrap methods action: recognize that forecast variance estimates contain Monte Carlo sampling error severity: medium kind: claim_boundary modality: must consequence: With finite simulations (default 1000), variance estimates have standard error proportional to 1/sqrt(simulations). Claims of point precision are statistically invalid stage_ids: - forecasting - id: finance-C-078 when: When implementing PhillipsPerron automatic lag selection action: use the formula 12 * (nobs/100)^(1/4) as the default when lags is None severity: high kind: resource_boundary modality: must consequence: Non-standard lag selection produces inconsistent long-run variance estimates and invalid PP test statistics across implementations stage_ids: - unitroot_testing - id: finance-C-079 when: When implementing PhillipsPerron test action: allow lag parameter to exceed available observations for covariance estimation severity: high kind: resource_boundary modality: must_not consequence: Excessive lags relative to observations cause ill-conditioned long-run covariance matrices, producing unreliable PP test statistics stage_ids: - unitroot_testing - id: finance-C-082 when: When running unit root tests with automatic lag selection action: warn users when max_lags is large relative to sample size due to performance impact severity: medium kind: operational_lesson modality: should consequence: Large lag search spaces with many observations cause slow computation without proportional statistical benefit stage_ids: - unitroot_testing - id: finance-C-088 when: When implementing unit root test base class action: make _check_specification and _compute_statistic abstract methods requiring subclass implementation severity: high kind: architecture_guardrail modality: must consequence: Missing abstract method enforcement allows instantiation of incomplete test classes that lack core computation logic stage_ids: - unitroot_testing - id: finance-C-089 when: When using unit root test results for trading decisions action: claim unit root test results as predictions of future price behavior severity: high kind: claim_boundary modality: must_not consequence: Unit root tests are statistical hypothesis tests on historical data, not forecasts; presenting stationarity conclusions as trading signals misleads stakeholders stage_ids: - unitroot_testing - id: finance-C-090 when: When presenting cointegration test results action: claim cointegration implies causal trading relationships severity: high kind: claim_boundary modality: must_not consequence: Cointegration only indicates statistical equilibrium relationships; presenting it as evidence of profitable pairs trading without proper risk management overstates the capability stage_ids: - unitroot_testing - id: finance-C-091 when: When using critical values for unit root tests action: claim asymptotic critical values are exact for finite samples severity: medium kind: claim_boundary modality: must_not consequence: MacKinnon critical values are asymptotic approximations; presenting them as precise thresholds for small samples overstates test accuracy and may lead to incorrect conclusions stage_ids: - unitroot_testing - id: finance-C-092 when: When running multiple unit root tests on the same series action: select the test with most favorable p-value without pre-specification justification severity: medium kind: claim_boundary modality: should_not consequence: Multiple testing without correction inflates Type I error rate; selecting favorable results misleads about statistical evidence for stationarity stage_ids: - unitroot_testing - id: finance-C-099 when: When initializing bootstrap for confidence intervals action: use default method='basic' for confidence interval calculation severity: medium kind: resource_boundary modality: must consequence: Using non-basic methods without understanding tradeoffs may produce incorrect coverage; basic is simplest and matches default behavior expected by the framework stage_ids: - bootstrap_inference - id: finance-C-100 when: When initializing bootstrap for confidence intervals action: use default sampling='nonparametric' severity: medium kind: resource_boundary modality: must consequence: Nonparametric is the safest default; parametric/semiparametric require specific assumptions that may not hold stage_ids: - bootstrap_inference - id: finance-C-101 when: When initializing bootstrap for confidence intervals action: use at least 1000 bootstrap replications for stable estimates severity: high kind: resource_boundary modality: must consequence: Fewer than 1000 reps produces high-variance confidence intervals with poor coverage, leading to unreliable statistical inference and potentially wrong conclusions stage_ids: - bootstrap_inference - id: finance-C-102 when: When implementing MCS or SPA multiple comparison procedures action: default block_size to sqrt(T) when not provided severity: high kind: resource_boundary modality: must consequence: Wrong block size invalidates time-series bootstrap standard errors; sqrt(T) is theoretically justified for block bootstraps stage_ids: - bootstrap_inference - id: finance-C-104 when: When initializing MCS action: default MCS test size to 0.05 (5% significance level) severity: low kind: resource_boundary modality: should consequence: Non-standard significance levels may not be appropriate for model selection; 0.05 is conventional stage_ids: - bootstrap_inference - id: finance-C-105 when: When implementing BCa confidence intervals action: compute acceleration parameter using jackknife estimation severity: high kind: operational_lesson modality: must consequence: BCa without proper jackknife acceleration produces biased confidence intervals that fail to achieve nominal coverage stage_ids: - bootstrap_inference - id: finance-C-108 when: When initializing any bootstrap class for reproducibility action: pass seed parameter (int, Generator, or RandomState) to enable reproducible results severity: high kind: architecture_guardrail modality: must consequence: Without seed, each run produces different bootstrap replicates, preventing reproducible inference and making results impossible to verify stage_ids: - bootstrap_inference - id: finance-C-111 when: When implementing bootstrap state management action: use reset() to restore initial state or reset with new seed severity: medium kind: architecture_guardrail modality: must consequence: Without proper reset, bootstrap continues from current state causing reproducibility issues in sequential inference stage_ids: - bootstrap_inference - id: finance-C-112 when: When using bootstrap confidence intervals action: claim bootstrap CI coverage is exact for finite samples severity: high kind: claim_boundary modality: must_not consequence: Bootstrap confidence intervals are asymptotically valid; claiming exact finite-sample coverage is misleading and violates statistical theory stage_ids: - bootstrap_inference - id: finance-C-113 when: When using MCS model confidence set action: claim MCS produces guaranteed model rankings severity: high kind: claim_boundary modality: must_not consequence: MCS produces confidence set of models, not rankings; claiming guaranteed ranking is statistically incorrect stage_ids: - bootstrap_inference - id: finance-C-114 when: When using SPA test of Superior Predictive Ability action: claim SPA p-values have exact finite-sample distribution severity: high kind: claim_boundary modality: must_not consequence: SPA uses bootstrap p-values that are asymptotically calibrated; exact finite-sample distribution is unknown stage_ids: - bootstrap_inference - id: finance-C-115 when: When implementing MCS with identical loss values action: handle standard deviation of 0 in loss differences with warning severity: high kind: operational_lesson modality: must consequence: Identical losses produce zero variance, causing division by zero and invalid MCS computation with RuntimeWarning issued stage_ids: - bootstrap_inference - id: finance-C-126 when: When displaying model results summary action: organize parameters into separate tables for Mean Model, Volatility Model, and Distribution severity: high kind: architecture_guardrail modality: must consequence: Flat parameter listing without model component separation obscures model structure and complicates interpretation stage_ids: - results_reporting - id: finance-C-127 when: When outputting results using statsmodels Summary action: use statsmodels SimpleTable and Summary classes for consistent output formatting severity: high kind: architecture_guardrail modality: must consequence: Non-standard output formatting will break compatibility with Jupyter notebooks and the econometrics ecosystem stage_ids: - results_reporting - id: finance-C-129 when: When optimizer indicates failed convergence action: display convergence warning in summary output with optimizer message severity: high kind: architecture_guardrail modality: must consequence: Silent convergence failure will produce unreliable parameter estimates that appear valid but are actually suboptimal stage_ids: - results_reporting - id: finance-C-131 when: When presenting ARCH-LM test results to users action: claim that a significant ARCH-LM test indicates adequate model specification severity: high kind: claim_boundary modality: must_not consequence: A significant ARCH-LM p-value means remaining ARCH effects exist, indicating the model is misspecified - claiming otherwise misleads users stage_ids: - results_reporting - id: finance-C-132 when: When presenting R-squared values from ARCH model estimation action: claim that high R-squared indicates good volatility forecasting ability severity: medium kind: claim_boundary modality: must_not consequence: R-squared measures mean model fit, not volatility model adequacy; ARCH models are estimated for volatility forecasting, not point prediction stage_ids: - results_reporting - id: finance-C-133 when: When visualizing forecast results with hedgehog plots action: align forecast spines with actual historical values at the forecast origin severity: high kind: domain_rule modality: must consequence: Misaligned hedgehog plot spines will mislead users about the timing and accuracy of forecasts relative to actual observations stage_ids: - results_reporting - id: finance-C-134 when: When using matplotlib for visualization action: handle matplotlib version compatibility for date plotting methods severity: medium kind: resource_boundary modality: should consequence: Incompatibility with matplotlib version < 3.10 will cause date axis plotting failures in hedgehog and residual plots stage_ids: - results_reporting - id: finance-C-138 when: When passing data between data_input and model_specification action: Preserve the hold_back parameter when excluding initial observations from estimation severity: high kind: architecture_guardrail modality: must consequence: Incorrect hold_back handling will cause the first hold_back observations to be incorrectly included or excluded from parameter estimation stage_ids: - data_input - model_specification - id: finance-C-142 when: When computing variance bounds for use in loglikelihood action: Pass variance_bounds computed from residuals to each variance recursion calls to prevent NaN in loglikelihood severity: high kind: domain_rule modality: must consequence: Without variance bounds, extreme variance values will produce -inf loglikelihood, causing optimizer to fail or produce invalid parameters stage_ids: - model_specification - parameter_estimation - id: finance-C-143 when: When validating user-provided starting values action: Check starting values satisfy both bounds AND linear constraints before passing to optimizer severity: high kind: domain_rule modality: must consequence: Invalid starting values that violate constraints will cause SLSQP to fail immediately or produce undefined behavior in optimization stage_ids: - model_specification - parameter_estimation - id: finance-C-145 when: When passing backcast and var_bounds to forecasting action: Use the same backcast and variance_bounds computed during estimation, not recomputed values severity: high kind: architecture_guardrail modality: must consequence: Recomputing backcast/var_bounds may produce slightly different values, breaking alignment between in-sample fit and out-of-sample forecasts stage_ids: - parameter_estimation - forecasting - id: finance-C-146 when: When computing multi-step variance forecasts action: Verify horizon is >= 1 and uses only variance forecasting method supported by the volatility model severity: high kind: domain_rule modality: must consequence: Using unsupported forecasting method (e.g., analytic for EGARCH multi-step) will raise ValueError or produce mathematically incorrect forecasts stage_ids: - parameter_estimation - forecasting - id: finance-C-147 when: When passing ARCHModelResult to results reporting action: Populate residuals array with NaN in positions outside estimation window (first_obs:last_obs) severity: medium kind: architecture_guardrail modality: must consequence: Without NaN padding, users cannot distinguish observations excluded from estimation from actual zero residuals, causing misinterpretation of results stage_ids: - parameter_estimation - results_reporting - id: finance-C-148 when: When reporting ARCHModelResult summary action: Report both fit_start and fit_stop indices to indicate which observations were used in estimation severity: medium kind: architecture_guardrail modality: must consequence: Without explicit fit window reporting, users may incorrectly analyze residuals or apply forecasts to wrong time periods stage_ids: - parameter_estimation - results_reporting - id: finance-C-149 when: When passing bootstrap results to results reporting action: Return confidence intervals with shape (2, num_params) where row 0 is lower bounds and row 1 is upper bounds severity: high kind: architecture_guardrail modality: must consequence: Incorrect confidence interval shape will cause downstream reporting to display wrong bounds or raise dimension errors stage_ids: - bootstrap_inference - results_reporting - id: finance-C-150 when: When computing Model Confidence Set (MCS) p-values action: Return p-values in DataFrame format with model indices as rows severity: high kind: architecture_guardrail modality: must consequence: Wrong format will cause downstream model selection to fail or select wrong models stage_ids: - bootstrap_inference - results_reporting - id: finance-C-151 when: When computing SPA (Reality Check) p-values action: Return three p-values (lower, consistent, upper) to account for test's one-sided nature severity: high kind: domain_rule modality: must consequence: Single p-value ignores the SPA's multiple-testing correction, leading to incorrect model selection decisions stage_ids: - bootstrap_inference - results_reporting - id: finance-C-152 when: When computing unit root test statistics action: Store stat, pvalue, and critical_values (dict with keys 1%, 5%, 10%) in the result object severity: high kind: architecture_guardrail modality: must consequence: Missing critical values will prevent users from making decisions using critical-value-based thresholds instead of p-values stage_ids: - unitroot_testing - results_reporting - id: finance-C-153 when: When returning cointegration test results action: Include cointegrating_vector in the result so users can implement the discovered relationship severity: high kind: architecture_guardrail modality: must consequence: Without the cointegrating vector, users cannot implement the discovered long-run equilibrium relationship between variables stage_ids: - unitroot_testing - results_reporting - id: finance-C-154 when: When validating unit root test lags parameter action: Reject negative lag values as they are mathematically invalid severity: high kind: domain_rule modality: must consequence: Negative lags will produce undefined behavior in the test regression or raise cryptic errors downstream stage_ids: - unitroot_testing - results_reporting - id: finance-C-155 when: When passing forecast results to reporting action: Return mean, variance, and residual_variance as DataFrames aligned by index severity: high kind: architecture_guardrail modality: must consequence: Misaligned forecasts will cause incorrect visualization and summary statistics in results reporting stage_ids: - forecasting - results_reporting - id: finance-C-156 when: When creating hedgehog forecast plot data action: Pad forecasts with NaN for dates before the earliest forecastable date to prevent look-ahead bias in visualization severity: medium kind: domain_rule modality: must consequence: Without NaN padding, the hedgehog plot will display incorrect forecast trajectories that include in-sample information stage_ids: - forecasting - results_reporting - id: finance-C-157 when: When forecasting with align='target' action: Align forecasts so that column h contains h-step ahead forecast from time t-h, matching evaluation methodology severity: high kind: domain_rule modality: must consequence: Misaligned target forecasts will show incorrect alignment between realizations and forecasts, invalidating forecast evaluation metrics stage_ids: - forecasting - results_reporting - id: finance-C-158 when: When using bootstrap forecasting method action: Require at least 10 initial observations and horizon/start ratio < 0.2 for valid bootstrap severity: high kind: resource_boundary modality: must consequence: Insufficient initial observations for bootstrap will produce unstable variance estimates and unreliable forecasts stage_ids: - forecasting - results_reporting - id: finance-C-164 when: When using a GARCH volatility model with power not equal to 2.0 action: Request analytic forecasting method for horizon > 1 — only 'simulation' or 'bootstrap' are valid forecasting methods for non-square-power GARCH models severity: high kind: domain_rule modality: must_not consequence: Using method='analytic' with power!=2.0 at horizon > 1 raises a ValueError and produces no forecast, forcing re-estimation or re-configuration - id: finance-C-165 when: When using an EGARCH volatility model action: Request analytic forecasting method for horizon > 1 — EGARCH does not support analytic multi-step variance forecasts severity: high kind: domain_rule modality: must_not consequence: Using method='analytic' with EGARCH at horizon > 1 raises a ValueError, preventing multi-step forecast generation - id: finance-C-166 when: When determining the estimation path in ARCHModel.fit() action: 'The closed-form estimation path is only taken when each three conditions hold simultaneously: volatility.closed_form=True, distribution.num_params=0, and isinstance(volatility, ConstantVariance) — if any condition fails, use the general SLSQP optimization path' severity: high kind: architecture_guardrail modality: must consequence: Attempting to use the closed-form path without all conditions met causes incorrect parameter estimates or AttributeErrors, as the closed-form formulas are specific to the ConstantVariance + Normal combination - id: finance-C-167 when: When calling the forecast() method on an ARCHModel or ARCHModelResult action: 'Use only one of the three explicitly supported ForecastingMethod values: ''analytic'', ''simulation'', or ''bootstrap'' — any other string raises a TypeError' severity: high kind: architecture_guardrail modality: must consequence: Using an unsupported forecasting method string causes a TypeError in the function call chain, preventing forecast generation - id: finance-C-168 when: When configuring unit root tests (ADF, DFGLS, Phillips-Perron, KPSS, Zivot-Andrews, VarianceRatio) action: 'Use only one of the four explicitly supported trend specifications: ''n'' (no constant), ''c'' (constant only), ''ct'' (constant and time trend), or ''ctt'' (constant, time trend, and squared time trend)' severity: high kind: architecture_guardrail modality: must consequence: Using an unsupported trend specification causes a TypeError or produces statistically incorrect test results with wrong degrees of freedom - id: finance-C-169 when: When configuring parameter covariance estimation in ARCHModel.fit() action: Use only 'robust' or 'classic' for the cov_type parameter — 'robust' uses the sandwich estimator with numerical derivatives, 'classic' uses the inverse Hessian severity: high kind: architecture_guardrail modality: must consequence: Using an unsupported cov_type value causes incorrect standard errors and invalid inference (wrong t-statistics, p-values, and confidence intervals) - id: finance-C-170 when: When calling forecast() on an ARCHModel or ARCHModelResult action: Use only 'origin' or 'target' for the align parameter — 'origin' aligns forecasts by their information origin time, 'target' aligns by the forecast target time severity: high kind: architecture_guardrail modality: must consequence: Using an unsupported align value causes a TypeError and prevents forecast computation - id: finance-C-176 when: When initializing any bootstrap class (IIDBootstrap, CircularBlockBootstrap, StationaryBootstrap, MovingBlockBootstrap) action: 'Pass the index parameter as one of the three supported types: an Int64Array1D, a tuple of Int64Array1D, or a tuple of (list of Int64Array1D, dict of Int64Array1D) — matching the BootstrapIndexT union type' severity: high kind: architecture_guardrail modality: must consequence: Passing an unsupported index type causes the bootstrap to produce invalid resampled indices, corrupting all bootstrap confidence intervals, p-values, and covariance estimates - id: finance-C-177 when: When estimating any ARCH model and the variance of input residuals is outside [0.1, 10000.0) action: Allow automatic rescaling of the data or provide explicit rescale=True — the _check_scale function automatically rescales data outside this range by powers of 10 to avoid numerical issues in the optimizer severity: medium kind: operational_lesson modality: should consequence: Data with variance outside [0.1, 10000) causes the SLSQP optimizer to converge slowly or fail to find the optimal parameters, producing suboptimal or invalid estimates - id: finance-C-178 when: When presenting or reporting results from this package to users action: Claim that the package supports real-time streaming data analysis — it is a batch statistical estimation library that operates on static historical time series severity: high kind: claim_boundary modality: must_not consequence: Users attempt to integrate the package into real-time trading pipelines expecting live data ingestion, leading to system failures when the package cannot process streaming data - id: finance-C-179 when: When presenting or reporting this system's capabilities action: Claim support for high-frequency trading systems requiring sub-second latency — the package performs batch maximum-likelihood estimation unsuitable for latency-critical applications severity: high kind: claim_boundary modality: must_not consequence: Users deploy the package in HFT contexts where sub-second decision-making is required, causing severe financial losses due to estimation latency - id: finance-C-180 when: When presenting or reporting this system's capabilities action: Claim support for multivariate volatility models — the package only implements univariate ARCH/GARCH variants; users requiring multivariate volatility must use the rpy2 port of the R package 'rmgarch' severity: high kind: claim_boundary modality: must_not consequence: Users attempt to model multivariate volatility correlations using the univariate package, producing incorrect risk estimates and wrong portfolio allocation decisions - id: finance-C-181 when: When presenting or reporting this system's capabilities action: Claim support for structural break detection beyond unit root tests — the package's unit root tests cannot detect multiple structural breaks; users requiring this should use dedicated structural change packages severity: medium kind: claim_boundary modality: must_not consequence: Users rely on unit root tests for structural break detection, missing multiple breaks that invalidate the entire time-series model specification - id: finance-C-182 when: When presenting or reporting this system's capabilities action: Claim drag-and-drop GUI interfaces — the package is a Python API-only library with no graphical user interface; users requiring GUI access must build their own wrappers severity: medium kind: claim_boundary modality: must_not consequence: Users expect a graphical interface and cannot use the package's Python API, wasting development resources on attempting to find a non-existent GUI - id: finance-C-183 when: When presenting or reporting this system's capabilities action: Claim that this package supports live trading — it is a pure backtesting and statistical estimation library with no exchange connectivity, order execution, or portfolio management capabilities severity: high kind: claim_boundary modality: must_not consequence: Users connect the package directly to a brokerage expecting automated trade execution, causing unintended market orders to be placed with real capital - id: finance-C-184 when: When presenting or reporting this system's backtested or estimated returns to users action: Claim that estimated model parameters or historical backtest results equal expected future performance — past ARCH model estimates do not predict future volatility or returns severity: high kind: claim_boundary modality: must_not consequence: Users make live capital allocation decisions based on inflated historical estimates, leading to severe underperformance when market regimes shift away from the estimation period - id: finance-C-185 when: When presenting or reporting volatility forecasts to users action: Claim that model-based forecasts fully account for market microstructure costs — forecasts ignore market impact, bid-ask spread, financing costs, slippage, and execution delays severity: high kind: claim_boundary modality: must_not consequence: Users incorporate ARCH forecasts directly into live trading strategies without adjusting for execution costs, producing strategies that appear profitable in backtests but lose money in live trading after costs - id: finance-C-186 when: When implementing GARCH volatility model configuration in arch package action: Use GARCH(1,1) with power=2.0 as the default configuration — verify default p=1, q=1 parameters are used unless explicit model selection is performed; for asymmetric volatility, use GJR-GARCH; for log-volatility use EGARCH severity: high kind: domain_rule modality: must consequence: Using non-standard GARCH parameters (p>1, q>1) without sufficient data causes unreliable volatility estimates, leading to incorrect risk forecasts and poor hedging decisions in live trading derived_from_bd_id: BD-001 - id: finance-C-187 when: When using GARCH model with non-standard power parameter action: Use simulation-based forecasting when power != 2.0 — analytic forecast methods are only available for standard GARCH (power=2.0); verify forecast method is explicitly set to simulation if power differs from default severity: high kind: domain_rule modality: must consequence: Using analytic forecasting with power != 2.0 produces incorrect forecast values since closed-form solutions do not exist for non-standard power specifications, causing systematic mispricing in option hedging and VaR calculations derived_from_bd_id: BD-060 - id: finance-C-188 when: When configuring backcast parameters for GARCH model initialization action: Verify backcast tau calculation matches min(75, nobs) formula — for samples smaller than 75, tau should equal nobs; for larger samples, tau should equal 75; changing decay factor from 0.94 affects backcast smoothness and initial variance estimates severity: medium kind: operational_lesson modality: should consequence: Incorrect backcast tau calculation produces biased initial variance estimates, affecting the accuracy of short-term volatility forecasts which are critical for intraday risk management and option pricing derived_from_bd_id: BD-066 - id: finance-C-189 when: When testing for cointegration between two financial time series action: Apply Engle-Granger two-step cointegration test using OLS regression followed by ADF test on residuals — this method applies to bivariate relationships only; use MacKinnon critical values for significance determination severity: high kind: domain_rule modality: must consequence: Using univariate time series methods for cointegration testing incorrectly identifies or misses cointegrating relationships, causing pairs trading strategies to trade on spurious relationships or miss profitable opportunities derived_from_bd_id: BD-042 - id: finance-C-190 when: When calculating returns for downstream performance metrics action: Verify that 100 * pct_change() scaling matches the expected annualization multiplier (12x for percentage returns) used in Sharpe ratio and other risk-adjusted performance calculations severity: medium kind: operational_lesson modality: should consequence: Using log returns without adjusting the annualization multiplier from 12x to sqrt(12) causes systematic mismeasurement of risk-adjusted performance, making strategies appear more or less attractive than they actually are derived_from_bd_id: BD-003 - id: finance-C-191 when: When computing Sharpe ratio or other risk-adjusted performance metrics action: 'Verify the annualization multiplier matches the return scaling convention: use 12x for percentage returns (100*pct_change) or sqrt(12) for log returns; document the dependency explicitly in strategy analysis code' severity: medium kind: operational_lesson modality: should consequence: Mismatch between return scaling convention and annualization assumption creates systematic mismeasurement of risk-adjusted performance, causing strategies to appear more or less attractive than their true performance derived_from_bd_id: BD-074 - id: finance-C-192 when: When implementing optimization or fitting methods for ARCH models action: Assume the framework provides comprehensive convergence diagnostics beyond scipy status codes — the current convergence_flag only returns status codes without iteration history, log-likelihood path, or parameter trajectory data severity: high kind: claim_boundary modality: must_not consequence: Without trajectory data, local optima issues in complex ARCH models cannot be diagnosed post-hoc, leading to unreliable parameter estimates being used in production strategies derived_from_bd_id: BD-GAP-016 - id: finance-C-193 when: When fitting complex ARCH models requiring convergence quality assessment action: 'Implement or use a ConvergenceDiagnosis object that stores: iteration history, log-likelihood path, and parameter trajectory for post-hoc assessment of convergence quality to diagnose local optima issues' severity: high kind: domain_rule modality: must consequence: Fitting complex ARCH models without convergence diagnostics prevents diagnosis of local optima issues, causing unreliable parameter estimates to be used in production strategies derived_from_bd_id: BD-GAP-016 - id: finance-C-194 when: When running simulation/bootstrap forecasting action: Verify that 1000 simulations (Monte Carlo SE ≈ 3.2%) provides sufficient precision for the intended use case; for extreme quantile estimation such as VaR at 99%, increase to 10000+ simulations to achieve stable tail estimates severity: medium kind: operational_lesson modality: should consequence: Using 1000 simulations for extreme quantile estimation produces unstable VaR estimates with high variance, leading to either excessive capital reserves or underestimation of tail risk derived_from_bd_id: BD-005 - id: finance-C-195 when: When initializing variance in EWMA volatility models action: Verify that lambda=0.94 decay rate and tau=75 observation window (~3 months of daily data) align with your data frequency and volatility characteristics before using default backcast values severity: medium kind: operational_lesson modality: should consequence: Default EWMA parameters may not match asset-specific volatility dynamics, causing systematic initialization bias that propagates through all forecasts derived_from_bd_id: BD-006 - id: finance-C-196 when: When selecting power specification for APARCH or TARCH volatility models action: Verify power parameter before selecting forecast method; power!=2 automatically switches from analytic to simulation-based forecasting with different computational cost and replication requirements severity: high kind: domain_rule modality: must consequence: Selecting non-quadratic power models without understanding the forecast method switch causes unexpected runtime increases and potentially insufficient simulation replications for stable tail estimates derived_from_bd_id: BD-077 - id: finance-C-197 when: When relying on Bollerslev-Wooldridge robust standard errors for inference action: Assume robust SE corrects inference only when the conditional variance specification is approximately correct; model misspecification such as ignoring leverage effects makes robust SE unreliable despite appearing to correct standard errors severity: high kind: operational_lesson modality: must_not consequence: Robust standard errors provide false confidence when the GARCH specification is misspecified, leading to invalid hypothesis tests and potentially wrong conclusions about coefficient significance derived_from_bd_id: BD-080 - id: finance-C-198 when: When selecting bootstrap block length for time series resampling action: Verify sqrt(T) rule-of-thumb against Politis-White optimal block calculation; for highly persistent series, larger blocks than sqrt(T) may be needed to account for long memory severity: medium kind: operational_lesson modality: should consequence: Using sqrt(T) default block length for highly persistent series inflates bootstrap variance and produces unreliable confidence intervals, leading to incorrect statistical inference derived_from_bd_id: BD-079 - id: finance-C-199 when: When implementing or refactoring RiskMetrics2006 variance calculations action: Maintain lambda=0.94 as the fixed decay factor for EWMA recursion, as this is the RiskMetrics 2006 industry standard for balancing responsiveness and stability in variance estimation severity: high kind: domain_rule modality: must consequence: Changing lambda from the RiskMetrics 2006 standard of 0.94 breaks comparability with industry benchmarks and produces variance estimates that do not reflect the intended balance between responsiveness and stability, potentially leading to misaligned risk management decisions derived_from_bd_id: BD-036 - id: finance-C-200 when: When implementing volatility model selection for time series with long-memory characteristics action: Use GARCH instead of FIGARCH for series exhibiting long-memory — GARCH cannot capture hyperbolic decay in volatility autocorrelation; FIGARCH(1,d,1) with fractional differencing parameter d in (0,0.5) is required severity: high kind: domain_rule modality: must_not consequence: Substituting GARCH for FIGARCH when modeling long-memory volatility causes the model to miss the characteristic hyperbolic decay pattern, leading to materially incorrect variance forecasts that distort risk estimates and hedging ratios derived_from_bd_id: BD-039 - id: finance-C-201 when: When implementing DFGLS unit root test for stationarity detection action: Apply GLS detrending (ERS 1996) before Dickey-Fuller regression in the DFGLS variant — standard OLS detrending must not be used as it provides materially lower test power severity: high kind: domain_rule modality: must consequence: Using OLS detrending instead of GLS detrending in DFGLS reduces test power below the designed efficiency gains, causing higher rates of failing to detect actual unit roots and leading to false conclusions about stationarity derived_from_bd_id: BD-041 - id: finance-C-202 when: When implementing cointegrating vector estimation for bivariate or multivariate relationships action: Add leads and lags of differenced regressors (Dynamic OLS) to address endogeneity in the cointegrating regression — static OLS without augmentation must not be used severity: high kind: domain_rule modality: must consequence: Using static OLS without lead/lag augmentation introduces endogeneity bias that violates the super-consistency property of cointegration estimators, producing inconsistent coefficient estimates that invalidate the identified long-run relationship derived_from_bd_id: BD-043 - id: finance-C-203 when: When implementing volatility calculations in backtesting or production code action: Assume the framework provides a built-in annualized_volatility() helper function with configurable compounding convention — no such standardized helper exists in the current framework severity: high kind: claim_boundary modality: must_not consequence: Without a standardized annualization helper, users apply inconsistent formulas, leading to incorrect risk estimates and strategy comparisons that diverge from live trading results derived_from_bd_id: BD-GAP-017 - id: finance-C-204 when: When implementing volatility calculations in backtesting or production code action: Implement an explicit annualized_volatility() helper that accepts configurable compounding convention (252 for daily trading days, 365 for calendar days, simple for no compounding) and documents that input volatility is in frequency-of-data units severity: high kind: domain_rule modality: must consequence: Without explicit annualization, users apply inconsistent formulas causing systematic risk mis-estimation that compounds over time in live trading derived_from_bd_id: BD-GAP-017 - id: finance-C-205 when: When implementing GARCH model evaluation workflows in backtesting action: Assume the framework provides a standardized backtest validation framework with automatic train/test splits and VaR/CVaR/realized PnL tracking — no such framework exists in the current implementation severity: high kind: claim_boundary modality: must_not consequence: Without standardized backtest methodology, users implement ad-hoc validation that fails to detect GARCH forecast failures, leading to live trading losses from unvalidated volatility predictions derived_from_bd_id: BD-GAP-018 - id: finance-C-206 when: When implementing GARCH model evaluation workflows in backtesting action: Implement a backtest validation framework that includes automatic train/test split for time series, historical VaR/CVaR tracking against realized PnL, and diagnostic plots for volatility model evaluation severity: high kind: domain_rule modality: must consequence: Without standardized backtest validation, GARCH forecast failures go undetected until live trading, causing significant financial losses from incorrect volatility predictions derived_from_bd_id: BD-GAP-018 - id: finance-C-207 when: When implementing or extending GARCH model parameter extraction and constraint application action: Use hardcoded parameter indices without computed offsets — parameter ordering follows [mean_params, vol_params, dist_params] with dynamically computed offsets during fit() severity: high kind: claim_boundary modality: must_not consequence: Direct index access assuming fixed parameter ordering breaks custom GARCH variants; constraint application fails silently causing invalid optimization results derived_from_bd_id: BD-GAP-015 - id: finance-C-208 when: When implementing or extending GARCH model parameter extraction and constraint application action: Always use dynamically computed offsets from the model to access parameter indices; validate that offsets remain within bounds before parameter extraction severity: high kind: domain_rule modality: must consequence: Without using computed offsets, custom GARCH variants with non-standard parameter counts cause index out-of-bounds errors or silently corrupted parameter values derived_from_bd_id: BD-GAP-015 - id: finance-C-209 when: When configuring starting values for GARCH optimization action: Validate GARCH starting values against stationarity constraints (alpha >= 0, gamma >= 0, beta >= 0, alpha + gamma + beta < 1) before passing to optimizer severity: high kind: domain_rule modality: must consequence: The fixed grid search may produce invalid starting values for non-standard GARCH variants; using invalid starting values causes optimizer divergence or convergence to incorrect parameters derived_from_bd_id: BD-067 - id: finance-C-211 when: When using ARCH library for volatility calculations in production backtesting action: Assume the framework handles stale data detection and expiry — the ARCH library does not implement data freshness validation; stale data may be processed as current without warning severity: high kind: claim_boundary modality: must_not consequence: Without stale data detection, stale price data is processed as current, causing PnL calculations to be incorrect and potentially resulting in significant financial losses or reporting errors in production systems derived_from_bd_id: BD-GAP-003 - id: finance-C-212 when: When implementing data ingestion in ARCH library production backtesting action: Implement data timestamp validation using validate_timestamp() helper — check data timestamps against current time and reject data older than the configured staleness threshold (e.g., 5 minutes for intraday data) severity: high kind: domain_rule modality: must consequence: Stale data processed as current leads to incorrect PnL calculations and reporting errors in production backtesting systems, potentially causing significant financial losses derived_from_bd_id: BD-GAP-003 - id: finance-C-213 when: When running backtests or production strategies with ARCH library action: Assume the framework automatically maintains model and data version binding — the framework does not implement snapshot binding; different runs may silently use different data versions without tracking severity: high kind: claim_boundary modality: must_not consequence: Without version snapshot binding, backtest results become non-reproducible because different executions may load different data versions without any tracking or warning, making strategy audits impossible derived_from_bd_id: BD-GAP-004 - id: finance-C-214 when: When running backtests or production strategies with ARCH library action: Capture and persist data hashes (e.g., hashlib.sha256 on source data) and model version identifiers for each backtest run, storing them alongside results in a version manifest file severity: high kind: domain_rule modality: must consequence: Without storing version snapshots, backtest results cannot be reproduced or audited; different data versions may silently change strategy performance and invalidate historical comparisons derived_from_bd_id: BD-GAP-004 - id: finance-C-215 when: When implementing custom data provider integration or attempting to write external datasets to ARCH library action: Assume the framework supports versioned writes and snapshot semantics for data persistence — the framework only supports built-in datasets (sp500, cpu, realized volatility) without version control or atomic write guarantees severity: high kind: claim_boundary modality: must_not consequence: Without versioned writes, concurrent data updates can corrupt datasets, and snapshot semantics cannot guarantee data consistency across parallel operations or strategy executions derived_from_bd_id: BD-GAP-011 - id: finance-C-216 when: When implementing custom data provider integration with ARCH library action: Use external database transactions or file versioning systems (e.g., git LFS, versioned S3 buckets) for custom dataset writes — implement atomic write patterns using database transactions or write-to-temp-then-rename operations severity: high kind: domain_rule modality: must consequence: Without version control and atomic writes, data corruption can occur during concurrent updates; strategies may execute on inconsistent snapshots, leading to unpredictable backtest results derived_from_bd_id: BD-GAP-011 - id: finance-C-217 when: When processing DatetimeIndex inputs with timezone-naive indices in arch/utility/array.py:259-276 action: Assume the framework handles timezone conversion automatically — timezone-naive indices are silently stripped to GMT without warning, causing subtle off-by-one errors in quarterly and monthly data severity: high kind: claim_boundary modality: must_not consequence: Timezone-naive date indices are silently stripped to GMT, leading to off-by-one errors that accumulate over time in quarterly and monthly data, corrupting statistical analysis and strategy signals derived_from_bd_id: BD-GAP-012 - id: finance-C-218 when: When processing DatetimeIndex inputs before passing to ARCH library functions action: UTC-normalize each DatetimeIndex inputs using tz_localize(tz='UTC') before processing, and apply validate_timezone() helper to verify each date indices carry explicit UTC timezone information severity: high kind: domain_rule modality: must consequence: Without explicit timezone normalization, timezone-naive indices silently default to GMT, causing subtle off-by-one errors that corrupt quarterly and monthly statistical analysis used for strategy decisions derived_from_bd_id: BD-GAP-012 - id: finance-C-219 when: When implementing or modifying KPSS stationarity test logic in arch/unitroot/unitroot.py action: Use automatic bandwidth selection for KPSS test via auto_bandwidth() function — the auto_bandwidth function minimizes asymptotic mean squared error of the variance estimator; do not replace with fixed bandwidth formulas (T^0.5, T^0.4) unless sample size is small, series is trending, or exhibits heavy-tailed distributions severity: high kind: domain_rule modality: must consequence: Replacing auto-bandwidth with fixed bandwidth may cause KPSS test to reject stationarity incorrectly or accept non-stationary series as stationary, leading to incorrect trading strategy signals and financial losses derived_from_bd_id: BD-028 - id: finance-C-220 when: When processing monetary values or quantitative data in backtesting action: Assume the framework provides explicit currency/unit annotation for data fields — the framework does not implement currency/unit annotation; numeric values lack metadata about their denomination or measurement unit severity: high kind: claim_boundary modality: must_not consequence: Without explicit currency/unit annotation, mixed-currency portfolios or unit-mismatched data cause silent conversion errors that accumulate over time, leading to incorrect portfolio valuations and risk calculations in production derived_from_bd_id: BD-GAP-005 - id: finance-C-221 when: When defining portfolio data structures or processing multi-currency positions action: Add explicit currency/unit metadata to each monetary fields (e.g., currency_code='CNY', unit='share', scale=1) in data schemas and validate unit consistency before calculations severity: high kind: operational_lesson modality: must consequence: Explicit currency/unit annotation prevents silent unit mismatches that cause portfolio value miscalculations when strategies operate across multiple currencies or asset classes derived_from_bd_id: BD-GAP-005 - id: finance-C-222 when: When estimating covariance matrices for portfolio optimization or risk calculation action: Assume the framework automatically fixes non-positive semi-definite (PSD) covariance matrices — the framework does not implement PSD correction; eigenvalue adjustment, Higham's method, or shrinkage is not applied automatically severity: high kind: claim_boundary modality: must_not consequence: Non-PSD covariance matrices cause portfolio optimizers to fail or produce invalid allocations with negative variances, leading to incorrect risk estimates and potentially catastrophic trading decisions derived_from_bd_id: BD-GAP-008 - id: finance-C-223 when: When performing covariance matrix estimation in portfolio construction action: Apply PSD correction using eigenvalue clipping (set negative eigenvalues to 0, rescale trace) or Higham's method before passing covariance matrix to portfolio optimizer severity: high kind: domain_rule modality: must consequence: Without PSD correction, portfolio optimization fails for ill-conditioned covariance matrices, causing strategies to produce unstable or infeasible allocations derived_from_bd_id: BD-GAP-008 - id: finance-C-224 when: When estimating covariance matrices for portfolios with N > T (high-dimensional case) action: Select Ledoit-Wolf shrinkage estimator or OAS (Oracle Approximating Shrinkage) with target=diagonal, and configure shrinkage intensity α in range [0.2, 0.4] based on cross-validation severity: high kind: operational_lesson modality: must consequence: Shrinkage estimators provide finite-sample bias correction that improves portfolio out-of-sample performance by 5-15% in high-dimensional cases compared to raw sample covariance derived_from_bd_id: BD-GAP-009 - id: finance-C-225 when: When configuring VaR/CVaR risk metrics for regulatory or internal risk management action: Set confidence_level=0.99 for regulatory VaR (Basel requirements) or 0.95 for internal models, and configure lookback_window=252 (1 year) for daily VaR or 60 for monthly; validate parameters against risk mandate before backtesting severity: high kind: domain_rule modality: must consequence: Explicit VaR/CVaR parameter configuration ensures regulatory compliance and accurate tail risk estimation aligned with the specific risk management mandate derived_from_bd_id: BD-GAP-010 - id: finance-C-226 when: When implementing volatility forecasting using realized volatility (RV) data action: Use HAR (Heterogeneous Autoregressive) model with predetermined lags of 1, 5, and 22 days representing daily, weekly, and monthly components respectively severity: high kind: domain_rule modality: must consequence: Using alternative volatility models like standard GARCH without understanding HAR's multi-scale advantage produces systematically different volatility forecasts, leading to incorrect risk assessments and suboptimal hedging decisions in live trading derived_from_bd_id: BD-050 - id: finance-C-227 when: When implementing bootstrap confidence intervals or hypothesis tests for time series action: Use Stationary Bootstrap with geometric block length distribution where expected block length equals 1/p (p = success probability) to verify stationarity of bootstrap samples severity: high kind: domain_rule modality: must consequence: Using fixed block length bootstrap methods like Circular Block Bootstrap or Moving Block Bootstrap introduces non-stationarity in bootstrap samples, causing confidence intervals to be systematically miscalibrated and hypothesis tests to have incorrect rejection rates derived_from_bd_id: BD-054 - id: finance-C-228 when: When implementing t-stat based lag selection for statistical tests action: Apply t-stat threshold of |1.645| (10% two-sided significance) for lag elimination — remove lags where absolute t-stat < 1.645 and continue until each remaining lags meet the threshold severity: high kind: domain_rule modality: must consequence: Changing the t-stat threshold alters the lag selection aggressiveness; using a stricter threshold (e.g., 1.96 for 5%) retains fewer lags while using a looser threshold retains more lags, directly affecting model specification and test power derived_from_bd_id: BD-055 - id: finance-C-229 when: When implementing or configuring APARCH volatility models in ARCH library action: Maintain delta=1 when using APARCH for TARCH specification; the power parameter controls volatility asymmetry where negative shocks produce larger volatility increases (absolute return specification) severity: high kind: domain_rule modality: must consequence: Without delta=1, APARCH no longer nests TARCH specification, eliminating the asymmetric volatility mechanism that captures negative shock amplification, causing systematically biased volatility forecasts derived_from_bd_id: BD-056 - id: finance-C-231 when: When configuring ARCHModel instances for volatility estimation action: Explicitly specify volatility model (ConstantVariance, EGARCH, GARCH, etc.) and distribution (Normal, StudentT, etc.) in constructor parameters rather than relying on hardcoded defaults; verify default path matches intended estimation severity: medium kind: operational_lesson modality: should consequence: Using hardcoded defaults without verification may result in ConstantVariance+Normal being silently used, causing incorrect volatility and distribution specifications that corrupt estimation results and invalidate downstream risk metrics derived_from_bd_id: BD-061 - id: finance-C-232 when: When refactoring bootstrap implementations in arch library action: Preserve the inheritance relationship between CircularBlockBootstrap and IIDBootstrap; verify block_length parameter override is maintained as the inheritance enables clone behavior and shared sampling interface severity: high kind: domain_rule modality: must consequence: Breaking the inheritance relationship between CircularBlockBootstrap and IIDBootstrap breaks the circular block bootstrap implementation, causing sampling failures and invalid statistical inference in bootstrap-based confidence intervals derived_from_bd_id: BD-065 output_validator: assertions: - id: OV-01 check_predicate: all(p in inspect.getsource(zvt.factors.algorithm.macd) for p in ['slow=26', 'fast=12', 'n=9']) failure_message: 'FATAL: MACD params drifted from (fast=12, slow=26, n=9) — SL-08 violation, non-reproducible signals' business_meaning: Standard MACD parameters are a semantic lock; drift makes results incomparable with industry-standard indicators and non-reproducible. source_ids: - SL-08 - BD-036 - id: OV-02 check_predicate: result.get('total_trades', 0) > 0 or result.get('explicit_zero_trade_ack') is True failure_message: Zero trades executed — likely missing pre-fetched data (see PC-02) or over-restrictive filters business_meaning: A backtest with zero trades is not a valid result; either data is missing or the strategy never triggered. Structural non-emptiness check is insufficient — we need business confirmation. source_ids: - SL-01 - finance-C-073 - id: OV-03 check_predicate: result.get('annual_return') is None or abs(float(result['annual_return'])) <= 5.0 failure_message: 'FATAL: |annual_return| > 500% — likely look-ahead bias or data error' business_meaning: Annual returns exceeding 500% are physically implausible for A-share strategies; indicates look-ahead bias or corrupt data. source_ids: [] - id: OV-04 check_predicate: result.get('holding_change_pct') is None or abs(float(result['holding_change_pct'])) <= 1.0 failure_message: 'FATAL: |holding_change_pct| > 100% — physically impossible' business_meaning: Holding change percentage cannot exceed 100%; violation indicates position accounting error. source_ids: - BD-029 - id: OV-05 check_predicate: result.get('max_drawdown') is None or abs(float(result['max_drawdown'])) <= 1.0 failure_message: 'FATAL: |max_drawdown| > 100% — impossible for non-leveraged account' business_meaning: Maximum drawdown cannot exceed 100% without leverage; violation indicates calculation error or look-ahead bias. source_ids: [] - id: OV-06 check_predicate: not (hasattr(result, 'trade_log') and result.trade_log and any(result.trade_log[i].action == 'sell' and i+1 < len(result.trade_log) and result.trade_log[i+1].action == 'buy' and result.trade_log[i].timestamp == result.trade_log[i+1].timestamp for i in range(len(result.trade_log)-1))) failure_message: 'FATAL: buy-before-sell detected in same cycle — SL-01 violation, creates implicit leverage' business_meaning: SL-01 requires sell() before buy() in each cycle; violation means available_long was not updated before buying, risking duplicate positions. source_ids: - SL-01 scaffold: validate_py_path: '{workspace}/validate.py' tail_block: "# === DO NOT MODIFY BELOW THIS LINE ===\nif __name__ == \"__main__\":\n result = run_backtest()\n from\ \ validate import enforce_validation\n enforce_validation(result, output_path=\"{workspace}/result.csv\")\n# ===\ \ END DO NOT MODIFY ===" enforcement_protocol: 1. Never edit validate.py. 2. Never delete the DO NOT MODIFY tail block from the main script. 3. Never wrap enforce_validation() in try/except. 4. Never rewrite result write logic — it MUST go through enforce_validation. 5. If validate.py raises ImportError, fix the dependency, do not remove the call. acceptance: hard_gates: - id: G1 check: '{workspace}/result.csv exists AND file size > 0' on_fail: Strategy did not produce output; check run_backtest() return value and enforce_validation() call - id: G2 check: '{workspace}/result.csv.validation_passed marker file exists' on_fail: Validation did not complete; review validate.py output and fix assertion failures - id: G3 check: 'Main script contains literal: from validate import enforce_validation' on_fail: Validation chain stripped; re-add the import in the DO NOT MODIFY block - id: G4 check: 'Main script contains literal: # === DO NOT MODIFY BELOW THIS LINE ===' on_fail: Validation fence removed; regenerate DO NOT MODIFY tail block - id: G5 check: 'result.csv has at least 1 row: pandas.read_csv(result.csv).shape[0] >= 1' on_fail: Empty result; check if trade_log is non-empty and factors generated signals. Confirm PC-02 (k-data exists) passed. - id: G6 check: 'If MACD strategy: source contains ''slow=26'' AND ''fast=12'' AND ''n=9'' in algorithm call' on_fail: MACD params drifted from SL-08 lock; restore standard (12, 26, 9) - id: G7 check: 'For data pipeline tasks: result.csv contains ''entity_id'' and ''timestamp'' fields' on_fail: Missing required columns; check Mixin.query_data return schema and DataFrame MultiIndex reset_index() before writing - id: G8 check: 'OV-03 passes: abs(annual_return) <= 5.0 (500%)' on_fail: Physical plausibility check failed; investigate look-ahead bias or data corruption in input kdata soft_gates: - id: SG-01 rubric: 'Strategy narrative consistency: user intent aligns with generated strategy.py logic. dim_a: signal direction (buy/sell) matches intent [1-5, pass>=4]; dim_b: frequency (daily/intraday) aligns [1-5, pass>=4]; dim_c: risk controls match user intent [1-5, pass>=4].' - id: SG-02 rubric: 'Factor combination quality. dim_a: no highly correlated factor duplication [1-5, pass>=4]; dim_b: multi-period alignment correct [1-5, pass>=4]; dim_c: liquidity filter present for A-share [1-5, pass>=4].' - id: SG-03 rubric: 'Data source selection appropriateness. dim_a: coverage sufficient for target entities [1-5, pass>=4]; dim_b: provider latency acceptable for strategy frequency [1-5, pass>=4]; dim_c: no unauthorized provider used without credentials [1-5, pass>=4].' skill_crystallization: trigger: all_hard_gates_passed AND user_opt_out_skill_saving != true output_path_template: '{workspace}/../skills/{slug}.skill' slug_template: '{blueprint_id_short}-{uc_id_lower}' captured_fields: - name - intent_keywords - entry_point_script - validate_script - fatal_constraints - spec_locks - preconditions - install_recipes - human_summary_translated action: 'After all Hard Gates PASS, resolve slug via slug_template using the executed UC, then write the .skill YAML file at output_path_template. Notify user in their detected locale: ''Skill saved as {slug}.skill — next time say one of {sample_triggers} from the matched UC to invoke directly.''' violation_signal: All hard gates passed but no .skill file exists at expected path skill_file_schema: name: finance-bp-124 / Sharpe Ratio Bootstrap Statistical Inference version: v5.3 intent_keywords: - bootstrap - sharpe ratio - statistical inference - confidence intervals - stationary bootstrap entry_point: run_backtest fatal_guards: - SL-01 - SL-02 - SL-03 - SL-04 - SL-05 - SL-06 - SL-07 - SL-08 - SL-10 - SL-11 - SL-12 spec_locks: - SL-01 - SL-02 - SL-03 - SL-04 - SL-05 - SL-06 - SL-07 - SL-08 - SL-09 - SL-10 - SL-11 - SL-12 preconditions: - PC-01 - PC-02 - PC-03 - PC-04 post_install_notice: trigger: skill_installation_complete message_template: positioning: I help you build quant strategies on A-share with ZVT — from data fetch to backtest, one flow. capability_catalog: group_strategy: source: auto_grouped strategy_reason: no candidate field had 2-7 distinct values; all capabilities collapsed into single group groups: - group_id: all name: All Capabilities description: '' emoji: 📦 uc_count: 9 ucs: - uc_id: UC-101 name: Sharpe Ratio Bootstrap Statistical Inference short_description: Computes statistical inference (confidence intervals, standard errors) for the Sharpe Ratio using bootstrap methods to quantify uncertainty in risk-ad sample_triggers: - bootstrap - sharpe ratio - statistical inference - uc_id: UC-102 name: Multiple Model Comparison with SPA Test short_description: Compares 500 predictive models against a benchmark using the Superior Predictive Ability (SPA) test to determine if any models significantly outperfor sample_triggers: - model comparison - SPA test - multiple models - uc_id: UC-103 name: Oil Price Cointegration Analysis short_description: Tests for cointegration relationships between WTI and Brent crude oil prices to identify mean-reverting spread opportunities using Engle-Granger and P sample_triggers: - cointegration - unit root - ADF test - uc_id: UC-104 name: Credit Spread Stationarity Testing short_description: Tests for stationarity in credit spreads (BAA-AAA) using Augmented Dickey-Fuller tests to determine if mean-reversion trading strategies are applicabl sample_triggers: - unit root - ADF test - stationarity - uc_id: UC-105 name: ARX Forecasting with Exogenous Variables short_description: Forecasts univariate time series using Autoregressive models with exogenous variables (ARX) to capture the impact of external factors on the target va sample_triggers: - ARX - exogenous variables - forecasting - uc_id: UC-106 name: HARX Volatility Modeling with Fixed Variance short_description: Demonstrates how to specify a HARX mean model with fixed/external variance inputs and iteratively fit volatility models using the estimated conditiona sample_triggers: - fixed variance - HARX - volatility modeling - uc_id: UC-107 name: S&P 500 GARCH Volatility Forecasting short_description: Forecasts future volatility of S&P 500 returns using GARCH models, including multi-step ahead forecasts and rolling window out-of-sample predictions sample_triggers: - GARCH - volatility forecasting - S&P 500 - uc_id: UC-108 name: S&P 500 GARCH Volatility Model Comparison short_description: 'Fits and compares different GARCH volatility model specifications (symmetric, asymmetric, power) with various error distributions to characterize S&P ' sample_triggers: - GARCH - volatility modeling - S&P 500 - uc_id: UC-109 name: NASDAQ Volatility Scenario Generation short_description: Generates multiple volatility scenarios for NASDAQ returns using simulation-based forecasting methods, useful for risk management and option pricing a sample_triggers: - volatility scenarios - simulation - NASDAQ call_to_action: Tell me which one you want to try. featured_entries: - uc_id: UC-101 beginner_prompt: Try sharpe ratio bootstrap statistical inference auto_selected: true - uc_id: UC-102 beginner_prompt: Try multiple model comparison with spa test auto_selected: true - uc_id: UC-103 beginner_prompt: Try oil price cointegration analysis auto_selected: true more_info_hint: Ask me 'what else can you do?' to see all 9 capabilities. locale_rendering: instruction: On skill_installation_complete, translate ALL user-facing strings (positioning + capability_catalog.groups[].name + capability_catalog.groups[].description + capability_catalog.groups[].ucs[].short_description + call_to_action + featured_entries[].beginner_prompt + more_info_hint) into detected user locale per locale_contract. Preserve UC-IDs, group_id, emoji, and sample_triggers verbatim. preserve_verbatim: - UC-IDs - group_id - emoji - sample_triggers - technical_class_names enforcement: action: 'Host agent MUST send composed message to user as the FIRST user-facing response after skill_installation_complete event. Message MUST contain: positioning, capability_catalog (rendered as markdown tables per group), 3 featured_entries, call_to_action, and more_info_hint.' violation_code: PIN-01 violation_signal: First user-facing message post-install does not contain the full capability_catalog (all UCs grouped) OR skips featured_entries OR skips call_to_action. human_summary: persona: Doraemon what_i_can_do: tagline: 'I help you build quant strategies on A-share with ZVT — from data fetch to backtest, one flow. Just tell me what you want; I''ll write the code, you don''t have to dig docs. (Heads up: ZVT natively supports A-share, HK, and crypto. US stocks — stockus_nasdaq_AAPL — are half-baked; don''t bother for serious work.)' use_cases: - Oil Price Cointegration Analysis - Multiple Model Comparison with SPA Test - Sharpe Ratio Bootstrap Statistical Inference - A-share MACD daily golden-cross backtest with hfq price adjustment from eastmoney - 'End-to-end ZVT pipeline: FinanceRecorder + GoodCompanyFactor + StockTrader' - Multi-factor strategy with TargetSelector (AND mode) combining MACD + volume breakout - Index composition data collection (SZ1000, SZ2000) with EM recorder what_i_auto_fetch: - ZVT stage pipeline structure (data_collection → visualization) from LATEST.yaml - Semantic locks (SL-01 through SL-12) — especially sell-before-buy ordering and MACD params - Fatal constraints (finance-C-*) relevant to your target strategy type - 'Default parameters: MACD(12,26,9), hfq adjustment, buy_cost=0.001, base_capital=1M CNY' - Entity ID format (stock_sh_600000) and DataFrame MultiIndex convention - Provider-specific recorder class names and required class attributes what_i_ask_you: - 'Target market: A-share (default), HK, or crypto? (US stocks in ZVT are half-baked — stockus_nasdaq_AAPL exists but coverage is thin)' - 'Data source / provider: eastmoney (free, no account), joinquant (account+paid), baostock (free, good history), akshare, or qmt (broker)?' - 'Strategy type: MACD golden-cross, MA crossover, volume breakout, fundamental screen, or custom factor?' - 'Time range: start_timestamp and end_timestamp for backtest period' - 'Target entity IDs: specific stocks (stock_sh_600000) or index components (SZ1000)?' locale_rendering: instruction: On first user contact, translate all fields above into detected user locale while preserving Doraemon persona (direct, frank, mildly snarky, knows limits). preserve_verbatim: - BD-IDs - SL-IDs - UC-IDs - finance-C-IDs - class_names - function_names - file_paths - numeric_thresholds