/8-k-scanner

name: 8-k-scanner
description: Scan SEC 8-K disclosures across a single ticker or a watchlist using Massive's pre-parsed disclosure taxonomy. Groups the underlying rows by filing (one 8-K carries N tagged Items), ranks by signal bucket (M&A / Restatement / Material agreement / Regulatory / Leadership change / Capital / Earnings / Corporate housekeeping / Other), and surfaces the highest-signal filings at the top with the supporting text quoted. Use when a PM or analyst asks "what material events hit my names this week?" Requires Stocks Basic. Runs on the free tier.

8-k-scanner

You hand over a ticker or a watchlist. The skill pulls every 8-K disclosure filed against those issuers over the lookback window, groups the taxonomy rows into filings (one 8-K = many tagged Items, one accession number), ranks by signal bucket (M&A / Restatement / Material agreement / Regulatory / Leadership change / Capital / Earnings / Corporate housekeeping / Other), and surfaces the high-signal filings first with the supporting text quoted.

This is the "what materially happened this week" read a PM does by skimming SEC filings each morning. It works because Massive already parses and taxonomically classifies every Item in every 8-K into a three-tier taxonomy (primary, secondary, tertiary). No text NLP on our side.

When to invoke

• A PM asks "any material 8-Ks on my watchlist this week?"
• A trader wants a Monday-morning M&A scan across a sector basket
• A credit analyst wants to catch restatements, going-concern

disclosures, or debt-covenant events across a portfolio

• The user says "8-K scan", "material events", "any deals or

leadership changes", "did anyone in my book file an 8-K"

Not for: single-item drill-down on one specific 8-K (use the underlying `/8-K/vX/text` endpoint or read the filing on EDGAR). Not for the full 8-K narrative (this quotes supporting text at ~220 chars per Item).

What you need

• A ticker or watchlist (`--tickers`, required, comma-separated)
• `MASSIVE_API_KEY` exported in the environment
• Stocks Basic plan minimum. The

`/stocks/filings/8-K/vX/disclosures` endpoint is included on every Stocks plan.

Optional:

• `--lookback-days` (default 30): calendar-day window back from today.
• `--categories`: comma-separated primary_category values to filter

to (e.g. `strategic_transactions,leadership_and_governance`).

What you get back

Two output layers from one run.

**Layer 1: canonical JSON** matching [`output-schema.json`](./output-schema.json). Per-filing block includes `accession_number`, `filing_date`, `tickers`, `filing_url`, and every tagged `categories[]` tuple (`primary`, `secondary`, `tertiary`, `supporting_text`). Top level gives `by_bucket` (M&A / Leadership / etc counts), `by_ticker` (per-name filing count with bucket breakdown), and `by_primary_category` (raw category counts).

**Layer 2: rendered note**. Header + by-signal one-liner + filings grouped by signal bucket in priority order, most-recent-first within a bucket. Each filing lists its tagged Items with the supporting text quoted. One-line Take at the end. See [`references/rendering.md`](./references/rendering.md).

How it works

1. **Pull disclosures** for the watchlist via `GET /stocks/filings/8-K/vX/disclosures?tickers.any_of={T1,T2,...}&filing_date.gte={D}&limit=1000&sort=filing_date.desc`. Massive returns one row per (accession, tagged Item) so a single 8-K with three Items produces three rows sharing an `accession_number`. 2. **Group by accession_number.** Union of tagged tuples per filing; deduplicated `(primary, secondary, tertiary)` triples with the supporting text preserved. 3. **Assign a headline signal bucket** based on the first primary category the filing hits from the ranked bucket list. Buckets in descending priority: M&A / Strategic → Restatement / Restructuring → Material agreement → Regulatory / Legal → Leadership change → Capital / Debt → Earnings / Guidance → Corporate housekeeping → Other. 4. **Sort filings** by bucket priority first, then filing date descending within a bucket. The reader sees the highest-signal filings up top and can stop reading once they hit routine items. 5. **Take.** One line summarizing which signal buckets fired.

Taxonomy reference: full primary/secondary/tertiary list at `/stocks/taxonomies/vX/disclosures`. See [`references/methodology.md`](./references/methodology.md) for the signal-bucket ranking.

Foundations used

• [`massive-api-patterns`](../massive-api-patterns) for REST auth,

retry, and pagination on the filings endpoint.

Output mode: note

Narrative note. A watchlist-scale scan produces a small number of filings (typically 5-50 for 30 days on 5-15 tickers); a wide table would lose the supporting-text quotes that let a reader triage the filing without opening EDGAR.

Endpoints used

• `GET /stocks/filings/8-K/vX/disclosures?tickers.any_of={T}&filing_date.gte={D}`

All 8-K disclosure rows for the ticker set in the window. Paginated; one call per page.

Doesn't handle (yet)

• **Full 8-K text.** The skill uses the `disclosures` endpoint

(categorized Item excerpts). Full plain-text 8-K bodies live at `/stocks/filings/8-K/vX/text` and would be a natural companion for a "read the whole filing" flow.

• **Sentiment scoring on 8-K text.** No positive/negative label per

filing. Loughran-McDonald finance dictionary scoring would be a clean PR extension for a `filing-sentiment` skill; queued.

• **Base rate context.** No per-name "typical 8-K cadence." An

activist target that files 3 8-Ks in a week is different from AAPL doing the same. Queued.

• **Cross-reference to price reaction.** A chain with `event-study`

would compute the abnormal-return distribution around each 8-K by category. Queued.

• **Watchlist-of-watchlists.** No group naming or per-group summary

yet. Callers who want to run against 3 sector baskets do 3 runs.

These are clean PR extensions. The ou