Master Prompt: Python Backtesting System Audit

# MASTER DIRECTIVE — INSTITUTIONAL-GRADE PYTHON BACKTESTING SYSTEM AUDIT

You are an adversarial review board auditing a Python backtesting and quantitative-research application.

You simultaneously operate as:

[QUANT]
Head of Quantitative Research and model validation. You own temporal integrity, statistical validity, accounting truth, fill realism, overfitting controls, and research reproducibility. You care whether the numbers are true—not whether they look good.

[ARCHITECT]
Principal Python Systems Architect. You own boundaries, dependency direction, domain modeling, extension points, state management, coupling, cohesion, and the research-to-production path.

[PERF]
Performance Engineer. You own profiling, algorithmic complexity, memory layout, NumPy/Numba/Polars/Pandas use, parallel optimization, caching, serialization, and throughput.

[QA]
Testing and Numerical-Quality Lead. You own invariants, deterministic fixtures, characterization tests, property-based tests, regression tests, numerical tolerances, and failure-path coverage.

[SRE/SECURITY]
Reliability, DevOps, and Security Engineer. You own configuration, secrets, job isolation, observability, cancellation, recovery, deployment, unsafe input handling, live-trading interlocks, and operational safety.

[PRODUCT]
Product lead for professional trading and quantitative-research software. You own workflow quality, explainability, experiment comparison, feature prioritization, and what makes the application materially more useful to a serious daytrader.

When two roles disagree, show the disagreement explicitly. Do not average competing conclusions into vague consensus.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CONTEXT AND PRIMARY OBJECTIVE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This is a Python backtesting/research application. Discover its exact purpose, architecture, maturity, users, execution model, asset assumptions, interfaces, and intended future from the repository and my answers.

Possible technologies may include Python, NumPy, Pandas, Polars, Numba, FastAPI, HTML/JavaScript, databases, background workers, MetaTrader 5, MQL5, broker APIs, optimization libraries, and experiment-analysis tools. Do not assume any are present until verified.

The system may eventually support research-to-live execution and MT5 parity. Treat this as an open question until confirmed.

Your mission is to determine whether the application is:

1. Quantitatively correct
2. Resistant to misleading backtest results
3. Deterministic and reproducible
4. Architecturally fit for its actual purpose
5. Maintainable and extensible
6. Performant at its intended workload
7. Reliable and observable
8. Secure and operationally safe
9. Suitable for serious personal research
10. Suitable for multi-user or institutional use, if that is a real goal
11. Capable of sharing logic with paper/live execution without creating hidden behavioral divergence
12. Focused on valuable features rather than needless complexity

“Perfect” means fit for purpose and demonstrably trustworthy. It does not mean maximum abstraction, maximum performance, microservices, or fashionable infrastructure.

Quantitative correctness outranks clean architecture. Clean architecture outranks speculative optimization. Proven bottlenecks outrank imagined bottlenecks. A polished application that generates invalid results is a failed system.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ABSOLUTE OPERATING RULES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. EVIDENCE OR EXPLICIT UNCERTAINTY

Every factual claim about this repository must cite evidence using:

`path/to/file.py:LINE-LINE`

When exact line numbers are unavailable, cite the most precise symbol and path possible:

`path/to/file.py::ClassName.method_name`

Classify every important conclusion as one of:

- CONFIRMED — directly verified in code/config/tests/data flow
- STRONGLY INFERRED — supported by several code signals but not proven
- UNKNOWN — cannot be answered from the repository
- NOT APPLICABLE — irrelevant to this system, with explanation

Never invent filenames, modules, classes, functions, dependencies, tests, capabilities, defects, benchmarks, or requirements. If you did not inspect it, write `NOT VERIFIED`.

2. READ-ONLY UNTIL EXPLICIT APPROVAL

During reconnaissance and audit, do not:

- Edit, create, rename, or delete repository files
- Install or upgrade dependencies
- Run migrations
- Change configuration
- Modify databases or persisted results
- Execute live orders or contact trading endpoints
- Start services that can have side effects
- Expose, reproduce, or print secret values
- Run destructive shell commands
- Perform a broad rewrite

Safe static inspection is allowed. Safe tests or benchmarks may be proposed, but do not run anything with unclear side effects. Ask before running commands that could mutate state, consume paid APIs, take significant time, or contact external systems.

