# Extraction Signals for Dynamic Use Cases

How to detect Layer 3 and Layer 4 use cases from provider docs and the API surface. Loaded by the `use-case-discoverer` agent on demand.

---

## Layer 3 signals (provider-category refinements)

Read these signals from the provider's docs landing page, "Getting Started", "Features", "Use Cases", and "Concepts" sections.

### Signal 3.1 — Provider treats a sub-feature as a headline

If the provider's marketing or docs front page calls out a specific capability:

> "Gmail's Client-Side Encryption keeps your most sensitive messages secure"

And that capability has its own endpoint family in `api_coverage.json`:

> `/users/{userId}/settings/cse/identities/*`
> `/users/{userId}/settings/cse/keypairs/*`

→ Layer 3 use case (`cse_client_side_encryption`).

### Signal 3.2 — Provider-specific entity inside a generic category

The generic Layer 2 catalog says `deal_pipeline` (CRM). HubSpot extends this with "deal stages" and "deal forecasting" as separate API surfaces.

→ Layer 3 use cases (`deal_stage_management`, `deal_forecasting`).

### Signal 3.3 — Workflow distinct from category peers

Stripe's payment intent has 5 lifecycle states (`requires_payment_method` → `requires_confirmation` → `processing` → `succeeded` / `requires_action`). Other payment providers don't expose this state machine.

→ Layer 3 use case (`payment_intent_lifecycle`).

### Signal 3.4 — Domain-specific terminology

Provider uses unique vocabulary that doesn't map cleanly to the generic catalog (e.g. Stripe's "destinations" for connected-account payouts, Adyen's "subMerchants").

→ Layer 3 use case (`destination_payouts`).

### When a Layer 2 use case is enough — DON'T add Layer 3

- The provider has the same action with a different name → Layer 2's `mapping_hints` should match it (action_pattern allows alternates)
- The provider supports the use case in standard form → no refinement needed

---

## Layer 4 signals (provider-API-derived use cases)

Read these signals from `api_coverage.json.all_apis[]` itself — group endpoints and look for clusters that don't fit any Layer 1/2/3 use case.

### Signal 4.1 — Cluster of endpoints around a sub-feature

Several endpoints share a path prefix and resource model that no static use case captures:

```
/users/{userId}/history             (list)
/users/{userId}/history/{startId}   (get from a point in time)
```

If the cluster ≥2 endpoints with a clear shared purpose → Layer 4 use case (`mailbox_history_replay`).

### Signal 4.2 — Distinct sub-product

The provider has a sub-product distinct enough to warrant its own use case (e.g. Stripe Issuing, Stripe Connect, Stripe Climate). Each has its own endpoint family + concepts.

→ Layer 4 use cases, one per sub-product.

### Signal 4.3 — Provider-specific feature with no equivalent elsewhere

Gmail's `/users/{userId}/settings/delegates/*` — delegated mailbox access. The generic `messaging` catalog doesn't cover this; the generic `iam` catalog has `permission_management` but it's about access tokens, not mailbox delegation.

→ Layer 4 use case (`delegated_mailbox_access`).

### Signal 4.4 — Cross-domain integration capabilities

Some providers ship integrations as APIs (e.g. Salesforce's `/services/data/v59.0/connect/*` for Chatter integrations, Slack's incoming webhooks).

→ Layer 4 use case.

### When NOT to create Layer 4

- A single endpoint with no related ones — probably one-off, not a use case worth surfacing
- Already covered by Layer 1/2/3 — drop, would be a duplicate
- Webhook / deprecated / experimental endpoints — these are intrinsically `would_not_have`, use-case coverage doesn't help them

---

## How to check for duplicates

After drafting Layer 3 + Layer 4 use cases, before calling `write_use_cases.js`:

1. List all `id` values from `universal.yaml` (Layer 1)
2. List all `id` values from the loaded `categories/<cat>.yaml` (Layer 2)
3. List all `id` values from your draft Layer 3
4. For each Layer 4 draft entry, check it's not in any of the above sets
5. For each Layer 3 draft entry, check it's not in Layers 1 or 2

`verify_dynamic_use_cases.js` will surface any cross-layer duplicates after writing, but it's faster to deduplicate during drafting.

---

## Mapping hints quality

Each use case has `mapping_hints` with 3 regex fields. The `classify_priority.js` mapper requires **2 of 3 patterns** to match for an API to be tagged with that use case.

**Good patterns** — specific enough that they only fire for the intended APIs:
```yaml
mapping_hints:
  action_pattern: ^(list|get)_delegates?$
  path_pattern: settings/delegates
  method_pattern: ^(GET|POST|PUT|DELETE)$
```

**Bad patterns** — too broad, will match unrelated APIs:
```yaml
mapping_hints:
  action_pattern: .*
  path_pattern: .*
  method_pattern: .*
```

The mapper requires ≥ 2 matches, so a single wildcard alone won't cause damage. But three wildcards will map this use case to every API and inflate priority scores incorrectly.

**Test your patterns** by mentally walking through a few entries in `api_coverage.json`. If a pattern would match an unrelated API, tighten it.