Intent architecture

Ask an engineering leader what her team is optimising for this quarter and she'll give you a clean answer in under ten seconds. Reliability, mostly, with room for the two features sales already promised. She means it. Ask her three senior engineers the same question, separately, and you'll get three answers that are recognisably related and meaningfully different, and none of the three people involved will think anything went wrong.

Nothing did, historically. This is how organisations have always worked. A leader states direction at a level of abstraction that leaves room to manoeuvre, and then a chain of people underneath her fills in the specifics through conversation, correction, and the accumulated judgment of having been in the room for the last eighteen months of context that never made it into a doc. Someone interprets the direction slightly wrong, ships something, gets feedback, adjusts. The signal degrades a little at every handoff and gets restored a little at every correction, and on average, across a few cycles, it converges close enough. Call it the oral tradition of organisational direction. It isn't a failure to write things down. It's a working system that happened to require a person on both ends of every handoff.

The system runs on one assumption you rarely have to state, because it has always been true: whoever receives the instruction can ask what you meant.

What breaks first

The first time a non-human system acts on that same instruction, the assumption is gone, and it doesn't degrade gracefully. It breaks immediately, on the first cycle, in a way that's visible and specific.

Picture a platform team that ships an agent to triage incoming pull requests: flag anything touching the billing schema for mandatory human review, wave everything else through once CI is green. The rule sounds complete when someone says it out loud in a planning meeting. It is not complete. Does "touching the billing schema" mean the migration files, or does it include a shared utility function that the billing service happens to import? Does a config change that alters a billing feature flag count? Nobody asked, because in the old system nobody had to. A senior engineer reviewing PRs by hand would have applied the spirit of the rule without ever noticing the spirit and the letter had drifted apart. The agent has no spirit to apply. It has the sentence you gave it, and it will do exactly what the sentence says, which is a slightly wrong version of what you meant, every single time, with no correction loop unless you built one.

This is not a story about a bad agent or an underspecified prompt. It's a story about ambiguity that was always there, always costing something, and was always being paid for silently by a person who filled the gap without either of you registering that a gap existed. The system didn't create the cost. It made the cost visible, and it stopped picking up the tab.

Two ways to tell a system what you want

There's an old distinction from programming language design that turns out to be the entire argument: imperative versus declarative. Imperative means you specify the steps. Fetch the diff. Check the file paths. If any path matches this pattern, tag for review. Declarative means you specify the outcome you want to be true and let the system work out how to get there: no change to the billing surface reaches production without a named human's approval.

Most organisations, without ever using this language, are running their AI tools imperatively. A person sits down, translates a real, messy situation into a specific instruction, gets an output, checks it, and does the whole thing again next week for a slightly different situation. That's not automation in any deep sense. It's a person doing the same cognitive work they always did, just typing it into a different box, and paying the prompt tax for it every week.

The declarative version asks something harder up front and something much cheaper afterward: what do you actually want to be true, stated precisely enough that a system can check whether it's true without asking you. Get that right once and the system reads it every time. Get it wrong, or leave it vague, and you've built a machine for executing your ambiguity at a scale no team of humans ever could.

The document that does the work

Writing this down has a name and a form. Call it an intent document, and keep it to one page. Seven things on it, no more:

The outcome you want, stated precisely enough that two reasonable people reading it would agree on whether it happened. "Reduce review latency" fails that test. "Median time from PR open to first human review, under four hours, for anything the agent flags for mandatory review" passes it.

Why this is the priority right now, not permanently. Conditions change; a document that doesn't say why it exists gets treated as timeless, and a timeless intent document is usually a stale one nobody's willing to touch.

The system or surface it actually governs, named specifically enough to be wrong about. "Our review process" is not a surface. "PRs opened against the payments service, human and agent-authored both" is.

The trade-offs you've already decided, in language that admits something is being given up. This is the part people skip, because naming a trade-off out loud is a smaller, more specific decision than the vague version, and smaller decisions are easier to be wrong about in a way someone can point to later.

The questions you haven't answered yet, with an owner and a date attached, instead of quietly letting whoever hits the gap first invent an answer and have it become policy by accident.

The conditions under which you'd revisit the whole thing. Without this, the document is a photograph of a decision, not a description of a state you're maintaining, and photographs age badly.

Who owns it, by name, and how often they look at it again.

The output isn't ceremony. It's the thing standing between "the agent did something technically correct and completely wrong" and a system that behaves the way you actually meant.

The part I got wrong first

I used to think organisations kept their strategy vague out of laziness, or a failure of discipline, and that the fix was mostly a willingness to write more precisely. That's backwards, and it took watching a few leaders resist the exercise before I understood why.

Strategic ambiguity isn't a bug. In a lot of organisations it's load-bearing. "We're prioritising reliability and shipping velocity" lets two factions who actually disagree about the trade-off both feel represented, right up until someone has to make a call at 2 a.m. and the sentence turns out to have never meant anything specific enough to make it with. Vagueness is how a coalition holds together without anyone losing an argument they'd rather not have in front of the room. That's a real function. Writing an intent document doesn't just cost time. It costs someone the ability to keep avoiding a fight they've been avoiding on purpose.

That's the actual reason this is hard, and it's not a process problem you fix with a template. It's a decision to have the argument now, on paper, where it's checkable, instead of later, in production, where it's a postmortem.

What it isn't

It isn't a mission statement, and it isn't a fourteen-page style guide either. Both of those are real artefacts with real jobs. A mission tells a person why the team exists. A strategy sets a direction. Neither is precise enough for a system to act on without a human translating it first, and translating it first is exactly the cost this whole exercise exists to remove.

It also isn't a one-time deliverable. A document that's accurate the day it's written and never touched again drifts, quietly, until the system is executing last quarter's priorities with complete confidence and no one notices for a while, because nothing throws an error. The drift is the second half of this problem, and it deserves its own argument. This one is about getting the first version onto paper, specific enough that it's worth maintaining at all.

Start smaller than feels sufficient. One system, one page, seven fields. The tool below builds it with you.