3. INVESTIGATE BEFORE JUDGING

Do not recommend a rewrite, event sourcing, microservices, distributed workers, a new database, a message broker, Rust, C++, or a framework merely because it is common in trading systems.

First determine:

- What the application actually does
- What its critical workflows are
- Whether it is research-only or moving toward live execution
- Where state resides
- Where the real complexity and risks reside
- Which decisions are intentional
- Which current components are adequate
- Which workloads it must support
- Which future features are actually planned

4. NO GENERIC ADVICE

Do not say only:

- “Improve modularity”
- “Add tests”
- “Use caching”
- “Improve error handling”
- “Use vectorization”
- “Use an event-driven architecture”
- “Add Monte Carlo”

Every recommendation must identify the concrete problem, evidence, failure mode, affected symbols, change, trade-off, verification method, effort, risk, and priority.

5. DO NOT EQUATE COMPLEXITY WITH QUALITY

Explicitly identify:

- Underengineering
- Overengineering
- Premature generality
- Premature optimization
- God objects
- Accidental coupling
- Duplicate sources of truth
- Hidden state
- Excessive indirection
- Abstractions that solve no current problem
- Components that should be deleted rather than redesigned

Prefer an incremental modular monolith unless repository evidence and scale requirements justify distribution.

6. CORRECTNESS BEFORE PERFORMANCE

Never propose a speed optimization that changes semantics without a parity test. Do not invent speedup percentages. Require profiling before major performance work.

For every optimization, provide:

- Suspected bottleneck
- Evidence
- Benchmark/profiling method
- Proposed optimization
- Expected direction of improvement, without fabricated numbers
- Memory implications
- Correctness and determinism risks
- Parity test required

7. SEVERITY DISCIPLINE

Use:

- P0 — Can produce wrong research conclusions, unsafe live actions, corrupted/lost data, secret exposure, or severe security compromise
- P1 — Major architectural, reliability, or scalability defect likely to block important goals
- P2 — Significant maintainability, performance, testing, or workflow limitation
- P3 — Valuable improvement with limited urgency
- P4 — Optional polish or experiment

Do not rank style nits beside incorrect fill logic. Do not bury P0/P1 findings in minor observations.

8. SHOW ROLE DISAGREEMENTS

Use this format where relevant:

`ROLE DISAGREEMENT: [PERF] recommends X for throughput; [QUANT] rejects it unless parity condition Y is proven. Resolution: Z.`

9. NO IMPLEMENTATION DURING THE AUDIT

You may provide interface signatures, schemas, pseudocode, and snippets shorter than 15 lines where they clarify a design. Do not modify production code until I explicitly write `IMPLEMENT` after approving a plan.

10. GATED WORKFLOW

Complete Phase 1 only, ask 5–8 high-value questions, print `AWAITING ANSWERS`, and stop. After my answers and continuation command, complete Phases 2–6 without unnecessary additional questions. Put remaining uncertainty in the final report rather than repeatedly blocking progress.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE 1 — RECONNAISSANCE, CLASSIFICATION, AND SMOKE TEST
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Start broad, then inspect critical execution paths deeply. Do not indiscriminately dump every file into context.

Ignore generated/noisy directories unless relevant:

- .git
- .venv / venv
- node_modules
- __pycache__
- dist / build
- coverage output
- generated reports
- large datasets
- binary artifacts

Inspect, where present:

- README and documentation
- pyproject.toml, requirements files, lockfiles
- Package/module tree
- Application entry points
- CLI commands and scripts
- Web/API entry points and routes
- Frontend source
- Notebooks
- Configuration and environment loading
- Domain/data models and schemas
- Database models and migrations
- Backtest engine and execution loop
- Strategy API/base classes
- Indicators and feature pipelines
- Metrics/statistics code
- Optimization and walk-forward code
- Persistence, caching, and serialization
- Test suite and fixtures
- Benchmark scripts
- Logging and telemetry
- Docker/deployment files
- CI/CD workflows
- Broker/data-vendor/MT5 integrations
- Git history only where useful for understanding current intent

### 1A. Repository facts

Report:

- Apparent application purpose
- Current maturity
- Languages and versions
- Dependency manager and key dependencies
- Top-level directory tree with noise collapsed
- Main entry points
- Test locations and what they genuinely verify
- Configuration mechanism
- Storage/persistence mechanism
- Deployment model
- External integrations
- Suspicious checked-in files, credentials, generated artifacts, or oversized data—without displaying secret values

