workflow Provision Live To Learn Contract
When an external API's exact request schema is uncertain and a dry-run skips the network, stop guessing from docs — make ONE real call and let the error response teach you the precise contract, then fix and retry. Activates when scripting create/update against an API (dashboards, webhooks, resources) whose field/enum shape you're inferring, especially when a dry-run can't validate it.
Install this skill
git submodule add https://github.com/modh-labs/playbook.git .playbookOne submodule installs all 17 skills. Reference .playbook/skills/provision-live-to-learn-contract/SKILL.md from your AGENTS.md.
Provision Live to Learn the Contract
Docs drift, enums get deprecated, and a --dry-run that skips the network can
only validate your code, not the server's acceptance. When you're unsure of
an API's exact shape, a single live call is the fastest, most reliable spec —
well-built APIs reject with the exact remedy in the error body.
The One Question
"Has anything actually validated this payload against the server, or only against my own code?"
A passing dry-run, a green typecheck, and matching docs all answer "only my code." Only a real request answers "the server."
Core Rules
- Prefer a live POST/PUT over more doc-reading once you've made a reasonable first attempt — the round-trip is faster than another docs pass and is ground truth.
- Read the error body, don't just check the status. Good APIs name the bad
field + the fix (e.g. "the transactions dataset is deprecated; use the spans
dataset with
is_transaction:true"). That one 400 replaced an hour of guessing. - Make the first live call cheap + reversible — one resource, idempotent (upsert-by-name), easy to delete. Then iterate on the error.
- A dry-run that skips the network is for payload assembly, not acceptance. Use it to catch shape/typos, but never trust it as "this will work."
- Codify what the error taught you in the script + a comment so the next person doesn't re-learn it (and the deprecation is recorded).
Anti-Patterns
- Shipping an un-exercised payload for someone else to debug in prod.
- Treating "dry-run passed" as "it works".
- Re-reading docs in a loop when one live call would settle it.
- Bulk-creating N resources before validating the shape on one.
Audit Checklist
- The payload was validated by a real server call, not just a dry-run/typecheck.
- First live attempt was a single, reversible resource.
- Error responses were read for the exact contract, not just status-checked.
- The learned contract (and any deprecation) is captured in code + comment.
Related Skills
Background Job Right Sizing
Choose the LIGHTEST durable mechanism a background/async/side-effect job actually needs, instead of reaching for a full workflow engine by reflex. A four-rung ladder — in-process fire-and-forget → durable queue → workflow engine → dedicated orchestrator — routed by four axes: durability, step count, concurrency shape, and cross-app/bus membership. Activates when adding any background job, emitting a side-effect from a request handler, choosing between Vercel Queues / Workflows / Inngest / Temporal / SQS, or auditing an existing job fleet for over-engineering ("do we still need the orchestrator for this?").
Workflow / ProcessworkflowBug Cleanup Triage
Framework for backlog bug cleanup sessions. Triage is three sequential activities — Linear hygiene, root-cause investigation, and code fixing — that must be executed in order as a hard phase gate. Includes git log pre-flight, Sentry module-tag verification, and umbrella breakdown auto-detection. Use when planning to clean up N bugs from a backlog, before dispatching research agents, or when a ticket has been In Progress for weeks without shipping.
Workflow / ProcessworkflowCI Pipeline Standards
Enforce CI pipeline conventions. Use when adding CI checks, modifying GitHub Actions workflows, or discussing CI vs deployment. Prevents deployment steps in CI and ensures the extensible step pattern is followed.
Workflow / Process