13 KiB
Geopolitical Turbulance Trapper — Development Plan v1
1. Project identity
Project name: Geopolitical Turbulance Trapper
Project type: small-scale event-driven trading intelligence and derivatives decision-support system
Primary goal: Track real-time geopolitical, macro, commodity, earnings, and market information across HK, US, and AU focus markets; map those drivers into actionable short-term trading setups on target shares, indices, and derivatives.
What it should help answer:
- What is the current regime: panic, rebound, chop, commodity shock, AI-infra momentum, earnings squeeze, or mixed?
- Which names are most exposed or most resilient?
- Which derivative type is appropriate right now: CBBC, warrant, put/call, bear/bull, options, LEAPS, or no trade?
- Where is the buying zone, danger zone, take-profit zone, and do-not-chase zone?
- What is the liquidity and execution risk of the proposed instrument under fast markets?
2. Why this project exists
The market backdrop is dominated by overlapping uncertainty and thematic opportunity:
- Middle East and other geopolitical instability
- oil and commodity shocks
- AI breakthrough and infrastructure capex trends favoring shovel providers
- earnings season with likely beats in selected names
- elevated chop and false breaks across HK tech and global risk assets
This project is intended to convert those overlapping narratives into a structured, repeatable workflow that is more reliable than ad-hoc chat analysis.
3. Target scope
3.1 Markets
- HK — first MVP priority
- US — second priority
- AU — later extension after HK logic is stable
3.2 Core watchlist (initial)
HK
- Tencent
- Alibaba
- Xiaomi
- HSI
- HSTECH
US
- TSM
- later candidates: NVDA, AMD, META, oil/metal-linked names
Asia ex-HK
- Samsung
- SK Hynix
Macro / driver instruments
- Brent crude
- WTI crude
- gold
- USD / FX proxies
- volatility indicators
- rates / bond-yield proxies (later)
4. Product goals
4.1 Primary system goals
User-selected primary goals already implied by prior drafts:
- signal when to buy/sell derivatives
- predict likely short-term direction
- detect volatility spikes for risk management
4.2 Output format
Primary output should be a dashboard with visual alerts, supported by rule-based textual recommendations.
4.3 Decision support outputs
Per target / instrument, the system should output:
- directional bias
- volatility regime
- event/risk tags
- candidate derivative types
- buying zone
- danger zone
- reduce/exit zone
- liquidity risk review
- execution warning
- confidence / evidence level
5. Hard requirements
5.1 Facts before opinions
The system must never rely on unverified AI-generated product facts.
Examples of facts that must be independently verified before a product recommendation is considered high-confidence:
- product code
- underlying
- issuer
- call level / strike / barrier
- expiry
- ratio / entitlement
- bid / ask / spread
- volume / turnover
- outstanding / open interest proxy
5.2 Bear as well as bull
The system must support:
- bull tools
- bear tools
- paired / hedge structures
- staged switch strategies (e.g. panic shield then rebound capture)
5.3 Liquidity and execution risk are first-class
The system must explicitly evaluate:
- historic volume / turnover behavior
- spread widening under sharp market moves
- issuer quote reliability proxy
- outstanding concentration risk
- risk of delayed or partial order execution in fast markets
5.4 Strict execution discipline
Every recommendation should include:
- entry condition
- invalidation condition
- stop / reduce rule
- no-chase rule
- special event warning (earnings, geopolitical headline, overnight gap)
6. What we learned from earlier prototypes
6.1 What is worth keeping
Earlier dashboard/system prototypes had useful ideas:
- dashboard-first output
- signal cards
- volatility gauge / regime logic
- signal breakdown panel
- CBBC knock-out buffer monitoring
- derivatives recommendation panel
- macro/geopolitical controls
- modular code layout: config / data / models / signals / backtest / dashboard
6.2 What must be changed
Earlier drafts were too weak in several areas:
- derivatives facts were too easy to hardcode or hallucinate
- AI was implicitly trusted as a facts layer
- HK-only framing is now too narrow
- strategy logic was too biased toward bullish rebound capture
- liquidity/outstanding risk was not elevated enough
- external data quality and verification rules were not strict enough
6.3 New design principle
AI should be the explanation layer, not the source of truth layer.
Correct order:
- real data collection
- product metadata verification
- market regime + rule engine
- risk engine
- AI explanation / summarization
- dashboard rendering
7. High-level system architecture
Module A — Event Radar
Track and classify relevant events:
- geopolitical headlines
- sanctions / conflict escalation / de-escalation
- earnings and guidance
- AI infra / capex headlines
- commodity shocks
- supply chain and policy headlines
Output:
- event tag
- affected names / sectors / markets
- severity score
- estimated duration
- confidence score
Module B — Market Regime Engine
Infer current regime using price, volatility, and macro data.
Candidate regimes:
- panic sell
- dead-cat bounce
- high-volatility range/chop
- commodity shock
- earnings squeeze setup
- AI infra momentum
- mixed/conflicted regime
Output:
- regime label
- supporting evidence
- derivatives suitability rules
Module C — Instrument Scanner
Scan available instruments by market.
HK
- CBBC bull / bear
- call / put warrants
US
- options
- LEAPS
Output fields per candidate:
- code / contract id
- underlying
- type
- strike / call / barrier
- expiry
- issuer / venue
- current price
- spread
- volume / turnover
- outstanding / OI proxy
- KO buffer or moneyness
- liquidity risk score
Module D — Signal / Opportunity Engine
Map:
- event state
- regime state
- underlying price behavior
- instrument characteristics into concrete setups.
Examples:
- panic leg using HSI/HSTECH bear
- rebound leg using Tencent / Alibaba call or deeper-buffer bull
- earnings-beat volatility capture
- AI-infra continuation for TSM / SK Hynix / Samsung
Module E — Risk Engine
Must evaluate:
- direction risk
- overnight gap risk
- KO risk
- IV crush / theta risk
- spread/quote deterioration
- outstanding crowding risk
- no-fill / late-fill risk
Module F — Dashboard / UI
Main user-facing layer.
Panels:
- macro / event panel
- market watch panel
- target name cards
- derivatives action panel
- liquidity and execution risk panel
- alerts / watchlist / danger monitor
8. Recommended dashboard layout
Top bar
- live status indicator
- last refresh time
- market regime badge
- geo risk badge
- volatility badge
Panel 1 — Macro Snapshot
- Brent / WTI
- gold
- volatility index / proxy
- FX / rates proxy
- event severity highlights
Panel 2 — Target Monitor
Per target card:
- latest price / move
- short-term bias
- earnings timing
- event sensitivity
- volatility regime
- support / resistance / danger zone
Panel 3 — Derivatives Board
For each target:
- curated candidate instruments
- risk tier
- liquidity tier
- recommended usage (bear leg / rebound leg / hedge / avoid)
- entry zone / danger zone / exit rules
Panel 4 — Signal Breakdown
Explain why a signal exists:
- price action
- event driver
- volatility state
- commodity linkage
- earnings proximity
- liquidity constraints
Panel 5 — Alerts
- KO proximity alert
- spread widening alert
- geo shock alert
- earnings-event alert
- strategy invalidation alert
9. Data-source strategy
9.1 Principles
- prioritize official or near-official sources for derivative metadata
- tolerate lower-quality sources only for non-critical exploratory fields
- label confidence level per field
9.2 Proposed source layers
Layer 1 — Market prices / broad data
- Yahoo Finance or equivalent for fast prototyping
- later upgradeable market data sources as needed
Layer 2 — HK derivatives metadata
- HKEX and issuer pages as the primary truth sources
- avoid trusting chat-provided product codes without verification
Layer 3 — Event/news layer
- curated RSS / news APIs / official releases
- event classification and severity tagging
Layer 4 — Liquidity/risk layer
- live bid/ask if available
- turnover and volume history
- outstanding
- historical spread/quote behavior if feasible
10. Strategy framework (v1)
The system should support multiple strategy families instead of one bullish mean-reversion script.
Strategy family A — Panic shield
Use broad-market or tech-index bear exposure to capture the first risk-off leg.
Strategy family B — Rebound capture
After panic exhaustion, rotate into deeper-buffer bull or call structures on high-quality rebound targets.
Strategy family C — Chop capture
In high-volatility ranges, prefer instruments and rules suited to repeated swings rather than one-direction conviction.
Strategy family D — Earnings-driven asymmetry
Focus on names likely to beat expectations but still exposed to macro risk; choose derivatives based on IV, timing, and gap risk.
Strategy family E — Theme continuation
AI infra / semiconductor / commodity-linked continuation trades in US and Asia.
11. MVP definition
11.1 MVP objective
Prove that the system can produce fact-checked, risk-aware, visually presented trade setups for HK targets under geopolitical uncertainty.
11.2 MVP market scope
HK only, first:
- HSI
- HSTECH
- Tencent
- Alibaba
- Xiaomi
11.3 MVP instrument scope
- HK CBBC bull / bear
- HK call / put warrants
11.4 MVP deliverables
- project brief
- schema / data model
- dashboard wireframe
- regime + signal framework
- derivatives verification workflow
- liquidity risk framework
- first working dashboard prototype
12. Suggested implementation phases
Phase 0 — Project reset and reference audit
- inventory the old Claude draft and earlier dashboard concepts
- identify reusable files vs files to rewrite
- avoid blindly inheriting hardcoded product facts
Phase 1 — Brief + schemas
Create:
- project brief
- event schema
- target schema
- derivative schema
- risk schema
- alert schema
Phase 2 — HK data and verification layer
Build:
- target price ingestion
- macro ingestion
- HK derivative metadata verification workflow
- confidence labels for each field
Phase 3 — Regime + risk engine
Implement:
- event tags
- market regime rules
- liquidity/execution risk scoring
- CBBC safety buffer logic
- warrant suitability rules
Phase 4 — HK dashboard MVP
Build dashboard panels with:
- macro snapshot
- target cards
- derivatives table
- risk panel
- alert panel
Phase 5 — Strategy logic expansion
Add:
- bear + bull + combo workflows
- panic/rebound/chop playbooks
- staged switching logic
Phase 6 — US extension
Add:
- TSM
- options / LEAPS framework
Phase 7 — AU extension
Add AU market target mapping if still valuable after HK/US validation.
13. Technical stance
13.1 What to de-prioritize for now
Do not start by over-investing in:
- complex ML pipelines
- fancy explainability layers
- model competitions
- aggressive backtesting sophistication before data integrity is solved
13.2 What to prioritize instead
Prioritize:
- data correctness
- product verification
- rule clarity
- risk engine
- dashboard usability
- AI-generated summaries only after the above are stable
14. Reuse plan for the existing Claude draft
Keep as likely reusable
- folder structure
- README framing as a prototype
- Streamlit dashboard skeleton
- some parameter organization
- some risk-parameter naming
Rewrite or heavily audit
- hardcoded derivative codes and assumptions
- data sources and fetch logic
- signal engine directional assumptions
- over-reliance on ML-first thinking
- liquidity scoring
- bear/combination strategy support
15. Immediate next steps
- create the formal project brief in repo/docs
- extract the reusable structure from the Claude draft
- define clean schemas for targets, instruments, and alerts
- design the derivatives verification workflow
- define the first HK-only dashboard MVP panels
- begin implementation with data correctness first
16. Success criteria for v1
The project counts as successful only if it can do all of the following for MVP HK targets:
- produce a coherent market regime classification
- provide instrument candidates with verified metadata
- identify buy / danger / exit zones
- explain when to prefer bear vs bull vs warrant vs no trade
- surface liquidity/execution risk clearly
- present all of this in a usable visual dashboard
17. Guiding principle
This system should help survive uncertainty, not hallucinate confidence.
That means:
- facts before opinions
- rules before vibes
- verified products before flashy recommendations
- liquidity and execution warnings before leveraged enthusiasm