# Ib Find Short Roll

> Ib Find Short Roll is an Agent Skill for apps & automation published in the staskh/trading_skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Find roll options for existing short positions OR find best covered call/put to open against long stock. Use when user asks about rolling shorts, finding roll candidates, writing covered calls, or managing option positions. Requires TWS or IB Gateway running locally.

- Skill name: `ib-find-short-roll`
- Category: [Apps & Automation](https://www.openparable.com/skill/apps-automation/1)
- Source: https://github.com/staskh/trading_skills/blob/HEAD/.claude/skills/ib-find-short-roll/SKILL.md
- Repository: staskh/trading_skills (289 GitHub stars when collected)

## SKILL.md

# IB Find Short Roll

Analyze roll options for short positions or find best short options to open against long stock using real-time data from Interactive Brokers.

## IB Connection

TWS or IB Gateway must be running locally with API enabled:
- **Paper trading** — port 7497
- **Live trading** — port 7496

**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: Gather Data

> **Note:** If `uv` is not installed or `pyproject.toml` is not found, replace `uv run python` with `python` in all commands below.

```bash
uv run python scripts/roll.py SYMBOL [--strike STRIKE] [--expiry YYYYMMDD] [--right C|P] [--port PORT] [--account ACCOUNT] [--iv-multiplier N]
```

The script returns JSON to stdout with all position and candidate data.

### Step 2: Format Report

Read `templates/markdown-template.md` for formatting instructions. Generate a markdown report from the JSON data and save to `sandbox/`.

### Step 3: Report Results

Present key findings to the user: recommended position, credit/debit, and the saved report path.

## Behavior

1. **If short option position exists** (`mode: "roll"`): Analyzes roll candidates to different expirations/strikes
2. **If long option position exists** (`mode: "spread"`): Finds best short call/put to create a vertical spread
3. **If long stock exists** (`mode: "new_short"`): Finds best covered call (or protective put) to open
4. **If none of the above**: Returns error (use --strike/--expiry to specify manually)

## Arguments

- `SYMBOL` - Ticker symbol (e.g., GOOG, AAPL, TSLA)
- `--strike` - Current short strike price (optional, auto-detects from portfolio)
- `--expiry` - Current short expiration in YYYYMMDD format (optional, auto-detects)
- `--right` - Option type: C for call, P for put (default: C)
- `--port` - IB port (default: 7497 for paper trading)
- `--account` - Specific account ID (optional)
- `--iv-multiplier` - Expected-move multiplier for strike band width (default: 2.0); increase for high-IV names to surface wider roll candidates

## JSON Output

The script outputs JSON with `mode` field indicating the analysis type:

### Common Fields
- `success` - Boolean
- `generated` - Timestamp
- `mode` - "roll", "spread", or "new_short"
- `symbol` - Ticker
- `underlying_price` - Current stock price
- `earnings_date` - Next earnings date or null
- `expirations_analyzed` - List of expiry dates checked

### Mode-specific Fields
- **roll**: `current_position` (includes `iv` and `delta` from IB greeks), `buy_to_close`, `roll_candidates` (dict of expiry -> candidates), `iv_multiplier`
- **spread**: `long_option`, `right`, `candidates_by_expiry`
- **new_short**: `long_position`, `right`, `candidates_by_expiry`, `iv_multiplier`

### Strike Band Logic (roll and new_short modes)
The strike search window is IV-aware: `half_band = iv_multiplier × ATM_IV × spot × √(T/365)` where T is the DTE of the nearest roll expiry. For roll mode, ATM IV comes from IB model greeks on the current position's quote; if unavailable, it is estimated from the option mid-price using the Brenner-Subrahmanyam approximation. For new_short mode, a conservative default IV of 30% is used. This makes the band automatically wider for high-IV underlyings without requiring a manual override.

## Example Usage

```bash
# Auto-detect GOOG position (short option, long option, or long stock)
uv run python scripts/roll.py GOOG --port 7497

# Specify exact short position to roll
uv run python scripts/roll.py GOOG --strike 350 --expiry 20260206 --right C

# Find short call to sell against long call (vertical spread)
uv run python scripts/roll.py AUR --right C

# Find covered put for long stock
uv run python scripts/roll.py TSLA --right P
```

## Dependencies

- `ib-async`
- `yfinance`


## Timezone

All timestamps and time-based calculations must use the `America/New_York` timezone. All JSON output must include `generated_at` (NY time string) and `data_delay` fields.

---

Source: https://www.openparable.com/skill/apps-automation/ib-find-short-roll (OpenParable). Cite the canonical URL above.