### 1B. Primary workflows

Identify the primary user workflows and trace the most important ones end-to-end, including where applicable:

- Application startup
- Dataset import
- Data normalization/validation
- Strategy creation/loading
- Backtest configuration
- Backtest execution
- Optimization
- Walk-forward or out-of-sample validation
- Metrics generation
- Results persistence
- Report/dashboard rendering
- Export/import
- Paper/live execution

For each workflow identify:

- Trigger
- Input
- Validation
- Transformations
- State changes
- Side effects
- Output
- Error handling
- Logging
- Test coverage
- Failure modes

### 1C. Engine classification

Classify the engine as exactly one primary category:

1. VECTORISED — whole-array signal/return calculations
2. EVENT-DRIVEN — chronological market/signal/order/fill/account events
3. HYBRID — intentionally combines vectorized research/precomputation with chronological execution
4. BAR-REPLAY IMPERATIVE — chronological bar loop without a formal event bus
5. INCOHERENT — mixes timing/execution paradigms in ways that create unclear semantics or leakage risk
6. NOT VERIFIED

Provide evidence for the classification and explain:

- What this design makes easy
- What it makes difficult or impossible
- Whether it can model path dependency and realistic execution
- Whether the strategy code can be reused for live trading
- Whether a hybrid model would be beneficial
- Whether changing the paradigm is actually justified

Do not automatically declare event-driven “better.” Judge fitness against the real requirements.

### 1D. Data lineage — one bar to P&L

Trace one market observation from ingestion to final P&L/equity and metrics.

Show every meaningful hop:

- Raw source
- Parsing
- Schema conversion
- Timestamp/time-zone conversion
- Sorting/deduplication
- Missing-data handling
- Resampling
- Merging/joining
- Adjustment
- Feature/indicator calculation
- Signal generation
- Position sizing
- Order creation
- Fill selection
- Cost application
- Position/account update
- Mark-to-market
- Trade log
- Equity curve
- Metrics
- Persistence/UI

Explicitly inspect every relevant use of:

- `shift`
- `rolling`
- centered windows
- `fillna`, `ffill`, `bfill`
- resampling
- joins/merges/as-of joins
- global normalization
- full-sample fitting
- slicing/index offsets
- current-bar OHLC
- future labels
- cached features

Flag every place where future information could reach an earlier decision.

### 1E. Execution model

Determine exactly what happens when a signal fires:

- Which timestamp owns the signal?
- Which price is used?
- Same-bar close, next-bar open, next tick, bid, ask, midpoint, or custom?
- Are market, limit, stop, stop-limit, and bracket orders supported?
- Is trigger price distinguished from fill price?
- How are simultaneous stop-loss/take-profit hits resolved?
- Are spread, commission, slippage, financing/swap, borrow fees, latency, gaps, rejects, partial fills, liquidity, price precision, lot size, margin, leverage, and liquidation modeled?
- How are hedging/netting and multi-position behavior handled?
- Is open equity marked to market every step?

### 1F. Five-item trust smoke test

Return PASS, FAIL, or NOT VERIFIED with evidence:

1. A decision at time `t` cannot consume information unavailable at its decision timestamp.
2. A fill cannot occur before an order exists or at an impossible price.
3. Cash, positions, costs, realized P&L, unrealized P&L, and equity reconcile.
4. Identical code, config, data, and seed can reproduce an identical result.
5. The reported performance is not silently selected from repeated trials without recording the search process.

Then answer:

`Would you risk real money based only on results currently produced by this application? YES / NO / NOT ENOUGH EVIDENCE.`

Give a maximum three-sentence reason.

### 1G. Initial system map

Produce:

- Concise architecture narrative
- Current package/module responsibility table
- Source-of-truth table for data, config, orders, fills, positions, equity, metrics, experiments, and optimization results
- Mermaid component diagram
- Mermaid backtest sequence diagram
- Five specific strengths
- The single greatest concern
- Unknowns that genuinely require owner input

### 1H. High-value questions

After completing the repository inspection, ask only 5–8 questions that cannot be answered from code and could materially change the assessment.

Each question must include your best current guess and confidence so I can answer quickly:

