# Discover Dynamic Use Cases

## Scope

This skill is the **per-layer specification** for dynamic use-case generation. The orchestration loop (filter, validate, write to disk) is owned by the **`use-case-discoverer`** sub-agent that loads this skill.

| Layer | What it adds beyond static layers | Output path |
|---|---|---|
| 3 — category dynamic | Provider-specific refinements of Layer 2 generic use cases | `.connector-dev/<provider>/research/use_cases/dynamic_category.yaml` |
| 4 — provider dynamic | Use cases derived from the actual API surface, not in any static or dynamic catalog yet | `.connector-dev/<provider>/research/use_cases/dynamic_provider.yaml` |

## Schema (declaration only — no API list)

Each generated use case follows this exact YAML shape:

```yaml
- id: <snake_case>                 # unique within the file
  name: <human readable>           # short label
  description: <one sentence>      # what it enables
  mapping_hints:                   # required, used by classify_priority.js
    action_pattern: <regex>
    path_pattern: <regex>
    method_pattern: <regex>
  # Layer 3 additionally has:
  parent_use_case: <id from Layer 2>     # optional — only if this refines a generic use case
  rationale: <one-sentence why this is provider-specific>
  # Layer 4 additionally has:
  api_signal: <docs URL or path pattern that triggered this>
```

### ⚠️ Do NOT include `example_apis`

Static catalog files (Layer 1 + Layer 2) use `example_apis` as illustrative documentation for human readers. **Dynamic files (Layer 3 + Layer 4) MUST NOT include this field.** The actual mapping between use cases and APIs is:

1. **Defined** by `mapping_hints` (regex patterns that `classify_priority.js` evaluates against each API)
2. **Emitted** to `metadata/use_cases.yaml` during Phase 5B — that file is the authoritative `use_case_id → action_ids` mapping
3. **Never duplicated** in the dynamic catalog file itself — the LLM populating these YAMLs sees a real API list and would otherwise be tempted to hand-curate the mapping, which then competes with the authoritative one in metadata

Both `write_use_cases.js` and `verify_dynamic_use_cases.js` will REJECT a dynamic file that contains `example_apis` to enforce this rule.

## Layer 3 generation — provider-category refinements

**Goal:** capture use cases that are specific to *this* provider within its category but go beyond what the generic Layer 2 catalog covers.

### When to add a Layer 3 use case

Add one when:
- The provider has a feature its category peers don't typically have (e.g. Gmail's Client-Side Encryption — emails support it, but most email providers don't expose CSE APIs)
- The provider has a domain-specific terminology / workflow that doesn't match generic Layer 2 vocabulary (e.g. HubSpot's "deal pipelines" vs Salesforce's "opportunity stages" — both exist generically, but each has unique entity shapes)
- The provider exposes capabilities at a finer-grained level than the static catalog (e.g. Stripe's `payment_intents` lifecycle has 5 states that map to one generic `process_payment` use case — surface them as refinements)

### When NOT to add a Layer 3 use case

- The provider just has a slightly different action name for the same use case → Layer 2's `mapping_hints` should match it
- The provider has an API for something completely outside the category → that's Layer 4 (provider dynamic), not Layer 3
- The use case fits a Layer 2 use case exactly → no Layer 3 needed

### How to find Layer 3 use cases

1. Read the provider's docs landing page + "Getting Started" + "Features" pages
2. For each Layer 2 use case in the loaded category file, ask: "Does this provider have a more specific variant or extension?"
3. Look for provider-specific concepts that the docs treat as headline features but the generic catalog doesn't cover
4. Cross-check against `api_coverage.json` — every Layer 3 use case must have ≥1 endpoint that backs it

### Layer 3 example (Gmail in `messaging` category)

```yaml
- id: cse_client_side_encryption
  name: Client-Side Encryption (CSE)
  description: Gmail-specific enterprise encryption where keys never leave the client
  mapping_hints:
    action_pattern: cse|client_side_encryption
    path_pattern: settings/cse|cseIdentities|cseKeypairs
    method_pattern: ^(GET|POST|PUT|PATCH|DELETE)$
  parent_use_case: organize_email
  rationale: Gmail uniquely exposes CSE setup APIs — most email providers don't. Refines the
             generic "organize_email" by adding encryption configuration as a first-class concern.

- id: smart_compose_assistance
  name: Smart Compose / AI Suggestions
  description: Gmail's predictive text suggestion APIs
  mapping_hints:
    action_pattern: smart_compose|predict
    path_pattern: smartCompose
    method_pattern: ^(GET|POST)$
  parent_use_case: send_message
  rationale: Gmail-specific AI text completion; not part of the generic messaging category.
```

## Layer 4 generation — use cases bubbled up from the API surface

**Goal:** identify use cases that the provider's API enables but that don't fit any Layer 1/2/3 catalog.

### When to add a Layer 4 use case

Add one when:
- A cluster of endpoints exists with a clear shared purpose, no matches in Layers 1+2+3
- The provider has a sub-product or feature area distinct from the rest (e.g. Gmail's `/history` endpoints support mailbox replay — neither universal nor email-category covers it)
- Two or more APIs share an endpoint pattern that suggests a unified use case (e.g. all `/delegates` endpoints together → "delegated mailbox access")

### When NOT to add a Layer 4 use case

- A single endpoint by itself with no related ones — probably a one-off, not a use case
- The use case already exists in Layer 1, 2, or 3 — would be a duplicate
- Deprecated / experimental endpoints (those are auto-`would_not_have` regardless of use-case coverage). **Webhook subscription/management endpoints ARE eligible for classification** — they're REST APIs and get score-tiered like helpers, so a Layer 4 use case for "webhook lifecycle management" or similar is valid. Note: webhook endpoints are still excluded from Phase 4 detail-fetching by default (`--exclude-webhooks`); the use case exists so the classification is right when the user opts in.

### How to find Layer 4 use cases

1. Group `api_coverage.json.all_apis[]` by `category` (the resource name) and by URL pattern prefix
2. For each cluster of 2+ endpoints, ask: "What user-facing capability does this enable?"
3. Check against the IDs already used in Layers 1+2+3 — skip if duplicate
4. Use the cluster's common path or action verb as `api_signal`

### Layer 4 example (Gmail)

```yaml
- id: mailbox_history_replay
  name: Mailbox History Replay
  description: Replay mailbox changes since a given history ID
  mapping_hints:
    action_pattern: history
    path_pattern: history
    method_pattern: ^GET$
  api_signal: /users/{userId}/history endpoint family
  rationale: Distinct sub-feature — neither covered by universal nor by messaging category catalog.

- id: delegated_mailbox_access
  name: Delegated Mailbox Access
  description: Grant other users access to a mailbox (Gmail-specific delegate model)
  mapping_hints:
    action_pattern: delegate
    path_pattern: settings/delegates
    method_pattern: ^(GET|POST|PUT|PATCH|DELETE)$
  api_signal: /users/{userId}/settings/delegates endpoint family
```

## Executable scripts

| Script | Purpose |
|--------|---------|
| `node ${CLAUDE_PLUGIN_ROOT}/scripts/research/write_use_cases.js <provider> <layer>` | Reads JSON use-case list from stdin, validates schema, writes YAML to the appropriate dynamic file. `<layer>` is `category_dynamic` or `provider_dynamic`. |
| `node ${CLAUDE_PLUGIN_ROOT}/scripts/research/verify_dynamic_use_cases.js <provider>` | Schema-checks both dynamic files. Reports duplicate IDs across layers. Exits 0 on clean, 1 on errors. |

## Anti-Patterns

- ❌ Generate a Layer 3 use case with the same `id` as an entry in Layer 1 or 2 — would be a duplicate, surfaced by the verifier
- ❌ Generate a Layer 4 use case that duplicates a Layer 3 entry — keep Layer 3, drop Layer 4
- ❌ Skip `mapping_hints` — required for classify_priority.js to map APIs to your use case; without it, the use case is invisible
- ❌ Use regex patterns that match too broadly (e.g. `action_pattern: ^.*$`) — defeats the purpose; the classifier needs 2 of 3 hints to fire to map an API
- ❌ Invent use cases the provider's API doesn't support — every entry's `mapping_hints` must match at least one real API in `api_coverage.json`, or the use case won't appear in `metadata/use_cases.yaml` after Phase 5B
- ❌ Add `example_apis` to a dynamic file — that field belongs to static catalog files only. Dynamic files declare detection rules; the actual mapping lives in `metadata/use_cases.yaml`
- ❌ Put Layer 4 entries in `dynamic_category.yaml` or vice versa — the writer enforces the split based on the `<layer>` argument
- ❌ Hand-write YAML directly — always pipe JSON through `write_use_cases.js` so validation runs
- ❌ Forget to set `parent_use_case` on Layer 3 entries that refine a Layer 2 use case — it's optional but helps reviewers understand the relationship