---
name: ib-stop-loss
description: Downside stop-loss management for PMCC, naked LEAPS, and stock positions in IB. Computes stop prices, detects alerts, and places conditional combo orders. Dry-run by default. Requires TWS or IB Gateway running locally.
dependencies: ["trading-skills"]
---

# IB Stop-Loss Manager

Analyzes PMCC (diagonal call spread), naked LEAPS, and stock positions in the IB portfolio and manages conditional stop-loss orders.

**Default mode is dry-run** — no orders are placed unless `--execute` is in the request.

## IB Connection

TWS or IB Gateway must be running locally with API enabled:
- **Paper trading** — port 7497
- **Live trading** — port 7496
- **`IB_PORT` env var** — default port when `--port` is omitted (e.g. `IB_PORT=4001` for a Gateway container). Precedence: `--port` flag > `IB_PORT` > built-in default. Set it in the shell or a `.env` file.

**Port fallback:** If the configured port fails, automatically retry on the other port.
If the retry succeeds, save to memory which account type worked (live/paper) and reuse it for all IB skill calls in this and future sessions — until the user explicitly asks for the other account.
If both ports fail, ask the user to verify that TWS or IB Gateway is running with API access enabled.

## Instructions

### Step 1: Run the script

Dry-run (default — no orders placed):
```bash
uv run python .claude/skills/ib-stop-loss/scripts/stop_loss.py
```

Execute (cancel orphan orders + place SL_ conditional orders):
```bash
uv run python .claude/skills/ib-stop-loss/scripts/stop_loss.py --execute
```

Execute forced (basis = current mid price, can lower existing stops):
```bash
uv run python .claude/skills/ib-stop-loss/scripts/stop_loss.py --execute --forced
```

### Step 2: Format the report

Format JSON output as a markdown report with four sections:

#### Section 1: Alert Soon
List symbols in `alert_soon` prominently — these are past the early-warning threshold.

#### Section 2: Existing Conditional Orders
Show `all_conditional_orders.module` (SL_ orders) and `all_conditional_orders.manual` (manually placed).
If `orphan_orders` is non-empty, warn that these were cancelled (execute mode) or need manual cancellation (dry-run).

#### Section 3: Positions
For each entry in `positions`, show a table:

| Field | Value |
|---|---|
| Symbol | NVDA — pmcc (3 contracts) |
| Spot | $219.05 |
| LEAPS | 200C 20270115 · avg cost $44.27 · current $44.23 · basis $44.27 |
| **Stop price** | $22.14 (40% stop) → action: place_new |
| LEAPS loss | 0.1% |
| Shorts | 235C 20260515 · received $0.61 · current $0.56 · 9.5% decayed |

Show `preserve_existing` when a more-protective stop already exists.
Show `overwrite` (red) when `forced=true` lowers an existing stop.

#### Section 4: Alerts
Group alerts by symbol. Types:

| Type | Meaning |
|---|---|
| `leaps_early_warning` | LEAPS down ≥ stop_pct/2% from basis |
| `short_premium_decay` | 90%+ of short premium captured — close or roll |
| `short_near_strike` | Spot at/above or within X% of short strike |

### Step 3: Report to user

- State dry-run vs execute mode prominently.
- Lead with `alert_soon` symbols.
- For each position: show stop action and current loss %.
- Show alerts section last.

## Arguments

| Flag | Default | Description |
|------|---------|-------------|
| `--port` | 7497 | IB Gateway/TWS port |
| `--account` | all | Specific account ID |
| `--symbols` | all | Analyze only these symbols |
| `--legs` | none | Specific option legs: `SYMBOL:STRIKE[C\|P]:EXPIRY` (e.g. `IBKR:70C:20270115 IBKR:100C:20260918`). Right defaults to `C`. Takes precedence over `--symbols`. Use when multiple PMCC/LEAPS coexist on the same symbol and only one pairing should get a stop. |
| `--stop-pct` | 40 | Loss % that triggers exit |
| `--short-near-strike-pct` | 5 | Near-strike alert threshold |
| `--price-mode` | mid | Option pricing: `mid` or `last` |
| `--execute` | off | Cancel orphans + place SL_ orders |
| `--forced` | off | Use current mid as basis (requires `--execute`) |

## JSON Output Structure

```json
{
  "generated_at": "2026-05-12 10:00 ET",
  "dry_run": true,
  "forced": false,
  "stop_pct": 40.0,
  "short_near_strike_pct": 5.0,
  "accounts": ["U1234567"],
  "symbols_filter": null,
  "all_conditional_orders": {"module": [], "manual": []},
  "orphan_orders": [],
  "alert_soon": ["PFE"],
  "positions": [
    {
      "symbol": "NVDA",
      "type": "pmcc",
      "account": "U1234567",
      "qty": 3,
      "underlying_price": 219.05,
      "leaps": {
        "strike": 200.0, "expiry": "20270115", "avg_cost": 44.27,
        "current_price": 44.23, "stop_basis": 44.27,
        "stop_price": 22.14, "loss_pct": 0.1
      },
      "shorts": [
        {"strike": 235.0, "expiry": "20260515",
         "premium_received": 0.61, "current_price": 0.56, "decay_pct": 9.5}
      ],
      "stop_loss": {"stop_price": 22.14, "action": "place_new", "existing_stop": null},
      "alert_soon": false,
      "alerts": []
    },
    {
      "symbol": "AAPL",
      "type": "stock",
      "account": "U1234567",
      "qty": 100,
      "underlying_price": 189.50,
      "stock": {
        "avg_cost": 175.00, "stop_basis": 189.50,
        "stop_price": 94.75, "loss_pct": 0.0
      },
      "stop_loss": {"stop_price": 94.75, "action": "place_new", "existing_stop": null},
      "alert_soon": false,
      "alerts": []
    }
  ]
}
```

## Key Fields

- `alert_soon` — top-level list of symbols where loss ≥ stop_pct/2%
- `position.type` — `pmcc` | `leaps` | `stock`
- `stop_loss.action` — `place_new` | `preserve_existing` | `overwrite`
- `stop_loss.existing_stop` — price of the existing SL_FALL_ order if present
- For PMCC: stop order is a single combo (BAG) order closing LEAPS + all shorts atomically
- In execute mode: orphan SL_ orders (no matching position) are cancelled first

## Order Identification

- `SL_FALL_{SYM}_{STRIKE}_{EXPIRY}` — options (PMCC or naked LEAPS)
- `SL_FALL_{SYM}_STK` — stock positions

## Architecture

All analytics live in `src/trading_skills/broker/stop_loss.py`:

**Analytics (no IBKR — testable in isolation):**
- `calc_stop_basis` — max(mid, avg_cost) normally; current_mid if forced
- `calc_stop_price` — basis × (1 - stop_pct/100)
- `calc_short_premium_decay_pct` — % of short premium captured
- `identify_positions` — classify normalized positions into pmcc/leaps/stock
- `build_position_analysis` — full per-position output dict
- `detect_orphan_orders` — SL_FALL_ orders for gone positions
- `summarize_all_conditional_orders` — splits IB orders into module vs manual

**Data layer (IBKR):**
- `get_stop_loss_data` — main entry point
- `_cancel_orphan_orders` — cancel stale SL_ orders
- `_place_combo_stop_order` — BAG order for PMCC (atomic LEAPS + shorts)
- `_place_simple_stop_order` — single order for naked LEAPS or stock
- `_execute_position_stop` — dispatch per position type