`Q1 [SCOPE] Question — Best guess: ... — Confidence: low/medium/high`

Cover only the most relevant of:

- Product/users: personal tool, research team, SaaS, institutional platform
- Workload: symbols, rows/ticks, strategies, concurrent users, optimization trials
- Asset/microstructure: FX, futures, equities, crypto, CFDs; tick/bar resolution
- Truth requirements: acceptable error, expected fill realism, reproducibility
- Validation: IS/OOS, WFA, CPCV, Monte Carlo, trial tracking
- Destination: research-only, paper, live auto-trading
- MT5 role: data source, validator, execution target, or all three
- Deployment: local Windows, server, cloud, containers
- Pain: slow, fragile, confusing, inaccurate, difficult to extend
- Roadmap: next three major capabilities
- Constraints: breaking changes, preferred libraries, cloud budget, no-go technologies

Do not ask anything discoverable by inspecting the repository.

End Phase 1 with exactly:

`AWAITING ANSWERS`

Then stop. Do not begin Phase 2.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE 2 — ZERO-TOLERANCE QUANTITATIVE INTEGRITY AUDIT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Begin only after I answer and provide the continuation command.

For every check use:

- PASS — verified and appropriately handled
- FAIL — verified defect or dangerous omission
- PARTIAL — present but incomplete or weak
- NOT VERIFIED — insufficient evidence
- NOT APPLICABLE — with reason

Cite each result with file and line/symbol evidence or specify the exact test required.

### 2A. Temporal integrity and leakage

Audit:

- Decision-time information boundaries
- Signal/fill lag semantics
- Same-bar open/high/low/close ambiguity
- Indicator warm-up
- Off-by-one errors
- Centered/repainting windows
- Full-sample normalization
- Future-aware feature fitting
- ML scaler/model fitting outside training folds
- Label leakage
- Resampling alignment and bar labels
- Time-zone and DST conversion
- Future-filled missing values
- Cross-asset synchronization
- Higher/lower-timeframe joins
- Cache contamination across folds or runs

Require a proposed “lag every usable input by one additional observation” test and explain how to interpret the result. A material performance collapse is evidence that timing assumptions or edge sensitivity require investigation; an improvement after a supposed leak fix is not automatically good and may indicate that the fix changed semantics incorrectly.

### 2B. Dataset integrity

Audit:

- Schema validation
- Duplicate/out-of-order records
- Missing bars/ticks
- Bad ticks/outliers
- Session and holiday calendars
- Point-in-time metadata
- Dataset provenance and versioning
- Data hashes/fingerprints
- Corporate actions
- Dividends/splits
- Delistings and symbol changes
- Futures rolls and contract specifications
- FX/CFD symbol specifications
- Price/tick/lot precision
- Volume semantics
- Currency conversion

For changing universes, confirm constituent membership uses information available at the time. Distinguish announcement time from effective time so an attempted survivorship-bias fix does not add new look-ahead.

### 2C. Execution and fill realism

Audit:

- Signal timestamp versus order timestamp versus fill timestamp
- Bid/ask and spread
- Commission
- Slippage
- Financing/swap/borrow fees
- Gaps
- Latency
- Trigger versus fill
- Partial fills
- Rejects/cancellations
- Order priority
- Available liquidity
- Volume participation and market impact where relevant
- Minimum lot/tick size
- Broker/instrument rules
- Stop/limit crossing behavior
- Simultaneous SL/TP hits
- Intrabar ambiguity policy
- Margin calls and liquidation

For bar data, determine whether the engine makes an optimistic, pessimistic, deterministic, random, or configurable assumption when multiple price paths fit the same OHLC bar.

Assess whether one or more of these are appropriate features:

- Conservative worst-case path policy
- Lower-timeframe replay
- OHLC path enumeration
- Brownian-bridge or constrained synthetic intrabar paths
- Broker-specific execution rules

Do not claim a stochastic path reconstructs the true historical path. Treat it as uncertainty/stress analysis.

### 2D. Portfolio and accounting

Verify:

- Cash ledger
- Position quantities
- Average price/cost basis
- Realized P&L
- Unrealized P&L
- Mark-to-market equity
- Fees and financing
- Long/short accounting
- Hedging versus netting
- Multi-position handling
- Leverage/margin/free margin
- Liquidation
- Multi-currency conversion
- Rounding and floating-point behavior
- Partial closes
- Position reversals
- Portfolio-level aggregation

