zigzag-pattern-classifier

What this skill does

# ZigZag Swing Pattern Classifier

Complete taxonomy for classifying ZigZag swing patterns by structure and market regime. Every confirmed ZigZag sequence maps to exactly one variant — no gaps, no overlaps.

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## When to Use

- Classifying a confirmed L₀→H₁→L₂ (two-pivot) or L₀→H₁→L₂→H₃ (three-pivot) swing
- Looking up market regime implications of a specific pattern
- Answering "how many distinct patterns exist?" and proving exhaustiveness
- Implementing pattern labeling in code (Rust `qta` crate, Python pipelines)
- Understanding the epsilon tolerance band that defines "equal"
- Applying Freedman-Diaconis binning for sub-classification depth

## Notation (Single Source of Truth)

| Symbol | Definition                                         | Example  |
| ------ | -------------------------------------------------- | -------- |
| **L₀** | Initial low (first confirmed pivot)                | 1.0800   |
| **H₁** | Swing high (reversal peak)                         | 1.0850   |
| **L₂** | Second low (retracement)                           | 1.0810   |
| **H₃** | Second high (three-pivot only)                     | 1.0870   |
| **W**  | Swing magnitude: H₁ − L₀                           | 0.0050   |
| **z**  | Normalized retracement: (L₂ − L₀) / (H₁ − L₀)      | 0.20     |
| **o**  | Volatility-normalized overshoot: (L₀ − L₂) / ATR₁₄ | 0.35     |
| **ε**  | Tolerance band for "equal" classification          | 5 pips   |
| **τ**  | ZigZag reversal threshold                          | 6.6 pips |

### Price Level Comparisons

| Code   | Meaning     | Condition       |
| ------ | ----------- | --------------- |
| **HL** | Higher Low  | L₂ > L₀ + ε     |
| **EL** | Equal Low   | \|L₂ − L₀\| ≤ ε |
| **LL** | Lower Low   | L₂ < L₀ − ε     |
| **HH** | Higher High | H₃ > H₁ + ε     |
| **EH** | Equal High  | \|H₃ − H₁\| ≤ ε |
| **LH** | Lower High  | H₃ < H₁ − ε     |

---

## Part 1: Two-Pivot Patterns (UP-DOWN)

Pattern: **L₀ → H₁ → L₂** (one up-leg, one down-leg)

### Base Classification (3 Classes)

Every UP-DOWN triplet falls into exactly one:

| Class  | Condition       | Meaning               | Frequency |
| ------ | --------------- | --------------------- | --------- |
| **EL** | \|L₂ − L₀\| ≤ ε | Equal Low (retest)    | ~20–30%   |
| **HL** | L₂ > L₀ + ε     | Higher Low (pullback) | ~50–60%   |
| **LL** | L₂ < L₀ − ε     | Lower Low (undercut)  | ~10–20%   |

### Granular Classification: 9 FD-Binned Variants

HL and LL each decompose into 4 sub-classes using Freedman-Diaconis binning on normalized coordinates:

- **HL bins** use z = (L₂ − L₀) / (H₁ − L₀), ranging 0 to 1
- **LL bins** use o = (L₀ − L₂) / ATR₁₄, ranging 0 to ∞

| Variant    | z or o Range    | Market Regime                        | Probability |
| ---------- | --------------- | ------------------------------------ | ----------- |
| **EL**     | \|z\| ≤ ε_r     | Retest — support re-established      | 20–30%      |
| **HL-FD1** | 0.75 < z < 1.0  | Shallow pullback — buyers in control | 20–25%      |
| **HL-FD2** | 0.50 < z ≤ 0.75 | Moderate pullback — Fib 38–50%       | 15–20%      |
| **HL-FD3** | 0.25 < z ≤ 0.50 | Deep pullback — Fib 61.8%            | 10–15%      |
| **HL-FD4** | 0 < z ≤ 0.25    | Near-complete retrace — barely held  | 5–10%       |
| **LL-FD1** | o ≤ q₂₀         | Micro undercut — brief false break   | 8–12%       |
| **LL-FD2** | q₂₀ < o ≤ q₄₀   | Shallow undercut — moderate panic    | 4–8%        |
| **LL-FD3** | q₄₀ < o ≤ q₆₀   | Deep undercut — structural break     | 2–5%        |
| **LL-FD4** | o > q₆₀         | Extreme undercut — tail event        | <2%         |

### Trading Implications

