hoopscout-v2/docs/adr/0005-scouting-search-domain.md

ADR-0005: Scouting Search Domain Baseline

Status

Accepted

Context

HoopScout v2 is moving from technical foundation decisions to product-domain decisions required before model, filter, and UI implementation. The next implementation prompts need a stable and explicit scouting search vocabulary so we do not conflate objective statistics with internal scouting interpretation.

The product intent is a scouting-first player search engine where users combine multiple dimensions to discover players. This is not a generic basketball encyclopedia.

Decision

1. Search purpose

The search system is defined as a player scouting search engine. Search dimensions are selected to support scouting workflows and shortlist creation, not comprehensive historical/statistical browsing.

2. Domain vocabulary and separation of concerns

Search dimensions are separated into distinct layers that must not be conflated:

• Position: standard on-court category (PG, SG, SF, PF, C).
• Role: tactical/scouting classification (for example playmaker, 3-and-D, point forward, rim protector, 6th man).
• Specialty: scouting tag layer (for example ball handling, off ball, defense, intangibles, clutch, post, dunk).

Position is a categorical descriptor, role is tactical interpretation, and specialty is a flexible tagging layer. Future implementation must preserve this separation in model semantics, filtering semantics, and UI wording.

3. Data classification by search dimension

The following classification defines ownership and data realism.

Dimension	Classification	MVP handling
Position (PG/SG/SF/PF/C)	Hybrid: often source-derived, may need normalization; can be manually overridden when source is inconsistent	In MVP; filterable
Role (listed tactical roles)	App-defined/internal taxonomy; assigned via internal scouting judgment; may be inferred from data but not treated as source-native fact	Deferred as mandatory filter; optional/manual enrichment in MVP
Specialty tags	App-defined/internal taxonomy; manually curated and optionally inference-assisted; not source-native	Deferred as mandatory filter; optional/manual enrichment in MVP
Age	Derived from source date-of-birth and reference date	In MVP; filterable
Height	Source-derived objective attribute; normalized units required	In MVP; filterable
Weight	Source-derived objective attribute; normalized units required	In MVP; filterable
Wingspan	Optional source-derived or manually curated enrichment; sparse in public sources	Not required in MVP; optional if present
Points per game	Source-derived objective per-game metric	In MVP; filterable
Assists per game	Source-derived objective per-game metric	In MVP; filterable
Steals per game	Source-derived objective per-game metric	In MVP; filterable
Turnovers per game	Source-derived objective per-game metric	In MVP; filterable
Blocks per game	Source-derived objective per-game metric	In MVP; filterable
eFG%	Source-derived if provided, otherwise calculated from source box score totals (derived but objective)	In MVP if available/computable
TS%	Source-derived if provided, otherwise calculated from source totals (derived but objective)	In MVP if available/computable
Plus/minus	Optional source-derived metric with context variance across competitions/sources	Deferred from MVP baseline; include only where source quality is acceptable
Offensive rating	Optional source-derived metric; not universally available/consistent	Deferred from MVP baseline
Defensive rating	Optional source-derived metric; not universally available/consistent	Deferred from MVP baseline

4. MVP search scope decision

MVP search filters include:

• position
• per-game metrics: points, assists, steals, turnovers, blocks
• objective personal/physical attributes with practical availability: age, height, weight
• advanced percentages when available or reliably computable: eFG%, TS%

MVP does not require role, specialty, wingspan, plus/minus, offensive rating, or defensive rating as baseline filters.

These deferred dimensions are allowed as optional enrichment fields in MVP data ingestion/storage if available, but they are not required for a player to be searchable.

5. Data realism decisions for risk-prone dimensions

• Role: public source coverage is inconsistent and mostly interpretive; treat as internal/manual scouting classification in MVP.
• Specialty: public source coverage is not standardized; treat as internal/manual tagging in MVP.
• Wingspan: public coverage is sparse and uneven across leagues; treat as optional enrichment, not a required MVP field.

6. Flexibility for future taxonomy growth

Role and specialty taxonomies are repository-owned domain vocabularies. They must be extensible so new role labels and specialty tags can be added without changing the conceptual model.

Future implementation should assume:

• position remains a bounded standard set;
• role remains an app-defined tactical taxonomy that can expand;
• specialty remains an app-defined tag taxonomy that can expand.

7. Implementation guidance for future prompts

Future model/filter/UI prompts must assume:

• Search filters are split by semantic layer: position, role, specialty, objective metrics, physical characteristics.
• Position filters operate on normalized categorical values.
• Role and specialty are internal taxonomy-owned dimensions and may be absent for many players in early phases.
• Objective metrics and physical fields remain source-driven (or objectively derived from source stats) and should be treated differently from scouting classifications.
• Optional dimensions must not block ingestion or search eligibility when missing.
• UI wording should avoid presenting role/specialty as objective source facts.

Alternatives considered

A. Treat role and specialty as source-native fields in MVP

Rejected. This overstates source objectivity and creates data quality risk because these are primarily scouting interpretations.

B. Require all listed dimensions in MVP filters

Rejected. This increases delivery risk and couples MVP to low-availability fields (especially wingspan and certain advanced metrics).

C. Ignore role/specialty until much later

Rejected. Even if deferred as mandatory filters, role/specialty must be conceptually defined now to avoid model ambiguity and rework.

Trade-offs

• Pros: clear semantic boundaries, realistic MVP scope, lower ingestion risk, explicit taxonomy ownership.
• Cons: initial MVP filter set is narrower than full scouting ambition, and some high-value scouting dimensions are manual/optional at first.

Consequences

• Near-term implementation can proceed with objective, reliably available filters first.
• Role/specialty workflows will require internal curation processes and possibly reviewer/admin UX later.
• Data pipelines must support missing optional fields without breaking search.
• Future ADRs can refine role/specialty governance and metric computation standards without replacing this baseline separation.

Follow-up decisions needed

1. Role taxonomy governance: who can define, merge, rename, or deprecate roles.
2. Specialty taxonomy governance: naming rules, hierarchy policy (if any), and duplicate-tag handling.
3. Normalization standards for height/weight units and age reference-date semantics.
4. Metric computation and rounding policy for derived advanced stats (eFG%, TS%).
5. Source quality policy for optional advanced metrics (plus/minus, offensive/defensive rating).
6. Curation workflow for manual scouting classifications and auditability requirements.