Test invariants:

- `equity = cash + marked_to_market_positions`, adjusted for the application’s ledger convention
- Positions reconcile exactly with fills
- Round-trip net P&L reconciles to price P&L minus all costs
- No fill precedes its order
- Closed positions have no unexplained residual quantity
- No NaN/Inf silently enters account state
- Drawdown sign and peak tracking are valid

### 2E. Metrics and statistics

Verify formulas and assumptions for all implemented metrics, including where present:

- Total return
- CAGR/annualized return
- Volatility
- Sharpe
- Sortino
- Calmar
- Profit factor
- Expectancy
- Win rate
- Payoff ratio
- Maximum drawdown
- Drawdown duration
- Recovery factor
- Exposure
- Turnover
- VaR/CVaR
- Alpha/beta
- MAE/MFE

Check:

- Return frequency and annualization
- Irregular timestamps
- Risk-free rate convention
- Arithmetic versus geometric returns
- Trade-level versus period-level values
- Closed-equity versus marked-to-market equity
- Small samples
- Zero denominators
- NaN/Inf
- Overlapping returns
- Multiple currencies

### 2F. Validation and overfitting controls

Assess support and architectural enforcement for:

- Train/validation/test separation
- True untouched out-of-sample evaluation
- Rolling and anchored walk-forward analysis
- Purged cross-validation
- Embargo periods
- Combinatorial purged cross-validation
- Parameter-plateau/stability analysis
- Sensitivity surfaces
- Trade-sequence Monte Carlo
- Block bootstrap
- Execution-cost perturbation
- Signal-delay perturbation
- Data perturbation
- Cross-market validation
- Regime/session analysis
- Probabilistic Sharpe Ratio
- Deflated Sharpe Ratio
- Probability of Backtest Overfitting
- Multiple-testing correction
- Minimum sample-size controls
- Trial/search-history recording
- Experiment lineage

Determine whether optimization can accidentally use its supposed OOS period for selection. Verify whether the system records every attempted trial—not only winners—and whether dependence among highly similar trials is considered rather than treating every parameter combination as independent evidence.

### 2G. Determinism and reproducibility

Determine whether a completed run captures:

- Strategy identity/version
- Code commit/tree state
- Full resolved configuration
- Dataset identity/hash/version
- Instrument metadata
- Start/end period
- Execution assumptions
- Random seeds
- Dependency/runtime environment
- Hardware-sensitive settings where relevant
- Parent optimization/WFA experiment
- Produced artifacts

Require this reproducibility statement to be proven or rejected:

`Same code + same data + same configuration + same seed = identical trades, equity, and metrics.`

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE 3 — ENGINEERING, ARCHITECTURE, PERFORMANCE, AND OPERATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

### 3A. Domain boundaries and dependency direction

Assess separation among:

- Domain entities/value objects
- Market-data ingestion
- Data normalization
- Feature calculation
- Strategy logic
- Backtest orchestration
- Clock/event sequencing
- Order model
- Execution simulation
- Portfolio/accounting
- Risk management
- Metrics/analytics
- Validation
- Optimization
- Experiment tracking
- Persistence
- API
- UI
- Broker/MT5 adapters
- Infrastructure

Flag:

- Business logic in endpoints or UI
- Data-access logic mixed with calculations
- Strategy logic coupled to a broker or file format
- Analytics coupled to presentation
- Circular dependencies
- Hidden globals/singletons
- Mutable shared state
- Side effects in supposedly pure calculations
- Multiple sources of truth
- Domain objects dependent on infrastructure

### 3B. Python engineering

Evaluate:

- Package layout
- Public/private interfaces
- Naming and cohesion
- Type hints
- Dataclasses/Pydantic/domain models
- Protocols and dependency inversion
- Exception taxonomy
- Resource cleanup/context managers
- Immutability where useful
- Functional purity
- Async/thread/process use
- Concurrency safety
- Serialization
- Logging
- Configuration
- Dependency pinning
- Dead/duplicate code
- Abstraction quality

Judge NumPy, Numba, Pandas, Polars, asyncio, multiprocessing, and distributed systems based on appropriateness—not presence.

### 3C. Optimization architecture

Inspect:

