# Provider Schema Comparison

## Purpose

Invoke the `provider-comparator` agent to compare the connector schema against the provider's official API documentation. This skill finds missing parameters, type mismatches, name mismatches, and missing companion actions.

**CRITICAL:**
- Requires research data from Phase 1 (`.connector-dev/{provider}/research/`)
- Processes ACTION-BY-ACTION to guarantee 100% coverage
- Uses Playwright MCP for JS-rendered docs

---

## Pre-Requisite

**Research data SHOULD exist before running:**

```bash
ls .connector-dev/<provider>/research/endpoints/resources/
```

If missing, the agent will use **RIGOROUS LIVE FALLBACK** with multi-tool extraction:
1. `mcp-server-fetch` — fast URL fetching with pagination
2. `WebFetch` — built-in fallback
3. Playwright snapshot — for JS-rendered docs
4. Playwright evaluate — for interactive elements

**Best practice:** Run `/connector:research <provider>` first for comprehensive coverage.

---

## When to Use

- Before Phase 4 testing to catch missing params
- After adding new actions to verify completeness
- When tests fail with unexpected 400 errors
- To improve connector coverage

---

## Invocation

```
/provider-schema-comparison <provider>
```

Or when triggered by natural language:
- "Compare bamboohr schema with their API docs"
- "Find missing params in workday connector"
- "Check if we have all salesforce params"

---

## What It Catches

| Bug Type | Severity | Example |
|----------|----------|---------|
| Missing companion action | **BLOCKING** | `polling_onboard` exists but no `polling_result` |
| Type mismatch | **BLOCKING** | Schema says `string`, provider says `integer` |
| Name mismatch | **HIGH** | We use `from_date`, provider uses `start_date` |
| Missing pagination | **BLOCKING** | `cursor` not in schema |
| Missing filter | HIGH | `updated_after` missing |
| Missing enum value | HIGH | `status` missing `archived` value |

---

## Process — ACTION-BY-ACTION

```
Step 0: FAIL FAST if no research data

FOR each partial file:
  FOR each action:
    1. Read action from OUR schema
    2. Load research data for this endpoint
    3. STRICT comparison:
       - Verify every param NAME matches exactly
       - Verify every param TYPE matches
       - Check for missing params
    4. Check companion actions (polling, async)
    5. WRITE shard file immediately
  END FOR
END FOR

Aggregate all shards into final report
```

---

## Strict Verification Rules

### Rule 1: Never Trust Existing Schema
```
❌ Wrong: "We have from_date, provider has date param, looks good"
✅ Right: "We have from_date, provider says start_date → NAME MISMATCH"
```

### Rule 2: Type Checking is STRICT
```
string ≠ number ≠ integer ≠ array
team_id (string) vs teams (array) → TYPE MISMATCH
```

### Rule 3: Missing Companions are BLOCKING
```
If we have: polling_onboard_employee
Must have:  polling_onboard_result → BLOCKING if missing
```

---

## Output

### Per-Action Shards
```
.connector-dev/<provider>/validation/shards/
├── list_employees.json
├── get_employee.json
└── ...
```

### Aggregated Report
```
.connector-dev/<provider>/validation/
├── provider-comparison.json   # Full findings from all shards
├── provider-comparison.md     # Human-readable summary
└── shards/                    # Per-action evidence
```

### Summary Format
```
═══════════════════════════════════════════════════════════════
PROVIDER SCHEMA COMPARISON: employmenthero
═══════════════════════════════════════════════════════════════

Source: Research data (.connector-dev/employmenthero/research/)

BLOCKING ISSUES: 3
  - 1 missing companion action
  - 2 type mismatches

HIGH ISSUES: 8
  - 3 name mismatches
  - 5 missing params

BLOCKING (must fix before testing):

[BLOCKING] Missing companion: polling_onboard_result
  We have: polling_onboard_employee
  File: employmenthero.employees.s1.partial.yaml

[BLOCKING] Type mismatch: list_unavailabilities.location_id
  Our type: string
  Provider type: number
  docQuote: "location_id (integer) - filter by location"

[HIGH] Name mismatch: list_leave_requests.from_date
  Our name: from_date
  Provider name: start_date
  docQuote: "start_date (string) - filter by start date"
═══════════════════════════════════════════════════════════════
```

---

## Resume Support

If the agent times out or is interrupted:

```bash
# Re-run - skips completed actions
/provider-schema-comparison <provider>

# Force fresh run
rm -rf .connector-dev/<provider>/validation/shards/
```

---

## Integration

This skill spawns the `provider-comparator` agent which:
1. Checks for research data (uses rigorous live fallback if missing)
2. Processes each action one-by-one
3. Uses multi-tool fallback chain: fetch MCP → WebFetch → Playwright
4. Performs BIDIRECTIONAL validation (schema→docs AND docs→schema)
5. Extracts params into structured format with evidence
6. Writes shard file after each action
7. Aggregates all shards at end

**Live Fallback Quality:**
- Structured extraction (not ad-hoc skimming)
- Inverse check mandatory (catches missing params)
- Quality gate before proceeding
- Extraction evidence saved in shard

Results feed into:
- Phase 3 completion gate
- BLOCKING findings must be fixed before Phase 4

---

## Rules

1. **Research data preferred** — uses rigorous live fallback if missing
2. **Process ACTION-BY-ACTION** — guarantees 100% coverage
3. **Never trust existing params** — verify name AND type
4. **Type checking is STRICT** — string ≠ number ≠ array. Exception: inputs with `variants` have no top-level `type` — check each variant's type instead
5. **Missing companions are BLOCKING** — async workflows break
6. **Every finding needs docQuote** — prove we saw it in provider docs
7. **Inverse check mandatory** — check BOTH directions to catch missing params
8. **Multi-tool fallback** — fetch MCP → WebFetch → Playwright (don't give up early)