# Consolidate Research Output Skill

## Purpose

Bridge between raw research collection (handled by `list-provider-apis`, `investigate-auth-*`, `fetch-endpoint-parts`) and the YAML files that downstream phases consume.

Two steps:

| Step | What it produces | From |
|------|------------------|------|
| 5A | `auth/auth_config.yaml` (single consolidated auth) | All `auth/*.json` files |
| 5B | 12 summary YAMLs (`api_type.yaml`, `actions.yaml`, `auth/scopes.yaml`, `endpoints/endpoints_master.yaml`, `metadata/*.yaml`) | `api_coverage.json` + `auth/auth_config.yaml` + `endpoints/resources/*.yaml` |

## Executable scripts

| Script | Purpose |
|--------|---------|
| `node ${CLAUDE_PLUGIN_ROOT}/scripts/research/merge_auth_config.js <provider>` | Step 5A — merge all `auth/*.json` files into `auth/auth_config.yaml` |
| `node ${CLAUDE_PLUGIN_ROOT}/scripts/research/derive_summary_yamls.js <provider>` | Step 5B — derive 12 summary YAMLs from collected research data |

Both scripts are pure, idempotent transformations of files already on disk. They take only `<provider>` as input.

**Ordering constraint:** 5A must run before 5B — `derive_summary_yamls.js` reads `auth/auth_config.yaml`, which is written by `merge_auth_config.js`. They are not interchangeable.

---

## Step 5A: Merge auth files

```bash
node ${CLAUDE_PLUGIN_ROOT}/scripts/research/merge_auth_config.js <provider>
```

**Input:** every `.connector-dev/<provider>/research/auth/*.json` file (one per detected auth type).

**Logic:** for each file, the script infers the entry's `type` (from `auth_type` field for custom auth, or `oauth2_<grant_type>` for OAuth2), then writes a single YAML containing all entries under a top-level `auth_types[]` array.

**Output:** `.connector-dev/<provider>/research/auth/auth_config.yaml`

```yaml
provider: <provider>
last_updated: "<ISO timestamp>"
auth_types:
  - type: oauth2_authorization_code
    grant_type: authorization_code
    # ... rest of fields from the JSON
  - type: api_key
    # ... rest of fields
```

---

## Step 5B: Derive summary YAMLs

```bash
node ${CLAUDE_PLUGIN_ROOT}/scripts/research/derive_summary_yamls.js <provider>
```

**Input:**
- `.connector-dev/<provider>/research/api_coverage.json`
- `.connector-dev/<provider>/research/auth/auth_config.yaml`
- `.connector-dev/<provider>/research/endpoints/resources/*.yaml`

**Output:** 12 derived YAML files

| File | Purpose | Consumed by |
|------|---------|-------------|
| `api_type.yaml` | REST/GraphQL/SOAP classification | `/connector:build` command |
| `endpoints/endpoints_master.yaml` | Master endpoint list with `by_priority` counts | `/connector:build` command, `failure-triager` |
| `actions.yaml` | Action list (everything except `would_not_have`) | `validation-rules` |
| `auth/scopes.yaml` | Standalone scopes + recommended sets, per-auth-type scope mapping when available | `auth-oauth2` build skill, `action-config` (`authRequirements` derivation) |
| `metadata/api_info.yaml` | Provider metadata + key concepts | Reference for connector builder |
| `metadata/rate_limits.yaml` | Consolidated rate limits | Reference for connector builder |
| `metadata/pagination.yaml` | Pagination styles across the API | Reference for connector builder |
| `metadata/error_codes.yaml` | Provider error envelope + retry guidance | Reference for connector builder |
| `metadata/auth_per_subapi.yaml` | Which auth method per resource | Reference (multi-auth providers) |
| `metadata/use_cases.yaml` | Use case → action_id map (which APIs serve each use case) | Reference + dashboards |
| `metadata/priority_breakdown.yaml` | Per-tier action_id lists + counts (must / should / nice / would_not) | Reference + dashboards |
| `metadata/use_case_coverage.yaml` | Coverage score: % of catalog use cases supported, orphan actions, uncovered use cases | Reference + reviewer signal |

---

## When to invoke

This skill is the last step of Phase 1 research. Always invoke it **after** all three of the following have completed:

1. `list-provider-apis` — wrote `api_coverage.json` (must include `api_type` + provider metadata fields)
2. `investigate-auth-*` (one per auth type) — wrote `auth/auth_<type>.json` for each
3. `fetch-endpoint-parts` — wrote `endpoints/resources/<resource>.yaml` for each resource (with `error_codes` + `pagination` per endpoint)

If any of these inputs is missing or incomplete, the script will fail loudly (file-not-found errors) — re-run the missing sub-skill first.

## Idempotence

Both scripts are safe to re-run. They overwrite their output files on each invocation, so partial re-runs (e.g. after adding more endpoints) just regenerate the summaries from whatever raw data is currently on disk.

## Anti-Patterns

- ❌ Run Step 5B before Step 5A — `derive_summary_yamls.js` reads `auth/auth_config.yaml` which is created by `merge_auth_config.js`
- ❌ Hand-edit the derived YAML files — they are regenerated from raw data on every re-run. Edit the source (`api_coverage.json`, `auth/auth_<type>.json`, `endpoints/resources/<resource>.yaml`) and re-run the scripts
- ❌ Skip this skill when only one auth type exists — `auth_config.yaml` is still required by build/validate phases even with one entry in `auth_types[]`