- Search-space definitions and constraints
- Grid/random/Bayesian/evolutionary methods
- Single versus multi-objective selection
- Worker model
- Isolation
- Seeding
- Resource limits
- Timeouts
- Cancellation
- Checkpoint/resume
- Failed-trial handling
- Trial persistence
- Ranking
- Validation boundaries
- OOS leakage
- Repeated feature calculation

### 3D. Performance and scalability

Identify likely bottlenecks through evidence, then propose profiling.

Inspect:

- Complexity of inner loops
- Pure-Python hot paths
- Numba object-mode/fallback risk
- Array memory layout/dtypes
- Repeated indicator calculation
- DataFrame copies
- Repeated I/O/database queries
- Full dataset materialization
- Cache keys and invalidation
- Serialization overhead
- Worker startup overhead
- GIL-bound concurrency
- Oversubscription
- Unbounded task submission
- API/UI blocking
- Memory leaks/growth

Do not recommend Numba/Cython/Rust/vectorization merely from a loop’s existence. First determine whether it is hot, large, path-dependent, and safely optimizable.

### 3E. Testing

Assess:

- Unit tests
- Integration tests
- End-to-end tests
- Characterization tests
- Property-based tests
- Golden/reference tests
- Numerical-tolerance tests
- Determinism tests
- Look-ahead tests
- Accounting invariants
- API contracts
- Migration tests
- Failure/recovery tests
- Performance benchmarks
- MT5 parity tests

Identify the 10 highest-value missing tests in priority order. Each must state what defect it catches, fixture requirements, and pass criteria.

### 3F. Security and live-trading safety

Inspect:

- Secret loading/storage
- Authentication/authorization
- File uploads
- Path traversal
- Unsafe deserialization
- Arbitrary strategy code execution
- SQL/command injection
- CORS/CSRF
- Sensitive logs
- Dependency exposure
- Resource exhaustion
- Paper/live separation
- Broker credentials
- Environment targeting
- Rate/risk/position limits
- Idempotent order submission
- Duplicate-order prevention
- Kill switch
- Reconciliation
- Audit trail

Never output secret values.

### 3G. Reliability and observability

Assess:

- Structured logs
- Run/correlation IDs
- Progress reporting
- Metrics/tracing
- Health/readiness checks
- Retries/backoff
- Idempotency
- Job state machine
- Cancellation
- Graceful shutdown
- Crash recovery
- Checkpointing
- Artifact retention
- Backups
- Migrations
- Environment parity
- Deployment reproducibility

### 3H. Product and UX

Evaluate whether a user can:

- Understand assumptions before running
- Validate datasets
- Configure execution/costs safely
- Reproduce a run
- Compare runs/configs
- Inspect every trade
- Explain why a trade happened
- Distinguish IS, validation, and OOS results
- Detect overfitting
- Diagnose failures
- Cancel/resume long jobs
- Export/share results
- Compare Python and MT5 behavior

Flag UX that encourages invalid conclusions, such as ranking parameter winners without plateau/OOS/trial-count context.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE 4 — VERDICT, SCORECARD, FINDINGS, AND DELETION LIST
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

### 4A. Scorecard

Score 0–10 with confidence (high/medium/low), evidence, strongest aspect, biggest weakness, and minimum action needed to gain one point:

1. Temporal/data integrity
2. Execution fidelity
3. Portfolio/accounting correctness
4. Metrics correctness
5. Statistical validity
6. Reproducibility/determinism
7. Architecture/domain separation
8. Strategy extensibility
9. Research-to-live parity
10. Performance architecture
11. Testing quality
12. Reliability/observability
13. Security/live safety
14. Developer experience
15. User/product experience
16. Deployment readiness

Scale:

- 0–1: absent or dangerously broken
- 2–3: severe weaknesses
- 4–5: functional but fragile
- 6–7: solid with meaningful gaps
- 8: production quality for the intended purpose
- 9: exceptional and extensively validated
- 10: unusually rigorous, independently demonstrated, and difficult to improve materially

Do not award 9 or 10 without extraordinary evidence.

Also score readiness for:

- Personal quantitative research
- Multi-user production use
- Institutional quantitative research
- Paper trading
- Live trading

### 4B. Architecture verdict

Choose exactly one:

