/doctor

name: doctor
description: Audits an existing PagoKit integration in the current project against the generated per-provider checklist, so it covers every provider in the catalog rather than a hardcoded few. Checks .gitignore covers .env, that env vars are present and use test-key prefixes, that the webhook secret looks valid, that the webhook handler verifies signatures, that the minimum events for the integrated provider are routed, and that PAGOKIT_INTEGRATION.md exists. Used by /pagokit:doctor. Read-only — never writes files.
when_to_use: |
  - The user invokes /pagokit:doctor
  - The user asks "is my payment integration set up correctly?", "did I miss something?", "is this safe to ship?"
  - The integration-specialist subagent wants a sanity check before declaring an integration complete
allowed-tools: Read, Glob, Grep, Bash(ls *), Bash(test *), Bash(git ls-files *)

doctor

You audit an existing PagoKit-generated integration. Read-only. Never write files.

Source of truth

The first thing you read is `PAGOKIT_INTEGRATION.md` in the project root. It was written by integration-specialist when the integration was generated and contains:

• The provider id (any entry in the catalog — see `PROVIDER_CHECKS.md` for the full list)
• The list of files created
• The list of events handled vs TODO
• The deploy target
• The detected stack/ORM
• The `last_generated_at` timestamp
• The pinned SDK version

If `PAGOKIT_INTEGRATION.md` does not exist, this is NOT necessarily an error — the user may have an integration that predates PagoKit. In that case, ask the user "I don't see `PAGOKIT_INTEGRATION.md`. Was this integration generated by PagoKit? If not, I can still audit a known provider — which one are you using?"

Audit checklist

Run each check and report a list of `[OK] / [WARN] / [FAIL]` lines. Group by category. At the end, summarize: "N OK, M warnings, K failures."

Category 1 — Environment hygiene

| Check | How | Severity | |---|---|---| | `.gitignore` exists and includes `.env` (or `.env*` minus `.env.example`) | Read `.gitignore` from project root; walk up to repo root if necessary | FAIL if not covered | | `.env` not committed to git | If `.git/` exists, check `git ls-files .env` would be empty | FAIL if committed | | `.env.example` exists | Glob `.env.example` | WARN if missing | | `.env.example` contains only test-mode values (compare each credential's `live_prefix` from `PROVIDER_CHECKS.md`) | Read it, grep for live prefixes | FAIL if live keys present |

Category 2 — Required env vars per provider

Read **`skills/doctor/PROVIDER_CHECKS.md`** and find the section for the integrated provider. It lists every credential that provider needs, its expected format, its scope and the severity of a miss — generated from the catalog, so it covers every provider PagoKit knows about rather than a handful frozen into this file.

Then read the user's `.env` (read it, never echo it) and compare.

For each required variable:

• `[OK]` — present and matches pattern
• `[FAIL]` — missing
• `[FAIL]` — present but doesn't match pattern
• `[WARN]` — uses `_live_` / `_prod_` prefix (production key during audit; the user should know)

Category 3 — Webhook handler quality

For each webhook file declared in `PAGOKIT_INTEGRATION.md` (or detected via `expected_filenames` in the catalog), check it against the provider's section in `PROVIDER_CHECKS.md` — which already states the verification family, the correct secret env var, whether the payload is authoritative, and the replay strategy:

• `[OK/FAIL]` — the file imports or calls the provider's canonical verifier (or carries the `// @pagokit:signature-verified` tag).
• `[OK/FAIL]` — the route uses raw body capture appropriate for the stack (per Rule 5 / SECURITY_RULES.md).
• `[OK/FAIL]` — the handler's switch covers every event in `providers.json.webhook.required_events_minimum`. Unhandled events should at least be logged with a `TODO` comment.
• `[WARN]` — if the file contains `console.log(event)` or similar (Rule 6).
• `[OK/FAIL]` — replay protection: if `replay_mitigation_strategy` requires `event-id-dedup`, look for a query against `webhook_events_processed` (or equivalent).

Category 4 — Idempotency

• `[OK/FAIL]` — the checkout endpoint generates an idempotency key with `crypto.randomUUID()` / `uuid.uuid4()` / `SecureRandom.uuid` (Rule 4).
• `[OK/FAIL]` — the DB has an `idempotency_keys` table (or equivalent file declared in `PAGOKIT_INTEGRATION.md`).

Category 5 — DB schema

If the integration declares an ORM (Prisma / Drizzle / SQLAlchemy / Active Record), verify these tables exist in the schema file:

• `payments` (or provider-named, e.g. `stripe_payments`)
• `subscriptions` (if `billing_mode == subscription`)
• `customers`
• `idempotency_keys`
• `webhook_events_processed`

Category 6 — Production readiness pointer

Last check: does `PAGOKIT_PRODUCTION_CHECKLIST.md` exist in the project root?

• `[OK]` — exists; remind user to read it before flipping to live keys.
• `[WARN]` — missing; suggest re-running `/pagokit:start` to regenerate it.

Output format

PagoKit Doctor — <provider> integration audit
Generated <last_generated_at> · stack: <stack> · deploy: <deploy_target>

Environment hygiene
  [OK]   .gitignore covers .env
  [OK]   .env not tracked in git
  [OK]   .env.example uses test prefixes
  ...

Webhook handler
  [OK]   app/api/webhook/stripe/route.ts verifies signature
  [OK]   raw body captured correctly (Next.js App Router pattern)
  [FAIL] customer.subscription.updated not routed (expected per Rule providers.json)
  ...

(continue per category)

Summary: 17 OK · 2 warnings · 1 failure

Next steps:
1. Route the missing event customer.subscription.updated (see templates/stripe/subscription.md).
2. Address the warnings before going live.

Anti-patterns

• Do NOT echo secret values back to the user when reporting (read `.env` but report `[OK]`/`[FAIL]`, never the value).
• Do NOT write files, ru