# Institutional Hotspot Rules

Date: 2026-05-21

Hierarchy entry point: `docs/hotspot/README.md`

## Purpose

Translate 120-day Taiwanese institutional-flow behavior into testable hotspot
scanner features. These rules are hypotheses for ranking and validation; they
are not production trading advice.

## Data Contract

Each rule is evaluated as of a completed trading day.

Required input columns:

- `foreign_net`
- `trust_net`
- `dealer_net`
- `institutional_net`
- `close`
- `ma10`
- `ma20`
- `volume`
- `turnover`

Rolling windows:

```text
short flow = 5 trading days
medium flow = 20 trading days
long flow = 60 trading days
institutional memory = 120 trading days
```

Missing flow data should produce neutral features and an explicit skipped or
partial-data reason in validation output.

## Accumulation Rules

### 120-Day Combined Accumulation

```text
flow_120d_accumulation =
  institutional_net_120d > 0
  and institutional_net_120d_percentile >= 70
```

Interpretation:

- Long-window institutional demand exists.
- Use as a rank boost only when liquidity coverage is acceptable.

### 20-Day Acceleration

```text
flow_20d_acceleration =
  institutional_net_20d > 0
  and institutional_net_20d / 20 > institutional_net_120d / 120
```

Interpretation:

- Recent buying is stronger than the long-window pace.
- Use with price/volume confirmation to avoid stale accumulation.

## Institution-Specific Support Rules

### Investment Trust 10MA Support

```text
trust_10ma_support =
  trust_net_5d > 0
  and trust_net_20d > 0
  and close >= ma10
```

Risk variant:

```text
trust_10ma_break =
  trust_net_20d > 0
  and close < ma10
```

Interpretation:

- Trust buying above 10MA is supportive.
- A 10MA break after trust buying is a hotspot penalty, not a short signal by
  itself.

### Foreign 20MA Support

```text
foreign_20ma_support =
  foreign_net_20d > 0
  and close >= ma20
```

Risk variant:

```text
foreign_20ma_break =
  foreign_net_20d > 0
  and close < ma20
```

Interpretation:

- Foreign accumulation above 20MA is supportive.
- A 20MA break after foreign accumulation should lower rank confidence.

### Dealer Confirmation

```text
dealer_confirmation =
  dealer_net_5d > 0
  and (foreign_net_5d > 0 or trust_net_5d > 0)
```

Interpretation:

- Dealer buying confirms another institutional buyer.
- Dealer-only buying should be weaker than foreign or trust confirmation until
  validation proves otherwise.

## Divergence And Risk Rules

### Flow Divergence Risk

```text
flow_divergence_risk =
  close_20d_return > 0
  and institutional_net_20d <= 0
```

### Distribution Risk

```text
flow_distribution_risk =
  close >= close_60d_high * 0.95
  and institutional_net_20d < institutional_net_60d / 3
```

Interpretation:

- Price near highs with fading institutional support is a rank penalty.
- Keep this separate from bearish prediction labels.

### Volume-Spike Fade Breakdown

```text
volume_spike_fade_breakdown =
  volume[t-3] >= 2.0 * average_volume[t-23:t-4]
  and volume[t-2] <= 0.75 * volume[t-3]
  and high[t-2] <= high[t-3]
  and close[t-1] < open[t-1]
  and close[t] < open[t]
  and close[t] < ma20[t]
```

Interpretation:

- The earlier volume spike did not attract follow-through buying.
- Two black candles plus MA20 break means the hotspot may have shifted away.
- Use as a hotspot rank penalty and display risk flag, not a hard sell rule.

## Hotspot Score Composition

Initial experimental score:

```text
hotspot_score =
  volume_turnover_rank
  + flow_120d_accumulation
  + flow_20d_acceleration
  + trust_10ma_support
  + foreign_20ma_support
  + dealer_confirmation
  - flow_divergence_risk
  - flow_distribution_risk
  - volume_spike_fade_breakdown
```

The exact weights must be learned or grid-searched in the harness. Do not
hard-code permanent production weights without validation.

## Validation Requirements

- Use the no-lookahead split from `docs/full_market_hotspot_harness.md`.
- Evaluate top 20, top 30, and top 50 hotspot lists.
- Compare against the current local hot-stock ranking baseline.
- Record per-rule ablations so a single noisy flow rule can be removed without
  discarding the whole scanner.
- Promotion requires the gates in `docs/full_market_hotspot_harness.md`.