# Earnings Blocker

> Block or filter stock trading signals that fall within an earnings announcement window. Use this skill whenever the user wants to avoid trading a stock too close to its earnings report, filter out signals near earnings, check if a stock has upcoming earnings within N days, or add earnings-aware risk management to a quant scanner. Triggers include: "is AAPL near earnings", "filter stocks near earnings", "block trades during earnings", "earnings calendar check", "skip signals near earnings", "avoid earnings window", "earnings-aware filter", "any signals scheduled too close to earnings", or any request to use earnings dates as a gate for buy/sell decisions.

- Skill: `doertail/earnings-blocker` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add doertail/earnings-blocker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/doertail/earnings-blocker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: doertail (https://skillmd.com/u/doertail)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/doertail/earnings-blocker

---


# Earnings Blocker

Filter stock signals that fall within an earnings announcement window (±N days).
Earnings reports often produce sharp price gaps that invalidate short-term technical signals
like RSI breakdowns or moving-average crosses. Blocking signals near earnings is a common,
low-cost risk management gate in quant systems.

Data source: [yfinance](https://github.com/ranaroussi/yfinance) `Ticker.calendar`.

**Note**: Not financial advice. yfinance data may lag the official issuer calendar.

---

## When to use

- A user is building or running a scanner/screener and wants to exclude stocks with upcoming earnings.
- A user asks whether a specific ticker has earnings within the next few days.
- A user wants to add an earnings-aware safeguard to an existing trading pipeline.
- A user is debugging false signals that turned out to be earnings-related gaps.

## When NOT to use

- The user wants a full earnings analysis (consensus estimates, beat/miss history, analyst sentiment)
  → use the `earnings-preview` style skills instead.
- Index ETFs (SPY, QQQ, etc.) — they have no earnings dates.

---

## Step 1: Ensure yfinance is available

```python
import subprocess, sys
try:
    import yfinance  # noqa: F401
except ImportError:
    subprocess.check_call([sys.executable, "-m", "pip", "install", "-q", "yfinance"])
```

## Step 2: Use the helper

The provided helper (`earnings_blocker.py`) gives two functions:

```python
from earnings_blocker import is_near_earnings, filter_by_earnings

# Single-ticker check
info = is_near_earnings("NVDA", days=2)
# → {"is_near": True, "date": "2026-05-21", "days_until": -1}

# Bulk filter (parallelized, ~5 workers)
candidates = [{"ticker": "AAPL", "close": 200.0},
              {"ticker": "NVDA", "close": 140.0}]
passed, blocked = filter_by_earnings(candidates, days=2)
# `passed` keeps the safe ones; each candidate now has an "earnings" key.
```

### Return shape

| Key | Type | Meaning |
|---|---|---|
| `is_near` | bool | True if the closest earnings date is within ±days |
| `date` | str \| None | Closest earnings date in `YYYY-MM-DD` |
| `days_until` | int \| None | Days from today (negative = past, positive = future) |

When data cannot be retrieved, `is_near=False` is returned (safe default — if uncertain, let the signal pass).

## Step 3: Recommended `days` window

| Window | Use case |
|---|---|
| `days=1` | Tight filter — only block day-before / day-after |
| `days=2` (default) | Balanced — covers the announcement and the immediate reaction day |
| `days=5` | Conservative — wider buffer for pre-earnings drift |
| `days=7+` | Very conservative — may miss too many opportunities |

## Step 4: Respond to the user

If the user asked about a single ticker:

> AAPL's next earnings is scheduled for 2026-07-31 (D+70). It is **not** within the ±2-day window — signal is OK.

If the user is filtering a list:

> Of 12 candidates, 1 was blocked due to earnings:
> - NVDA: 2026-05-21 (D-1)
>
> Remaining 11 passed the earnings gate.

### Caveats to mention
- yfinance can lag the official earnings calendar by hours.
- If the ticker is delisted or new, `calendar` may be empty — treated as PASS.
- Earnings can be re-scheduled; recheck within 24 hours of trading.

---

## Real-world example

This skill was extracted from the [quant-scanner](https://github.com/doertail/quant-scanner) project,
where it acts as filter 6a in a multi-strategy pipeline: between universe scan and news-sentiment
analysis. In one live run (2026-05-22), it correctly blocked Deere & Co. (DE) one day after its
earnings report, preventing a mean-reversion false signal.