/single-name-vs-sector

name: single-name-vs-sector
description: Split one name's relative strength into two clean legs, name vs its sector ETF and sector vs benchmark, so you can tell whether the name is strong because its sector is strong or because it is pulling away from its own sector. Maps the ticker to its SPDR sector ETF (XLK, XLF, XLE, XLV, XLI, XLY, XLP, XLU, XLB, XLRE, XLC) with a --sector override for any name. Computes name-vs-sector, sector-vs-benchmark, and name-vs-benchmark RS in basis points across 5/20/60/120-day windows, a divergence score, and a take that classifies the name as leading its sector, lagging its sector, or diverging. Use when a single name looks strong or weak vs SPY and you need to know if it is name-specific or sector-driven. Requires Stocks Starter (Free Basic works, only three series per run).

single-name-vs-sector

relative-strength tells you a name is a stable laggard versus SPY. It does not tell you why. SOFI reading -4100bp versus SPY over 120 days looks like a broken name until you notice its sector XLF was a leader (+377bp over 20d). The weakness was name-specific, not a financials problem. Reading two separate relative-strength runs and doing the subtraction in your head is exactly the kind of eyeballing this tool removes.

You hand over one ticker. The skill maps it to its SPDR sector ETF, then measures the name against its sector and the sector against the benchmark over several windows. The take says whether the name is leading its sector, lagging its sector, or diverging (moving opposite to its sector), with the magnitude and the windows driving it.

This is not alpha. It is descriptive math that separates a name-specific move from a sector move, so an LLM does not have to guess whether "SOFI is weak" means SOFI or means financials.

When to invoke

• A single name looks strong or weak versus SPY and the question is

whether that is the name or its whole sector

• Following up a `relative-strength` run where one name stands out and you

want to attribute the move

• The user says "is this the name or the sector", "is NVDA leading or is

it just XLK", "why is SOFI lagging", "is the weakness name-specific", "how is this name doing versus its peers"

For ranking a whole watchlist versus one benchmark, use [`relative-strength`](../relative-strength). This skill is the focused single-name attribution; relative-strength is the watchlist ranker. relative-strength with `--include-sectors` surfaces sector context alongside the names; this skill isolates one name against its own sector and states the divergence explicitly.

What you need

• A ticker (`--ticker`, required)
• `MASSIVE_API_KEY` exported in the environment
• Any stocks tier (three US-listed series per run: name, sector ETF,

benchmark)

Optional:

• `--benchmark` (default `SPY`): the sector-vs-market leg denominator
• `--windows` (default `5,20,60,120`): RS lookback windows in trading days
• `--sector` (e.g. `XLK`): sector ETF override. Required when the ticker

is not in the built-in map; also lets you re-map a name to a different sector proxy.

• `--sleep`: seconds between calls. Rarely needed for three series; use

`--sleep 13` when batching many names on Free Basic.

What you get back

Two output layers from one run.

**Layer 1: canonical JSON** matching [`output-schema.json`](./output-schema.json). Per-window `name_vs_sector_bps`, `sector_vs_benchmark_bps`, and `name_vs_benchmark_bps` (all basis points), the per-leg five-bucket trend labels, a `divergence` block (signed score, unsigned composite, sector and name averages), a `classification`, and a composed `take`. UIs and downstream agents consume this.

**Layer 2: rendered note**: a three-row RS table (name vs sector, sector vs benchmark, name vs benchmark), then the divergence block, then the take. See [`references/rendering.md`](./references/rendering.md).

How it works

1. **Map the ticker to its sector ETF** from the built-in map of large US names, or from `--sector`. Unknown ticker with no override is a clear error telling the user to pass `--sector`. 2. **Pull daily aggregates** for the name, the sector ETF, and the benchmark over `max(windows) * 1.6 + 14` calendar days, via `/v2/aggs/ticker/{T}/range/1/day/{from}/{to}?adjusted=true`. 3. **Compute three RS legs** per window in basis points: `name_vs_sector = (name_return - sector_return) * 10_000`, `sector_vs_benchmark = (sector_return - spy_return) * 10_000`, `name_vs_benchmark = (name_return - spy_return) * 10_000`. Each leg also gets a five-bucket trend label (the relative-strength scheme). 4. **Score the divergence**: the name-vs-sector RS averaged across windows (signed) is the divergence score; the mean of its absolute values is the composite magnitude. 5. **Classify and compose the take**: `diverging` when the name-vs-sector move and the sector-vs-benchmark move point opposite ways; otherwise the sign of the divergence score (`leading its sector` / `lagging its sector`). The map, the score, and the rule live in [`references/methodology.md`](./references/methodology.md).

Foundations used

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

rate-limit handling, and the `/v2/aggs` daily endpoint conventions.

Output mode: note

The deliverable is a short attribution read, not a wide sortable table. One name, three RS legs, a divergence score, and a one-sentence take: a note is the right canvas. For the many-names table, use relative-strength.

Endpoints used

• `GET /v2/aggs/ticker/{ticker}/range/1/day/{from}/{to}?adjusted=true`

Daily closes per series. Three calls per run (name, sector ETF, benchmark).

Doesn't handle (yet)

• **Custom peer baskets.** The sector ETF is a cap-weighted proxy for the

peer group, not a hand-picked peer set. A name can read as diverging from its sector when it is really diverging from the ETF's largest holdings. Per-name custom peer baskets are queued. -