Skip to content

Specialism naming consistency: inventory-lists ↔ property_list, sales-streaming-tv ↔ channels:ctv, and friends #2287

Description

@bokelley

Problem

Specialism IDs use kebab-case and often don't match the tool families or enum values they imply. A few cases a fresh builder hits:

  1. `inventory-lists` specialism → `property_list` tools. The specialism is named for the concept ("lists of inventory") but every tool says "property list" (`create_property_list`, `validate_property_delivery`). Flagged by the fresh builder as real onboarding friction.

  2. `sales-streaming-tv` specialism → `channels: ['ctv']`. The specialism title is "Streaming TV" but the `MediaChannel` enum uses `ctv`. Same for specialism id vs channel id.

  3. Specialism id vs storyboard category id. `sales-broadcast-tv` (kebab) vs `media_buy_broadcast_seller` (snake) — same thing, three different names (plus the yaml title). Readers must learn the mapping by induction.

  4. `delivery_type: 'non_guaranteed'` (underscore) vs prose "non-guaranteed" (hyphen). Every builder fumbled this at least once.

  5. `signal_type: 'custom'` — in the enum but never defined in the spec; builders don't know when to use it vs `owned`.

Requested resolution

  • Add a canonical "terminology" section to `docs/` (or the llms.txt preamble) that explains: specialism ID kebab-case, storyboard category id snake_case, the yaml title is prose — and shows the mapping.
  • Normalize one of the inventory-lists ↔ property-list naming pairs. Either rename the specialism `property-lists` (kebab) or rename the tool family `inventory_list_*`. Rename inventory-lists is my recommendation — cheaper.
  • Document when `signal_type: 'custom'` applies.
  • Add to each specialism's `index.json` entry the set of tool families it uses (e.g. for `audience-sync`: `["sync_audiences", "list_accounts"]`) so discoverability doesn't require reading the whole yaml.

Context

Discovered via a 21-specialism fresh-builder test; every report flagged at least one terminology mismatch. Internal reports in `@adcp/client` `.context/specialism-tests/`.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions