FTD Detector Skill
FTD lifecycle and evidence contract (#765)
- Keep the FTD event separate from its current health. A close below the FTD-day low is a warning, not automatic rally failure. A later intraday low strictly below the recorded Day 1 low fails that rally; equality holds. This model explicitly uses Day 1, not an interchangeable FTD-candle or closing swing low.
- Missing/non-finite/nonpositive Day 1 or post-FTD low evidence means unavailable. Never substitute a close for a missing low.
- Default Nasdaq evidence is
^IXIC(Composite). Use--nasdaq-symbol QQQonly for a labeled Nasdaq-100 ETF proxy. Never substitute its volume or price into an index series or claim its DD count is the Composite count. No automatic fallback. quality_scoreis an uncalibrated technical heuristic, not success probability.exposure_rangeisNot assessedin every state. Do not derive portfolio percentages from the score; assess breadth, leadership, portfolio limits and operator decisions separately.- The Day 4–10 qualifying window is this model's bounded choice; it is not a claim that every later follow-through is invalid under all O'Neil interpretations.
Purpose
Detect Follow-Through Day (FTD) signals that confirm a market bottom, using an explicit O'Neil-style technical model. Generates a quality score (0-100) with technical health warnings; portfolio exposure is not assessed.
Complementary to Market Top Detector:
- Market Top Detector = defensive (detects distribution, rotation, deterioration)
- FTD Detector = offensive (detects rally attempts, bottom confirmation)
When to Use This Skill
English:
- User asks "Is the market bottoming?" or "Is it safe to buy again?"
- User observes a market correction (3%+ decline) and wants re-entry timing
- User asks about Follow-Through Days or rally attempts
- User wants to assess if a recent bounce is sustainable
- User asks about increasing equity exposure after a correction
- Market Top Detector shows elevated risk and user wants bottom signals
Japanese:
- 「底打ちした?」「買い戻して良い?」
- 調整局面(3%以上の下落)からのエントリータイミング
- フォロースルーデーやラリーアテンプトについて
- 直近の反発が持続可能か評価したい
- 調整後のエクスポージャー拡大の判断
- Market Top Detectorが高リスク表示の後の底打ちシグナル確認
Difference from Market Top Detector
| Aspect | FTD Detector | Market Top Detector |
|---|---|---|
| Focus | Rally-event confirmation | Market deterioration assessment |
| Trigger | Market correction (3%+ decline) | Market at/near highs |
| Signal | Rally attempt → FTD → health assessment | Distribution → deterioration evidence |
| Score | 0-100 heuristic FTD quality | Separate heuristic market-risk score |
| Action | When technical confirmation appears | When deterioration appears |
Execution Workflow
Phase 1: Execute Python Script
Run the FTD detector script:
python3 skills/ftd-detector/scripts/ftd_detector.py --api-key $FMP_API_KEYThe script will:
- Fetch S&P 500 (^GSPC) and Nasdaq Composite (^IXIC) historical data (60+ trading days) from FMP API
- Fetch current quotes for both indices
- Run dual-index state machine (correction → rally → FTD detection)
- Assess post-FTD health (distribution days, invalidation, power trend)
- Calculate quality score (0-100)
- Generate JSON and Markdown reports
API Budget: 4 calls (well within free tier of 250/day)
Phase 2: Present Results
Present the generated Markdown report to the user, highlighting:
- Current market state (correction, rally attempt, FTD confirmed, etc.)
- Quality score and signal strength
- Exposure not assessed: breadth, leadership and portfolio risk require separate inputs
- Key watch levels (swing low, FTD day low)
- Post-FTD health (distribution days, power trend)
Phase 3: Contextual Guidance
Based on the market state, provide additional guidance:
If FTD Confirmed (score 60+):
- Suggest looking at leading stocks in proper bases
- Reference CANSLIM screener for candidate stocks
- State that portfolio sizing and stop placement are not assessed by this score
If Rally Attempt (Day 1-3):
- Advise patience, do not buy ahead of FTD
- Suggest building watchlists
If No Correction:
- FTD analysis is not applicable in uptrend
- Redirect to Market Top Detector for defensive signals
State Machine
NO_SIGNAL → CORRECTION → RALLY_ATTEMPT → FTD_WINDOW → FTD_CONFIRMED
↑ ↓ ↓ ↓
└── RALLY_FAILED ←─────────────┘ FTD_INVALIDATED| State | Definition |
|---|---|
| NO_SIGNAL | Uptrend, no qualifying correction |
| CORRECTION | 3%+ decline with 3+ down days |
| RALLY_ATTEMPT | Day 1-3 of rally from swing low |
| FTD_WINDOW | Day 4-10, waiting for qualifying FTD |
| FTD_CONFIRMED | Valid FTD signal detected |
| RALLY_FAILED | Rally breached the Day 1 low (or exhausted this model's FTD window) |
| FTD_INVALIDATED | Intraday low below the recorded rally Day 1 low |
Quality Score (0-100)
| Score | Signal | Exposure |
|---|---|---|
| 80-100 | Strong FTD | Not assessed |
| 60-79 | Moderate FTD | Not assessed |
| 40-59 | Weak FTD | Not assessed |
| <40 | Very weak FTD (unless explicitly invalidated) | Not assessed |
| 0 | Unavailable: data gap | Not assessed |
Prerequisites
- FMP API Key: Required. Set
FMP_API_KEYenvironment variable or pass via--api-keyflag. - Python 3.9+: With
requestslibrary installed. - API Budget: Four logical data requests per execution; retries may add calls. Endpoint entitlement depends on the provider plan.
Output Files
- JSON:
ftd_detector_YYYY-MM-DD_HHMMSS.json - Markdown:
ftd_detector_YYYY-MM-DD_HHMMSS.md
Data gaps (missing or invalid price bars)
A missing or non-finite close/volume (or a non-positive close) is never read as 0, and bars are never dropped. Bar fields are read through the vendored scripts/_price_bars.py helper.
- JSON
data_gap(bool, every run, at the top level and inmarket_state): true when an index's 60-session window or a post-FTD check hit a bad bar. - JSON
data_quality(every run): per index, the window check (window_sessions,bad_bars,bad_dates,latest_bad) plussp500.power_trend_bad_barsfor the power-trend input (counted only when the power trend runs, 50+ bars). Each index block also carries its owndata_quality, anderrorwhen the analysis failed ("Insufficient data" or "Data gap: ..."). - Close/volume-gapped index:
NO_SIGNALwithcurrent_price/lookback_high/correction_depth_pctset tonull; no rally or FTD logic runs for it. With any gapped index the run'scombined_stateis reported asNO_SIGNALwithdata_gap: true, meaning state unavailable (not an uptrend), withftd_index: nulland no post-FTD checks. The other index is never promoted, because the gap could be hiding the gapped index's own (possibly invalidated) FTD. Each index's own analysis stays in the JSON. The Markdown headline reads "State unavailable (data gap)". - Unavailable score: if any index is gapped, or the post-FTD distribution or invalidation check has a gap,
quality_scoreistotal_score: 0(always an int, nevernull),signal: "Unavailable: data gap",exposure_range: "Not assessed",data_gap: true. Treat this as "no usable confirmation": do not increase exposure on it. A gapped distribution check keepsdistribution_count: 0(int) withdata_gap: true; a gapped invalidation check reportsinvalidated: null. A post-FTD gap also reports the combined state asNO_SIGNALwithdata_gap: true(state unavailable), since the FTD can be neither confirmed nor invalidated. - Power trend: a bad close anywhere in its input gives
power_trend: nullwith areason; this alone does not setdata_gapor change the score. - Volume 0 is a data gap. For ^GSPC and the selected Nasdaq instrument a zero session volume is provider missing data, so a missing, invalid or zero volume inside the 60-session window (or the post-FTD checks) marks a data gap. This is a behavior change from earlier versions, which read volume 0 as real.
Reference Documents
skills/ftd-detector/references/ftd_methodology.md
- O'Neil's FTD rules in detail
- Rally attempt mechanics and day counting
- Historical FTD examples (2020 March, 2022 October)
skills/ftd-detector/references/post_ftd_guide.md
- Post-FTD distribution timing and heuristic penalties
- Power Trend definition and conditions
- Qualitative favorable/adverse context (not calibrated outcome predictors)
When to Load References
- First use: Load
skills/ftd-detector/references/ftd_methodology.mdfor full understanding - Post-FTD questions: Load
skills/ftd-detector/references/post_ftd_guide.md - Regular execution: References not needed - script handles analysis
FTD-day-low pressure caps published quality at 59 (uncalibrated conservative heuristic); it does not erase the event or imply rally failure.
- Lifecycle-low gap: If only a Day 1/post-FTD low is missing, per-index and combined state are
NO_SIGNALwithdata_gap: true. Known prices and any already-established historical event evidence may remain visible; this does not mean the lifecycle is assessable.