---
title: Disambiguate the opportunity column vocabulary in the player from-plays registry
type: task
status: planned
description: >-
  The word opportunity names two different play populations in the player from-plays registry: the
  count column credits three roles while the share and weighted columns credit two, so a quarterback
  shows a large count against a near-zero share with nothing warning the reader. A naming collision,
  not a value defect; needs an operator naming ruling.
base_uri: user:task/league/data-views/disambiguate-opportunity-column-vocabulary.md
created_at: '2026-09-11T18:02:42.869Z'
entity_id: 71ec21c1-1d1b-4a59-b128-bd46d3e0aeae
owner_identity_uri: █████████████████████████
priority: Medium
public_read: true
relations:
  - relates [[█████████████████████-██████████-███████████-███-████████-█████████████]]
  - relates [[user:task/league/data-views/pair-player-from-plays-rate-populations.md]]
tags:
  - user:tag/league-xo-football.md
updated_at: '2026-09-11T18:02:52.309Z'
visibility_analyzed_at: '2026-11-05T23:48:47.939Z'
---

## Why

The word "opportunity" names two different play populations in the player from-plays column registry, and a reader comparing columns across the pair gets two vocabularies under one word with nothing in the UI to warn them.

Verified in `libs-server/data-views-column-definitions/player-stats-from-plays-column-definitions.mjs` at league `f19c74a560`-era HEAD:

- `player_opportunities_from_plays` (line 1048) credits **three** roles — `ball_carrier_pid`, `target_pid`, `passer_pid` — with the passer excluded on sacks, since a sack is not a pass attempt.
- `player_opportunity_share_from_plays` (line 1133) credits **two** roles — `ball_carrier_pid` and `target_pid` — and measures a share of team opportunities defined the same two-role way.
- `player_weighted_opportunity_from_plays` weights only those same two roles.

## What this is and is not

This is a **naming collision, not a value defect.** The share and weighted columns are correct for their own purpose: opportunity share is a carries-plus-targets concept by construction, and folding dropbacks into it would change what it measures. The count column is likewise correct to credit the passer. Each column is right; the shared word is what misleads.

The failure it produces: a quarterback shows a large opportunity **count** and a near-zero opportunity **share**, and nothing tells the reader those two numbers were computed over different populations.

## Scope

Decide the vocabulary and apply it. The open question is which of three shapes to take, and it needs an operator naming ruling before any code moves:

- Rename the three-role count so the word "opportunity" means carries-plus-targets everywhere.
- Rename the two-role pair so the word means all-credited-roles everywhere.
- Keep both names and carry the distinction in the column descriptions and the output label, changing no populations.

Out of scope: changing any column's population. This task does not alter what any of the three columns computes unless the ruling explicitly requires it.

## Plan

- [ ] **Establish the full blast radius.** Enumerate every column in the from-plays registry whose name carries "opportunity", plus every saved view and benchmark corpus entry that references one, so the rename cost is known before the naming ruling rather than after.
- [ ] **Put the three naming shapes to the operator** with the blast-radius numbers attached, as one ask.
- [ ] **Apply the ruling.** If a rename is chosen, follow the established rename discipline — saved-view migration, `data-views-saved-view-migration.mjs`, and the benchmark corpus files under `test/data-view-benchmark/`, which are a known sweep target.
- [ ] **Pin the distinction in a spec** so the two populations cannot silently converge or diverge again.

## Provenance

Surfaced by the `player_opportunity` attribution fix in `████████████████████████████████████████` and explicitly left unresolved there as outside its fence. Filed by the rate-denominator orchestration umbrella so the finding outlives the coordination task that was carrying it.