/guidance-tracker

name: guidance-tracker
description: Track corporate guidance history for a ticker via Benzinga Corporate Guidance. Classifies each event as raised / lowered / reaffirmed / initiation against the prior figure using the endpoint's built-in previous_min/max fields, groups by fiscal period, and reports the trajectory. Answers "how has management's own view of the year evolved?" Requires Stocks Basic + Benzinga Corporate Guidance add-on (approx $99/mo). Emits a clear NOT_AUTHORIZED tier caveat when the entitlement is missing.

guidance-tracker

You hand over a ticker. The skill pulls every corporate guidance event Benzinga has on record over the lookback window, compares each event to the prior figure for the same fiscal period, and labels it as a raise, cut, reaffirmation, or initiation. Groups results by fiscal period so the reader can see "management guided FY26 EPS at $5.20 in January, raised to $5.60 in April, reaffirmed in June."

When to invoke

• A PM asks "has NVDA management been raising or cutting guidance

this cycle?"

• A fundamental analyst wants a heads-up on companies that just

lowered guidance

• Screening a watchlist for consistent raisers as a bullish tilt
• The user says "guidance history", "guidance trajectory",

"management raise", "corporate guidance track record"

Not for: consensus vs guided (that's earnings-drilldown territory). Not for actual vs guided (also earnings-drilldown once the print lands).

What you need

• A ticker (`--ticker`, required)
• `MASSIVE_API_KEY` exported
• Stocks Basic plan minimum PLUS **Benzinga Corporate Guidance

add-on** (approx $99/mo). Without the add-on the endpoint returns NOT_AUTHORIZED; the skill emits a clean tier caveat and no events.

Optional:

• `--lookback-days` (default 540): calendar-day window back from today.

What you get back

Two output layers from one run.

**Layer 1: canonical JSON** matching [`output-schema.json`](./output-schema.json). Per-event: `date`, `fiscal_year`, `fiscal_period`, `label` (`raised`/`lowered`/`reaffirmed`/`initiation`/`mixed`/`unclear`), EPS midpoint current and prior, revenue midpoint current and prior, per-metric direction and delta_pct. Top-level `by_period` group of events per fiscal period plus a trajectory array showing the sequence of labels for that period.

**Layer 2: rendered note**. Header with counts by label, timeline sorted most-recent-first with EPS and revenue on the same line as the raise/cut tag, one-line Take. See [`references/rendering.md`](./references/rendering.md).

How it works

1. **Pull guidance events** via `GET /benzinga/v1/guidance?ticker={T}&date.gte={D}&limit=1000&sort=date.desc`. 2. **Classify per event** using the endpoint's built-in `previous_` fields. EPS midpoint = `estimated_eps_guidance` (fallback to `(min+max)/2`). Prior midpoint = `(previous_min + previous_max)/2`. Delta_pct = `(cur - prior) / |prior|`. Below 0.5% is `reaffirmed`; above is `raised` or `lowered`; missing prior is `initiation`. 3. **Combine EPS and revenue labels** into a headline: `raised`+`raised` = raised; `raised`+`lowered` = mixed; and so on. 4. **Group by fiscal_period.** Each period gets its trajectory (the ordered sequence of labels), so "FY26 Q4: initiated → raised → raised → reaffirmed" is one legible line. 5. **Take** summarizes the overall balance of raises vs cuts and surfaces the most-recent event's label.

Foundations used

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

retry, pagination.

Output mode: note

Narrative note with a chronological timeline. Guidance events are few per name (5-30 in 18 months typically); a wide table would lose the fiscal-period grouping that makes the timeline legible.

Endpoints used

• `GET /benzinga/v1/guidance?ticker={T}&date.gte={D}` — every

guidance event Benzinga has on record for the ticker in the window.

Doesn't handle (yet)

• **Chain to actual results.** No comparison of guided vs delivered.

`earnings-drilldown` covers actual-vs-consensus; a workflow composite could add actual-vs-guided.

• **Cross-ticker sector scan.** No "list every consumer name that

cut guidance this quarter." Queued as a composite.

• **Analyst reaction overlay.** No pairing with rating changes /

price target moves. Would compose cleanly with a future `analyst-tracker`.

• **Detection of guidance-plan vs one-off.** No flag for

"management gives structural annual guidance" vs "gave a one-off during a special-situation update."

These are clean PR extensions. The output schema is forward-compatible.