AI writes clean, testable code inside a single function; the trouble starts in the gap between two systems that never agreed on what "done" means.
The Details:
- Training data skews toward the happy path. Postmortems, runbooks, and 3 a.m. pager lessons about duplicate deliveries, clock skew, and partial writes rarely make it into a function signature, so a generated retry handler pattern-matches against the common case instead of the failure that actually ships.
- Idempotency is not a property of one function call, it is a property of an ongoing exchange between systems over time. A model reasoning about a single turn will handle the delivery it was shown and silently assume no other shape of delivery will ever arrive, across regions, hours, or an upstream retry policy that changed last sprint.
- The fix is to write the seam's contract before any implementation exists: what happens on a duplicate fire, who owns the retry, how a 5xx is handled versus a 4xx, and what clock skew tolerance the idempotency logic actually survives. Once that list exists on paper, code review has something concrete to interrogate instead of just checking syntax that already looks fine.
- A simple prompting shift makes assumptions visible: ask the model to list what it is assuming about the other side before writing any integration code. Turning "the webhook" into "our side of the webhook" names the boundary, and a named assumption becomes a testable claim rather than a silent guess.
Bottom Line: Smarter models will not close this gap because the failure is epistemic, not computational; the builder still has to define the contract at the seam before handing either side to the AI.
