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. 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.

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 for the signal-bucket ranking.

Foundations used

• 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 output schema is forward-compatible.