VWAP Pull-In Classifier Refinement Plan

Date 2026-06-04 · Status: PLAN ONLY — no DB / taxonomy / classifier / VCET / Scorecards changes · Driver: PI_TREND_ROTATION_WINNERS_REVIEW — only 1 of 5 ROTATION winners in the vwap-pull-in -> trend bucket was a true ROTATION → TREND conversion · Scope: Decide how to separate true Pull-In → Trend from profitable Pull-In / VWAP rotation scalps, without breaking the canonical taxonomy.

1. Current problem

How gen_scorecard.py currently assigns vwap-pull-in -> trend

The 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).

What the rule actually fires on

ConditionWhat it checksWhat it does NOT check
pnl > 0Trade was profitableWhy it was profitable
dist_sd ≤ 1.0Entry was near session avgWhether VWAP itself was rising/falling/flat
exit-move ≥ 2.0 est-SDExit traveled wideWhether the move was trend, rotation rip, or noise

It is outcome-based AND profit-based AND exit-width-based. It is NOT:

Diagnosis

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.

2. Mechanism distinction

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.

A. True Pull-In → Trend (conversion) A

Reference 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.

B. VWAP Rotation Scalp / TD VWAP Pull-In (mean-reversion) B

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.

C. Wrong-side escape / misclassified winner C

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.

3. Proposed classifier fields

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):

FieldTypePurposeWhen populated
mechanism_slugTEXTMechanism class A/B/C: pull_in_to_trend_confirmed, vwap_rotation_scalp, wrong_side_escape, insufficient_dataOnly when bars+VCET available within kti window
mechanism_confidenceTEXTHIGH / MEDIUM / LOW — confidence in mechanism callAlways when mechanism_slug populated
state_at_entryTEXTVCET state at entry-barOnly when bars available
state_at_plus_5TEXTVCET state at entry+5minOnly when bars available
state_at_plus_15TEXTVCET state at entry+15minOnly when bars available
band_width_delta_5minNUMERICbw(entry+5) - bw(entry) (positive = expansion)Only when bars available
slope_delta_5minNUMERICslope(entry+5) - slope(entry) (positive accel for LONG = good)Only when bars available
conversion_confirmedBOOLEANTRUE if state transitioned to EARLY_EXPANSION / EXPANSION_CONFIRMED / TREND_* within 15 min in trade directionOnly when bars available

Three-layer model

LayerFieldWhat it says
1. Raw classifierraw_classifier_outputWhat gen_scorecard.py's priority cascade picked
2. Canonical taxonomycanonical_strategy_slugThe canonical slug name (outcome-based today)
3. Mechanismmechanism_slug + companionsWhat 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.

4. Proposed rule candidates (research-level)

These are heuristics derived from the 5-trade trajectory review. Each needs validation against a larger sample before being committed to code.

Rule A: True Pull-In → Trend → mechanism_slug = 'pull_in_to_trend_confirmed'

Required (ALL must hold):

  1. Entry state in {ROTATION, COMPRESSION, EARLY_EXPANSION}
  2. Within 5-15 min of entry, AT LEAST 3 of:
    • band_width_pct(entry+5) ≥ band_width_pct(entry) * 1.5 — bands expanded ≥50% in 5 min
    • expansion_score(entry+5) ≥ 50 — expansion firing
    • LONG: slope_deg(+5) - slope_deg(0) ≥ +5° — slope accelerated up by ≥5°
    • SHORT: slope_deg(+5) - slope_deg(0) ≤ -5° — slope accelerated down by ≥5°
    • State transitions into {EARLY_EXPANSION, EXPANSION_CONFIRMED, TREND_UP/DOWN matching direction} within 15 min
  3. P&L positive

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.

Rule B: VWAP Rotation Scalp → mechanism_slug = 'vwap_rotation_scalp'

Required (ALL must hold):

  1. Entry state = ROTATION (any reason_code)
  2. State REMAINS ROTATION (or MEAN_REVERSION) at entry+15min AND entry+25min
  3. |slope_deg| < 2° at all of (entry, +5, +10, +15) — slope flat throughout
  4. band_width_pct(entry+25) ≤ band_width_pct(entry) * 1.2 — bands didn't materially expand
  5. expansion_score < 50 at all snap points
  6. P&L positive

Confidence: 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.

Rule C: Wrong-side escape → mechanism_slug = 'wrong_side_escape'

Required (any ONE triggers):

  1. Within 15 min of entry, state transitions to TREND_* OPPOSITE trade direction (LONG → TREND_DOWN; SHORT → TREND_UP)
  2. Slope accelerates ≥15° AGAINST trade direction within 5 min of entry
  3. expansion_score ≥ 75 at entry+5 AND slope_sign opposite to trade direction

Confidence: 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.

Rule D: Insufficient data → mechanism_slug = 'insufficient_data'

Triggered when: no bars available in kti window (>14 days old); VCET engine failed; snap window empty (session boundary).

Ordering / collision rules

5. Impact on existing report

The Canonical Strategy Performance Report should be re-read with care

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:

What this changes about the Quality Gate

VWAP_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.

What this does NOT change

6. Next validation step (smallest possible)

Goal: 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.

Scope

Method (no DB / no code changes)

  1. Read same population as Phase 4a pilot, filter to vwap-pull-in -> trend winners
  2. Re-run trajectory snap at offsets {-5, 0, +5, +10, +15, +25} for ALL of them
  3. Apply rules A/B/C/D in priority order (C > A > B > D)
  4. Emit a single CSV/markdown table — read-only, no DB writes

✓ Status: completed 2026-06-04 — see PULL_IN_TO_TREND_MECHANISM_AUDIT.html

Result: 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).

7. Do not implement yet

Nothing in this plan is implemented or queued for implementation. Specifically NOT being done:

8. Final recommendation

Recommendation: A — Keep vwap-pull-in -> trend as-is, but add mechanism_slug (and companion VCET-context fields) as additive research metadata.

Why A and not B (split into separate canonical slugs)

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.

Why A and not C (rename the slug)

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.

Why A and not D (defer)

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.

What "Recommendation A" means concretely (phased, future work)

  1. Now (done by this plan): mechanism rules A/B/C/D drafted; smallest next test scoped (§6)
  2. Next research turn (separate approval): run §6 — build PULL_IN_TO_TREND_MECHANISM_AUDIT.md. (✓ done 2026-06-04)
  3. After mechanism audit (separate approval): if signal real and rules hold up across ≥15 trades, propose ADR to add mechanism_slug + 7 companion fields. Still additive, still NULLable for historicals.
  4. After enough mechanism data accumulates (3-6 months): revisit B (split into separate canonical slugs) with a real evidence base. Until then, slug stays.

What is changing today

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.

Links