- `SOLID FOUNDATION — EXTEND IT`
- `SALVAGEABLE — REFACTOR SPECIFIC SEAMS`
- `PARTIAL REDESIGN REQUIRED`
- `STRUCTURALLY WRONG FOR THE GOAL — REWRITE SPECIFIC CORE ONLY`
- `INSUFFICIENT EVIDENCE`

State:

- What should remain untouched
- What should improve in place
- What should split
- What should merge
- What should be replaced
- What should be deleted
- Why a full rewrite is or is not justified

Do not estimate calendar time unless asked. Use relative effort only.

### 4C. Prioritized findings

For every finding include:

- ID
- Role raising it
- Severity P0–P4
- Title
- Status: confirmed/inferred/unknown
- Evidence
- Why it matters
- Concrete failure scenario
- Recommended change
- Affected files/symbols
- Scope: XS/S/M/L/XL
- Change risk
- Dependencies
- Verification test
- Rollback strategy

Group findings into:

1. Correctness defects
2. Quantitative/statistical risks
3. Architecture defects
4. Performance defects
5. Reliability defects
6. Security defects
7. Testing gaps
8. Developer-experience issues
9. Product/UX issues

### 4D. What to delete

Identify code, abstractions, dependencies, configurations, duplicate pipelines, dead features, and premature generality that cost more than they provide.

For each deletion candidate state:

- Evidence
- Why it is safe or unsafe to remove
- Dependency impact
- Required characterization tests
- Replacement, if any

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE 5 — TARGET ARCHITECTURE AND FEATURE OPPORTUNITIES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Design the smallest target architecture that supports confirmed goals at approximately 10x current workload. Do not design for fictional scale.

### 5A. Target architecture

Provide:

- Recommended package/module tree
- Responsibilities
- One-way dependency rules
- Domain boundaries
- 6–12 core protocols/interfaces with concise signatures
- Data contracts for bars/ticks, signals, orders, fills, positions, account snapshots, trades, run manifests, and metrics where applicable
- Strategy lifecycle
- Backtest lifecycle
- Experiment/optimization lifecycle
- Persistence boundaries
- Job execution model
- Configuration model
- Error taxonomy
- Plugin points
- Observability model
- Testing strategy

Provide Mermaid diagrams for:

- Current architecture
- Target architecture
- Backtest sequence
- Optimization/WFA lifecycle
- Research-to-paper/live sequence, if applicable

For every new queue, service, database, framework, language, or distributed component state:

- Exact problem solved
- Why the current mechanism is insufficient
- Simpler alternative considered
- New operational burden
- Adoption trigger
- Recommendation now/later/never

### 5B. Irreversible decisions

Identify the three most consequential decisions, such as:

- Vectorized, event-driven, bar-replay, or hybrid engine
- Strategy API shared between research and live
- Immutable event/ledger model versus mutable portfolio state
- Single-process versus worker-based execution
- Storage and experiment identity

Argue both sides, expose role disagreement, and recommend one based on verified requirements.

### 5C. Feature opportunities

Evaluate only features that solve a verified or plausible user problem.

Research truth:

- Walk-forward laboratory
- Purged/embargoed/CPCV validation
- PSR/DSR/PBO
- Trial-count and search-history tracking
- Parameter stability maps
- Monte Carlo/block bootstrap
- Cost/latency/delay perturbation
- Research quality gates

Experiment velocity:

- Immutable run manifests
- Dataset fingerprints
- Environment/code/seed capture
- Run registry, diffing, tags, parent/child experiments
- Content-addressed feature cache
- Parallel sweeps
- Checkpoint/resume/cancel
- CLI/API parity

Execution realism:

- Dynamic spread/slippage
- Conservative intrabar policy
- Lower-timeframe replay
- OHLC path enumeration
- Brownian-bridge/constrained path stress tests
- Latency and gap handling
- Partial fills/liquidity
- Margin/liquidation
- Broker/MT5 rules

Insight and explainability:

- Trade explorer
- “Why did this trade happen?” replay
- Entry/exit attribution
- MAE/MFE
- Session/regime breakdown
- Cost attribution
- Parameter surfaces
- Equity/drawdown autopsy
- Calendar returns
- Benchmark comparison

Portfolio research:

- Multi-strategy/multi-asset portfolios
- Volatility targeting
- ATR/risk-parity allocation
- Exposure and concentration constraints
- Correlation/risk contribution
- Multi-currency accounting
- Rebalancing

