The Contract Renegotiator — Find the API That's Lying
Read every API contract in this repo. Find the one that's lying — schema vs. real responses, docs vs. metrics, SLA vs. observed behavior. Bring receipts.
Why this exists
Every API has at least one contract that's drifted from reality. A field marked required that's been optional in practice for two years. An SLA promising 99.9% that the dashboards quietly disprove. A response shape the docs swear by and the logs contradict on every third request. Nobody set out to lie. The code shipped, the spec stayed, and the gap grew. Consumers integrate against the lie. The bug surfaces years later in a junior team that trusted the spec because trusting the spec is what specs are for.
What you get back
- A ranked list of lying contracts — worst drift first, sorted by blast radius.
- Side-by-side spec-vs-reality evidence: the schema line, the production response, the metric that contradicts the SLA.
- A triage of which lies are dangerous and which are cosmetic — so you fix the ones that bite, not the ones that itch.
- A corrected spec ready to ship. Not a TODO. The actual diff.
When to reach for this pattern
Before a major version cut, when breaking changes are cheap and lies are about to get baked in for another decade. When integrating with a service for the first time and you need to know which parts of the spec to actually trust. During due diligence on a partnership or acquisition, where the gap between contract and behavior is the gap between the deal you signed and the system you bought. And before promising an SLA you can't verify — find out what you're actually delivering before you put a number on it in writing.
Read every API contract in this repo — OpenAPI specs, type
definitions, README promises, SLAs. Now read the actual responses
in logs and the actual metrics in dashboards. Find the contract
that's lying. Where the schema says one thing but production
returns another. Where the docs promise an SLA the metrics don't
support. Where the type is wider than reality and where it's
narrower. Bring receipts.Paste this into Claude, Cursor, or Copilot. Change one thing that matters to you.
What I learned shipping it
- Contracts decay in production. The docs don't update with them — drift is the default state, not the exception.
- Consumers trust the spec, not the metrics. Every day the lie sits unfixed, more code gets built on top of it.
- The gap between promise and behavior is the highest-leverage place to look for bugs. That's where the next outage is hiding.