---
name: connector:validate
phase: 3
description: Phase 3 of 3 - Re-derive the connector from the provider's live documentation and reconcile every difference
triggers:
  - /connector:validate
  - validate connector
  - check [provider] against the docs
argument-hint: <provider>
---

# Validate

Phase 3 of **Research → Build → Validate**.

`$ARGUMENTS`

Load the `validate-config` skill and follow it. This command exists to sequence the two
halves of the phase and run the gate.

## The rule this phase turns on

**Re-read the provider's documentation.** Do not check the connector against
`{{provider}}_research.json` — that artifact is what produced this connector, so comparing
the two proves only that the build was faithful to a possibly incomplete input. Anything
research missed would be certified correct.

Research is the hypothesis. This is the adversarial check on it.

**Spawn both halves concurrently, in one message, FOREGROUND
(`run_in_background: false`).** The `schema-reviewer` and every `provider-comparator`
pass read the built connector independently — nothing orders them. One message spawns the
reviewer plus one comparator per resource (batches of 3–5 if the resource count is high);
foreground spawns in one message still run concurrently, and the message returns with
every report in hand. Never background — an uncollected background agent is tokens spent
for nothing (measured in research: finished summaries sat unread while the parent re-did
the work). Spawning one after another serializes 1–2 minutes of doc re-fetching per
resource for no ordering benefit — the token total is identical either way.

## Half one — structural review

Delegate to the `schema-reviewer` agent. It owns 14 check groups: connector structure, auth
block, partial wiring, input config, args mapping, step functions, expressions, scopes,
parameter completeness against research data, resource coverage, field mapping, end-to-end
wiring trace, and per-action resource URL verification.

Fix what it reports inline — after the concurrent spawn returns.

## Half two — documentation re-derivation

Delegate to the `provider-comparator` agent, one pass per resource — all passes spawned
together per the rule above. For each, write:

```
.connector-dev/{{provider}}/validation/{{provider}}_{{resource}}_doc_comparison.json
```

```bash
node ${CLAUDE_PLUGIN_ROOT}/scripts/gates/validate.js --schema
```

`docsRead[]` must list the documentation URLs actually opened. **A report with an empty
`docsRead` is rejected** — it is the only evidence that the check was independent rather than
a re-reading of research.

Check per action: path and method match · every documented parameter present with right type,
requiredness and **full** enum list · no invented parameters · description matches documented
behaviour including defaults and exclusions · pagination as documented · every id parameter
has a producing action.

## The gate

```bash
node ${CLAUDE_PLUGIN_ROOT}/scripts/gates/validate.js \
  --provider {{provider}} --connector-path <dir>
```

`V1` structure · `V2` re-derivation complete · `V3` no parameter discrepancies · `V4` no
endpoint omissions · `V5` descriptions accurate · `V6` dependency and pagination coherence ·
`V7` scope reconciliation · `V8` gap ledger clean · `V9` every action cites its doc page ·
`V10` every published version records what changed — `info.changelog` with a 1-2 line
customer-facing summary on every version, initial included; labels from
auth/downstream-change/bug-fix/new-actions; `ga` below 1.0.0 blocks.

Exit `0` and the run is complete. Exit `1`, fix what it reports and run again — scoped to one
resource where the fix was local:

```bash
node ${CLAUDE_PLUGIN_ROOT}/scripts/gates/validate.js --provider {{provider}} --scope candidates
```

Two consecutive rounds resolving nothing → mark the phase `exhausted` and finish. A coverage
gap found here usually means research missed an endpoint; rewinding to research is legitimate,
bounded by `policy.rewindBudget`.

```bash
node ${CLAUDE_PLUGIN_ROOT}/scripts/state/run.js set-phase \
  --provider {{provider}} --phase validate --status <complete|exhausted> [--unmet V3,V5]
```

## Verdict

```
Validation: {{provider}}

Structure:    14/14 check groups passed
Re-derived:   41/41 actions against 12 documentation pages
Discrepancies: 0
Scope:        41 of 41 in-scope endpoints, 0 unaccounted

Verdict: VALIDATED
```

Validation is the final phase — there is nothing after it.

**What this proves, and what it does not.** Every documented in-scope endpoint has an action,
parameters match the docs, and every action was re-checked against a cited URL. It does not
prove any action executes. The connector is **documentation-complete**, never "tested", and
the report must say so.