A short piece of fiction, written by API Evangelist. The reader is imagined; the post, and every number and quotation from it, is real: "What A Program Needs In Order To Decide," Kin Lane, October 21, 2026, https://apievangelist.com/2026/10/21/what-a-program-needs-in-order-to-decide/
Priya read the post on a Wednesday afternoon, between a code review and a standup she was dreading. She builds backend services for an invoicing product, and a colleague had dropped the link into the team channel with no comment, which usually meant it was worth her time.
She liked the part about Mike Amundsen's two axioms more than she expected to. The shift the post describes was from asking what the program needs to do next to asking "what does the program need in order to decide what it will do next". She read that twice. It was the difference between writing instructions and writing down the world those instructions assumed.
Then she hit the list of five things a program has to do, and her attention sharpened. The post says "A 200 OK is not success." She winced, because her own team's docs said almost exactly that a 200 meant the invoice was created, and nothing else. An agent calling their API would have no way to know whether the result matched the shape its goal needed. It would see a green status and move on.
She also felt a small, honest resistance. The post is written by someone who runs a catalog of exactly these artifacts, and its conclusion, that the provider should be the one to do the context engineering, conveniently describes a lot of work for people like her. She wasn't sure every provider could afford to publish a contract, a workflow, a schema, a rate limit and an access policy for every operation. Some of those she had never seen a product manager ask for. She typed a half-formed objection into her notes: this is a lot to ask of a team that is still behind on its changelog.
But the line she couldn't argue with was the one about what happens when assumptions stay in people's heads. Without them written down, the post says, the program will "guess or stall". She thought about the payment retry logic she had patched twice last year, and about the support thread where a customer's script had hammered a refund endpoint because nothing told it to stop. Nobody had ever written down that a refund couldn't be undone.
The post calls the per-operation statement of cost, reversibility and human approval "the explicit statement of where autonomy stops". She decided she didn't need a catalog or a standard to start on that. She didn't need anyone's permission either.
She closed the post and opened the repository for the refunds service. She didn't touch the code. She created a plain text file next to the route definitions and wrote three lines for the refund operation: that it moves money, that it cannot be reversed once issued, and that anything above a certain amount should go to a person first. She left the amount blank, since she didn't know it yet, and added a note to ask finance on Thursday.
It wasn't an OpenAPI extension or a policy format. It was three lines in a file. She committed it to a branch, wrote a one-sentence description, and went to standup.