gen_scorecard.py currently assigns vwap-pull-in -> trendThe exact rule lives in classify_trade(), gen_scorecard.py lines 454-468, Priority 3:
# PRIORITY 3: VWAP Pull-In → Trend (winner that exited > 2 SD)
elif (pnl > 0 and exit_p > 0
and dist_sd <= BAND1_SD * 2 # entry within 1.0 est-SD of avg
and abs(exit_p - entry) / est_sd >= BAND3_SD): # exit moved ≥ 2.0 est-SD from entry
raw = "VWAP_PULL_IN_TO_TREND"
tag_class = slug_for(raw) # 'vwap-pull-in -> trend'
strategy = display_for(tag_class) # 'VWAP Pull-In -> Trend'
Where: BAND1_SD = 0.5, so BAND1_SD * 2 = 1.0 · BAND3_SD = 2.0 · est_sd = avg_entry * 0.003 (heuristic, ~0.3% of price per SD; no real VWAP bands consulted).
| Condition | What it checks | What it does NOT check |
|---|---|---|
pnl > 0 | Trade was profitable | Why it was profitable |
dist_sd ≤ 1.0 | Entry was near session avg | Whether VWAP itself was rising/falling/flat |
exit-move ≥ 2.0 est-SD | Exit traveled wide | Whether the move was trend, rotation rip, or noise |
It is outcome-based AND profit-based AND exit-width-based. It is NOT:
The slug name vwap-pull-in -> trend makes a mechanism claim ("Pull-In converts to Trend") that the rule cannot verify. The rule sees outcome; the slug claims mechanism. That gap is what produced the mislabeling.
The PI → Trend bucket actually contains three distinct trade types. They share an entry zone (near VWAP) and a profitable outcome, but the mechanism that produced the profit is different — and so is the correct management.
expansion_score rises above 50; state transitions EARLY_EXPANSION → EXPANSION_CONFIRMED → TREND_UP / TREND_DOWNReference example: JOBY 5/28 09:31 LONG +$12.45 — Entry bw 1.54, slope +1.6° → at +5min bw 5.03, slope +31.4° → at +15min state TREND_UP score 100. Management: trend-hold; trail behind structure; let the runner run.
ROTATION_FLAT_BANDS)expansion_score stays low (< 35)Reference examples: DAL 5/26 13:56 +$68 (slope −0.39° → −0.20°, bw 1.49 throughout); DAL 5/28 13:56 +$5.59 (slope +0.21° → +0.11°, bw 2.84 → 2.75, comp_score=30). Management: target/mean-reversion based; exit at the band; don't expect continuation.
Reference example: JOBY 5/29 09:31 LONG +$0.70 — Entry slope −3.94°, bw 2.05 → at +5min slope −52.7°, state TREND_DOWN. Management: "do not let outcome validate the setup." P&L is noise, not signal.
Goal: preserve current canonical_strategy_slug, do not break Phase 2 backfill or existing reports. Add ADDITIVE mechanism clarity fields.
Recommended new fields on main.trade_context (research-only, NULLable):
| Field | Type | Purpose | When populated |
|---|---|---|---|
mechanism_slug | TEXT | Mechanism class A/B/C: pull_in_to_trend_confirmed, vwap_rotation_scalp, wrong_side_escape, insufficient_data | Only when bars+VCET available within kti window |
mechanism_confidence | TEXT | HIGH / MEDIUM / LOW — confidence in mechanism call | Always when mechanism_slug populated |
state_at_entry | TEXT | VCET state at entry-bar | Only when bars available |
state_at_plus_5 | TEXT | VCET state at entry+5min | Only when bars available |
state_at_plus_15 | TEXT | VCET state at entry+15min | Only when bars available |
band_width_delta_5min | NUMERIC | bw(entry+5) - bw(entry) (positive = expansion) | Only when bars available |
slope_delta_5min | NUMERIC | slope(entry+5) - slope(entry) (positive accel for LONG = good) | Only when bars available |
conversion_confirmed | BOOLEAN | TRUE if state transitioned to EARLY_EXPANSION / EXPANSION_CONFIRMED / TREND_* within 15 min in trade direction | Only when bars available |
| Layer | Field | What it says |
|---|---|---|
| 1. Raw classifier | raw_classifier_output | What gen_scorecard.py's priority cascade picked |
| 2. Canonical taxonomy | canonical_strategy_slug | The canonical slug name (outcome-based today) |
| 3. Mechanism | mechanism_slug + companions | What the trade actually did mechanically (when bars exist) |
This preserves the audit trail, doesn't break existing dashboards, and gives a place to grow mechanism analysis as bar history accumulates.
These are heuristics derived from the 5-trade trajectory review. Each needs validation against a larger sample before being committed to code.
mechanism_slug = 'pull_in_to_trend_confirmed'Required (ALL must hold):
ROTATION, COMPRESSION, EARLY_EXPANSION}band_width_pct(entry+5) ≥ band_width_pct(entry) * 1.5 — bands expanded ≥50% in 5 minexpansion_score(entry+5) ≥ 50 — expansion firingslope_deg(+5) - slope_deg(0) ≥ +5° — slope accelerated up by ≥5°slope_deg(+5) - slope_deg(0) ≤ -5° — slope accelerated down by ≥5°Confidence: HIGH if 4+ of 5 sub-conditions hold · MEDIUM if 3 hold · LOW if 3 hold but state still ROTATION at +15min. Reference: JOBY 5/28 would score HIGH.
mechanism_slug = 'vwap_rotation_scalp'Required (ALL must hold):
ROTATION (any reason_code)ROTATION (or MEAN_REVERSION) at entry+15min AND entry+25min|slope_deg| < 2° at all of (entry, +5, +10, +15) — slope flat throughoutband_width_pct(entry+25) ≤ band_width_pct(entry) * 1.2 — bands didn't materially expandexpansion_score < 50 at all snap pointsConfidence: HIGH if all 6 hold cleanly · MEDIUM if 5 hold and one borderline · LOW if state stays ROTATION but slope wandering ±3°. Reference: DAL 5/26 and DAL 5/28 would both score HIGH.
mechanism_slug = 'wrong_side_escape'Required (any ONE triggers):
expansion_score ≥ 75 at entry+5 AND slope_sign opposite to trade directionConfidence: HIGH if state transitions opposite-direction within 5 min · MEDIUM if slope accelerates strongly opposite but state doesn't flip until +15 · LOW if just one numeric condition fires. Reference: JOBY 5/29 would score HIGH.
mechanism_slug = 'insufficient_data'Triggered when: no bars available in kti window (>14 days old); VCET engine failed; snap window empty (session boundary).
CANONICAL_STRATEGY_PERFORMANCE_REPORT shows vwap-pull-in -> trend with a +$367 cumulative edge across the sample. This bucket-level number is still real — the trades did happen, and they did make money. But the mechanism breakdown of that +$367 is not what the slug name suggests:
vwap-pull-in -> trend are profitable as a bucketVWAP_PULL_IN_QUALITY_GATE uses RVOL + gap as the primary filter, which catches the Pull-In split cleanly at the BUCKET level. That gate is still correct. What's NOT correct is treating the -> trend suffix as evidence of trend mechanics — it isn't.
Quality Gate update implied: keep RVOL + gap as primary go/no-go; DO NOT use the -> trend slug as a "this was a trend trade" signal; add optional VCET-numerics secondary filter (vcet_score > 55, band_width < 3.0, slope sign matches direction) when bars are live.
vwap-pull-in -> trend should NOT be renamed or removed yetGoal: apply rules A/B/C/D to every vwap-pull-in -> trend trade with bars available, build the evidence table, see if the mechanism split is real at sample size.
canonical_strategy_slug = 'vwap-pull-in -> trend' in main.trade_contextentry_time within the kti retention window (~14 days)mechanism_slug = 'insufficient_data' and no further analysisvwap-pull-in -> trend winnersResult: 1 true conversion / 3 rotation scalps / 2 wrong-side / 9 insufficient_data (of which 3 were trend-continuation entries — a 4th mechanism the rule set doesn't model).
main.trade_contextmechanism_slug field added to TradeContext dataclass or upsert_contexts()main.user_strategiescanonical_strategy_slug renaminggen_scorecard.py Priority 3 rulevwap-pull-in -> trend as-is, but add mechanism_slug (and companion VCET-context fields) as additive research metadata.Splitting would require reworking the 25-slug taxonomy mid-stride (Phase 1 canonical work just landed 6/2); redoing Phase 2 historical backfill (297 rows) with new slug assignments; updating every downstream report and dashboard; making a structural commitment based on a 5-trade trajectory sample.
5-trade evidence is enough to justify SUSPECTING a mechanism split exists. It is not enough to justify CHANGING the canonical taxonomy.
Renaming to something like vwap-pull-in-wide-exit would describe the rule more accurately but: make every existing report look like data was lost; lose connection to the trader-facing playbook name; still not fix the mechanism question.
Quality Gate is already in production use (cheatsheet, MGP block, intraday checklist all reference the bucket). Some traders may already be reading -> trend as "trend mechanism confirmed" — wrong TODAY, getting wronger every week. Adding mechanism_slug as an OPTIONAL NULLable field is non-breaking and lets data accumulate.
PULL_IN_TO_TREND_MECHANISM_AUDIT.md. (✓ done 2026-06-04)mechanism_slug + 7 companion fields. Still additive, still NULLable for historicals.Nothing in the codebase, DB, or live reports. The Quality Gate documentation and MGP block can be re-read with the §5 caveats in mind. The vwap-pull-in -> trend slug retains its current outcome-based meaning. The mechanism question is now documented and queued behind §6 as the next testable step.