Draft Geopolitical Turbulance Trapper development plan v1

2026-07-22 05:25:07 +00:00 · 2026-03-09 14:59:01 +10:00
parent aaa9c8cca8
commit d56506a0c9
2 changed files with 526 additions and 2 deletions
@@ -1,12 +1,13 @@
 # CURRENT_STATE
-_Last updated: 2026-03-09 07:47 Australia/Brisbane_
+_Last updated: 2026-03-09 14:46 Australia/Brisbane_
 ## In Flight
 - [in_progress] anti-silence workflow hardening — main — workflow rules hardened again after finding a completion-consumption bug: runtime worker results can reach Tao before main updates state and summarizes them
- [blocked] Geopolitical Turbulence Trapper restart — main — no fresh execution evidence appeared within the 10-minute dispatch window after the 07:04 restart; treating as launch failure / blocked pending Tao’s direction
+- [in_progress] Geopolitical Turbulance Trapper planning — main — project scope has been re-anchored using Tao's restored chats + old Claude draft; writing Development Plan v1 and deciding what to reuse vs rewrite from the HK-only prototype
 ## Blocked / Waiting
 - [blocked] ACP + Codex smoke test — main — 14:46 watchdog re-check: tracked ACP Codex session still has no messages/history or visible artifact trace at all, so status remains blocked / no change and should be treated as an ACP launch/config-path blocker, not in-progress execution
 - [failed] Geopolitical Turbulence Trapper workflow test — main — previous flow test failed: planned workers (`data_worker`, `strategy_worker`, `dashboard_worker`) never produced launch/execution evidence, yet main reported progress as if work were underway
 ## Recently Finished
@@ -0,0 +1,523 @@
 # 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
 - Google
 - 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:
 1. real data collection
 2. product metadata verification
 3. market regime + rule engine
 4. risk engine
 5. AI explanation / summarization
 6. 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:
 1. macro / event panel
 2. market watch panel
 3. target name cards
 4. derivatives action panel
 5. liquidity and execution risk panel
 6. 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
 1. project brief
 2. schema / data model
 3. dashboard wireframe
 4. regime + signal framework
 5. derivatives verification workflow
 6. liquidity risk framework
 7. 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:
 - Google
 - 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:
 1. data correctness
 2. product verification
 3. rule clarity
 4. risk engine
 5. dashboard usability
 6. 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
 1. create the formal project brief in repo/docs
 2. extract the reusable structure from the Claude draft
 3. define clean schemas for targets, instruments, and alerts
 4. design the derivatives verification workflow
 5. define the first HK-only dashboard MVP panels
 6. 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