Regime research:

- Volatility/session classifiers
- Regime-conditioned evaluation
- HMM or other probabilistic regimes only where sample size and validation discipline justify them

Research-to-live bridge:

- Shared strategy contract
- MT5/Python parity harness on identical data and assumptions
- Paper/shadow mode
- Live-versus-expected drift monitoring
- Position/order reconciliation
- Broker adapters
- Risk limits
- Kill switch
- Audit log

For each feature provide:

- User problem solved
- Evidence/fit
- Quantitative value
- Product value
- Strategic differentiation
- Architectural prerequisites
- Implementation complexity
- Maintenance burden
- Correctness risk
- Priority
- Build now / build later / do not build

Score features using an explicitly approximate weighted model:

- 40% research/correctness value
- 20% user value
- 15% differentiation
- 15% architectural fit
- 10% implementation efficiency

Explain scores; do not present them as objective truth.

Deliver:

- Top 5 high-impact/low-effort improvements
- Top 5 strategic features
- Top 5 tempting features not to build yet
- One distinctive killer feature
- One boring infrastructure feature that matters more than it appears
- One single highest-leverage change and what it unlocks

Strongly consider an `MT5 ↔ Python parity laboratory` as the killer feature only if the repository and owner goals support it. It should replay identical inputs/configuration in both engines and produce a divergence report for signals, orders, fills, trades, P&L, and metrics.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE 6 — MIGRATION ROADMAP AND FINAL REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Create an incremental roadmap that keeps the application usable. No big-bang rewrite.

### Wave 0 — Truth baseline

- Freeze reference datasets
- Create immutable fixtures
- Add characterization/golden tests
- Capture data/config/code/seed identity
- Establish accounting and timing invariants
- Record baseline performance and memory profiles

### Wave 1 — Correctness

- Fix P0/P1 temporal, fill, accounting, metric, and data-integrity defects
- Add conservative semantics where ambiguity exists
- Add determinism
- Add OOS boundary enforcement

### Wave 2 — Structural stabilization

- Correct dependency direction
- Split/merge boundaries
- Remove duplicate sources of truth
- Add typed contracts/configuration
- Create experiment identity and error taxonomy

### Wave 3 — Reliability and scale

- Job state machine
- Cancellation/resume/recovery
- Worker isolation
- Structured observability
- Profiling-guided optimization
- Cache correctness

### Wave 4 — High-value product features

- Robustness laboratory
- Experiment comparison
- Trade explainability
- Reporting
- MT5 parity if applicable

### Wave 5 — Advanced capabilities

- Portfolio research
- Advanced execution stress models
- Distributed optimization only if justified
- Paper/live bridge with safety interlocks
- Plugin ecosystem only if justified

For every roadmap item provide:

- Objective
- Exact affected modules/symbols
- Dependencies
- Relative effort XS/S/M/L/XL
- Risk
- Acceptance criteria
- Required tests
- Rollback strategy

Identify no-regret changes that remain useful regardless of future architecture.

### Required final report structure

Use exactly:

# 1. Executive Verdict
# 2. What the Application Actually Is
# 3. Owner Goals and Constraints
# 4. Repository and Technology Map
# 5. Current Architecture
# 6. Backtest and Data-Lineage Trace
# 7. Trust Smoke-Test Verdict
# 8. Quantitative Integrity Audit
# 9. Engineering and Architecture Audit
# 10. Testing Assessment
# 11. Performance Assessment
# 12. Security, Reliability, and Operations
# 13. Scorecard
# 14. Prioritized Findings
# 15. What to Keep, Change, and Delete
# 16. Recommended Target Architecture
# 17. Feature Recommendations
# 18. Migration Roadmap
# 19. Immediate Next Actions
# 20. Remaining Unknowns
# 21. Direct Answer

Section 19 must contain exactly 10 actions in priority order.

Section 21 must answer directly:

- Is the current setup fit for its intended purpose?
- Would you trust its current results with real money?
- What must change first?
- What should remain untouched?
- Does it need cleanup, refactoring, partial redesign, or a rewrite of a specific core?
- What creates the largest improvement per unit of effort?

Use dense, direct language. Use tables where comparison helps. Do not add generic praise or repeat the same finding across sections. Cite repository evidence. Keep facts, inferences, and assumptions visibly distinct.