←All posts

When the Real Test Happens Outside Your Control

Link previews, webhooks and email clients all share the same awkward property. The final confirmation lives on infrastructure you do not own. Here is how we now write briefs for work we cannot fully observe ourselves.

3 min read

A few days ago we added branded link previews for posts on X. The technical work was ordinary. Generate an image on demand, drop the right Open Graph tags in place, and ship. The part that felt different was the verification.

You can open the image URL in a browser and confirm the picture looks correct. That only proves the generation path works. It does not prove that X will fetch the image, cache it, and display the card the way you expect when someone actually shares the link. That step runs on their servers, on their schedule, under their own caching and rate-limit rules.

Most failures live inside our own walls

Most features we ship never create this gap. A button that does nothing is obvious the moment you click it. An API that returns the wrong payload shows up in the logs at once. Those failures live inside environments we control.

Social cards sit in a different category. The same is true of webhooks that only fire from a third-party platform, HTML emails that render differently in every client, and search results that update only after an external crawler decides to visit again. In each case the moment of truth happens on infrastructure that does not belong to us.

That difference changes how the work should be specified. It matters even more when the person or model writing the code has less direct access to the final result than the person who asked for the feature.

Four rules for briefs you cannot watch end to end

We now treat verification as its own explicit requirement rather than an afterthought:

  1. Keep the generation step separate from the confirmation step. Creating the image and proving the platform actually uses it are two different jobs with different ways of failing. The brief should never collapse them into one line.

  2. Name the concrete checking method. "Make sure it works" is not a test. "Paste the URL into the platform's card validator and attach the resulting screenshot" is.

  3. Plan for caching from the start. External systems often keep old versions longer than you expect. Include a deliberate cache-bust or a documented waiting period so a stale result is not read as a broken implementation.

  4. Describe success in terms of evidence someone else can produce. If the person doing the work cannot see the final render themselves, the brief must spell out exactly what a correct outcome looks like so a screenshot or log can be judged against it.

A brief for a feature you cannot watch end to end has to carry more weight than a brief for one you can. It needs to define the proof that would satisfy you, not only the behaviour you want.

The same shape, everywhere the last step is someone else's

The same shape appears whenever the decisive step sits outside your own systems. Payment flows that only complete in a provider's sandbox, callbacks that only arrive from a partner's servers, or any task handed to a model that later has to be inspected by hand. The practical response stays consistent: write the proof into the specification instead of assuming the code path alone is enough.