| Variant    | Entry Signal         | Stop Loss    | Target       |
| ---------- | -------------------- | ------------ | ------------ |
| **EL**     | Long from L₀+ε       | L₀−ε         | H₁ + ΔH      |
| **HL-FD1** | Long from L₂         | L₂−ε         | H₁ + ΔH      |
| **HL-FD2** | Long at confirmation | L₂−ε         | Prior H + ΔH |
| **HL-FD3** | Reduced size; wait   | L₂−ε         | Support + ΔH |
| **HL-FD4** | Extreme risk; avoid  | L₂−ε         | Critical     |
| **LL-FD1** | Short spike trade    | L₂+spike     | L₀           |
| **LL-FD2** | Wait for reversal    | Breakout     | L₀           |
| **LL-FD3** | Short continuation   | Reversal     | New lows     |
| **LL-FD4** | Crisis mode; hedge   | Capitulation | TBD          |

### Optional Sub-Classification Flags

Attach to any variant for richer context:

| Flag   | Meaning                         | Signal                         |
| ------ | ------------------------------- | ------------------------------ |
| **+C** | Any close < L₀ between H₁→L₂    | Stronger bearish commitment    |
| **+S** | L₂ occurs in single bar (spike) | Sharp reversal; mean reversion |
| **+X** | Wicks below L₀ only, no close   | Liquidity grab; false break    |

Example labels: `HL-FD2+C`, `LL-FD4+S+C`, `EL+X`

---

## Part 2: Three-Pivot Patterns (UP-DOWN-UP)

Pattern: **L₀ → H₁ → L₂ → H₃** (up-leg, down-leg, up-leg)

### 9 Exhaustive Variants

Two independent dimensions × 3 values each = **3×3 = 9 mutually exclusive, collectively exhaustive variants**.

**Dimension 1** — L₂ vs L₀: {HL, EL, LL}
**Dimension 2** — H₃ vs H₁: {HH, EH, LH}

| #   | L₂ vs L₀ | H₃ vs H₁ | Name                        | Market Regime           |
| --- | -------- | -------- | --------------------------- | ----------------------- |
| 1   | HL       | HH       | **Continuation impulse**    | Bull trend continuation |
| 2   | HL       | EH       | **Double-top test**         | Range, bullish bias     |
| 3   | HL       | LH       | **Triangle compression**    | Neutral consolidation   |
| 4   | EL       | HH       | **Range break up**          | Bullish transition      |
| 5   | EL       | EH       | **Rectangle**               | Balanced range          |
| 6   | EL       | LH       | **Lower-high at flat base** | Range, bearish bias     |
| 7   | LL       | HH       | **V-reversal / spring**     | Bullish reversal        |
| 8   | LL       | EH       | **Undercut then stall**     | Volatile range          |
| 9   | LL       | LH       | **Rally failure**           | Bear trend continuation |

### Exhaustiveness Proof

All variants satisfy these mandatory constraints:

- L₀ < H₁ (first uptrend exists)
- L₂ < H₁ (retracement doesn't exceed peak)
- H₃ > L₂ (second uptrend exists)

L₂ has exactly 3 relationships to L₀ (higher, equal, lower). H₃ has exactly 3 relationships to H₁ (higher, equal, lower). These dimensions are independent — no constraint eliminates any combination. Therefore 3 × 3 = 9 variants, all feasible, none missing.

### Natural Groupings

- **Bullish** (4): HL+HH, EL+HH, HL+EH, LL+HH
- **Neutral** (3): HL+LH, EL+EH, LL+EH
- **Bearish** (2): EL+LH, LL+LH

### Regime Assignments

| Regime              | Variants                   |
| ------------------- | -------------------------- |
| Trend Continuation  | HL+HH (bull), LL+LH (bear) |
| Range Consolidation | HL+LH, EL+EH, LL+EH        |
| Bullish Transition  | EL+HH, HL+EH               |
| Bearish Transition  | EL+LH                      |
| Reversal            | LL+HH                      |

---

## Part 3: 27-Way Extension

Adding **H₃ vs L₀** as a third independent dimension:

- **L₂ vs L₀**: {HL, EL, LL}
- **H₃ vs H₁**: {HH, EH, LH}
- **H₃ vs L₀**: {Above, Equal, Below}

This yields 3×3×3 = **27 sub-variants**. Some are mathematically impossible due to constraints (e.g., HL+LH+H₃<L₀ requires H₃ < L₀ < L₂ < H₃, a contradiction).

Analysts often simplify this third dimension to a binary: "reclaims L₀" vs "fails to reclaim L₀".

---

## The Epsilon Tolerance Band

The tolerance band ε determines what "equal" means. It adapts to volatility and microstructure.

### Core Formula

```