AI Agent Requirements Doc: Catch a Wrong Destination Early

The feature was half-built before anyone noticed it was half-wrong. Forty files touched, three new modules, a migration, two days of agent time. Auth, billing, and the dashboard had all grown new code - faithfully, cleanly, on brand with the codebase. None of it connected to what the ticket actually asked for. The agent had read the first sentence of the ask, decided what “the feature” meant, and built that thing across the whole repo with total conviction. There was no degradation to blame. The misread happened on the first sentence, and everything after it was consistent with the misread.

That’s a different failure than the one this blog usually names. A long build going senile mid-session - forgetting its own earlier decisions, contradicting itself, quietly getting dumber as the window fills - has its own fix, and The Relay, Not the Window already covers it well. This failure has nothing to do with the window filling. The agent here was sharp the whole time. It read the ask once, committed to a destination, and executed that destination perfectly - forty files of clean, consistent, wrong.

Every technique for keeping a long build sharp protects the journey: the order things get built in, the boundaries between layers, the discipline of staying inside the window’s reliable zone. None of it touches the destination: whether what’s being built is the right thing at all. A flawless journey toward the wrong destination arrives exactly on schedule, at the wrong place, and every technique that made the journey flawless just got it there faster.

Catch a wrong destination at a review before any plan or code exists, and it costs about 1.9% of what the finished build will cost in tokens. Catch the identical misread after the last phase ships - forty files in, the way the opening anecdote did - and it costs all of it: 52.5 times more, for the exact same mistake. Nobody wrote the wrong thing more slowly. Someone just noticed later. Here’s exactly where that ratio comes from, on one feature, checkpoint by checkpoint.

Think of the last multi-day build an agent finished for you: something that took a plan, ran across more than one sitting, touched more than a handful of files. When it was done, was there ever a moment you realized it had built the wrong thing? Built cleanly, and wrong.

If nothing like that comes to mind, and every build that size already starts with a written requirements doc that someone other than its author reads before any plan exists, you already run the gate this piece is about to name. Skip to the table near the end and see which row you’re standing on.

If you can think of one, or “requirements doc” in your shop means a paragraph in a chat window that nobody reviewed, keep going. What follows is the price of that gap, worked out to the token on one feature.

A destination review either already happens on your builds or it doesn’t; everything below is what the second case costs.

A large feature has two things that can go wrong, and a fix for one does nothing for the other.

The destination is what “correct” looks like when the build is done: which user can do what, and why, and what’s explicitly not included. Get it wrong and the agent builds the wrong product, well.

The journey is the order you build it in: schema before the service that reads it, the service before the endpoint, the endpoint before the UI that calls it. Get it wrong and the agent builds layer three on top of a layer one that doesn’t exist yet.

Most people fuse both into one prompt and lose both. Worse, most of the techniques this blog already teaches only ever fix the journey. A fresh window per phase, a committed plan file, a second model auditing the checklist - every one of those techniques assumes the destination on the plan is the right one, and does its job perfectly regardless of whether that’s true. Run the journey flawlessly toward the wrong destination and you get the opening anecdote: forty files, on brand, consistent, and off target from word one.

The journey has a whole toolkit on this blog already. The destination gets one document, and this piece is about that document alone.

Before any code, and before any plan, you write a requirements doc. Keep it short. It is a contract with a fixed shape:

# Requirements: Team Invitations

## Problem
Admins can't add teammates. Today the only way onto an account
is a shared login. We need per-user accounts under one org.

## Solution (one paragraph)
An admin sends an email invite. The recipient clicks a link,
sets a password, and lands in the org with a "member" role.

## User stories
1. As an admin, I want to invite a teammate by email,
   so that they get their own login instead of sharing mine.
2. As an admin, I want to see pending invites,
   so that I know who hasn't accepted yet.
3. As an invitee, I want a link that expires in 7 days,
   so that a leaked old email can't grant access forever.

## Technical decisions
- Invites are rows in `invitations`, not a new service.
- Token is a signed JWT, not a DB-stored secret.
- Reuse existing `roles` enum; do not add new roles.

## Out of scope
- SSO / SAML. Not now.
- Bulk CSV invite. Not now.
- Editing a member's role after they join. Separate feature.
- Email deliverability/retry logic. Assume the mailer works.

This is a lightweight, do-it-yourself member of a wider family of 2026 tooling that formalizes the same instinct: GitHub’s Spec Kit, AWS’s Kiro, Tessl, OpenSpec, BMAD, and Google’s Antigravity all ship some version of “write the destination down before code exists.” None of that scaffolding is required here. One markdown file, no framework, works with any agent that reads text.

The user stories in role/want/why form state the destination as behavior rather than implementation - testable, with no room to interpret them into the wrong feature. But the section doing the most work is the one people skip: out of scope is negative space, and negative space is context. Writing “SSO and SAML are not in this build” costs eight words and prevents an agent from spending two hours scaffolding an identity provider because it pattern-matched “invitations” to “enterprise auth.” A broad model has seen more invitation systems than any one engineer ever will; left unconstrained, it builds the average of all of them. The out-of-scope list is how your specific knowledge of what this actually needs overrides that average - the cheapest context in the whole document that changes what gets built.

This is a Rules-shaped move at feature scope: your AGENTS.md carries standing context for the whole repo, and this file carries standing context for one feature, committed so it can’t drift out of the agent’s head between sessions.

Eight words in the out-of-scope list can stop two hours of scaffolding, which makes them the cheapest context on this page.

With the destination committed, you ask the agent, in plan mode, to turn the requirements into an ordered build:

# Plan: Team Invitations

## Phase 1 - Schema
- Add `invitations` table: id, org_id, email, role, token,
  status, expires_at, created_at.

## Phase 2 - Service layer
- createInvite(orgId, email, role) -> signed token.
- acceptInvite(token) -> validates, creates user, returns session.

## Phase 3 - API
- POST /invites, POST /invites/accept, GET /invites. Auth guards here.

## Phase 4 - UI
- Invite form + pending-invites table. Accept page: set password.
  Calls Phase 3 endpoints only.

Each phase names what it owns, and each phase runs in its own cleared window, fed exactly the requirements doc and the entire plan, then commits before the next phase starts. That’s the execution technique this blog already covers in full, twice: The Relay, Not the Window derives why an agent’s reasoning degrades well before its context window fills, with the citations for that effect, and Treat the Plan File as External Memory walks the checklist-and-audit version of the same relay on a 340-file migration, including Anthropic’s own published guidance on structured note-taking for long jobs. Both pieces already carry their own worked examples for exactly this mechanism, so this piece isn’t re-deriving it: the relay is how a correct plan gets executed well. What makes the plan worth executing in the first place is the other question, and it’s the one this piece is actually about.

The relay makes a good plan survive contact with a long build. It has no opinion on whether the plan was good.

Here’s the arithmetic behind the 52.5x from the top, worked on the Team Invitations build, checkpoint by checkpoint, top to bottom, no shortcut.

Each phase has an own load: the tokens it spends reading files for context, plus the tokens it spends writing its diff. At 2,000 tokens per file read - the per-file rate this blog already uses elsewhere - and 15 tokens per diff line, a stated assumption, the four phases cost:

Phase 1 - Schema:   3 files x 2,000  +  60 diff lines x 15  =  6,900 tokens
Phase 2 - Service:  4 files x 2,000  +  90 diff lines x 15  =  9,350 tokens
Phase 3 - API:      3 files x 2,000  +  70 diff lines x 15  =  7,050 tokens
Phase 4 - UI:       5 files x 2,000  + 140 diff lines x 15  = 12,100 tokens

Add the two committed documents - the 700-token requirements doc, the 650-token plan - and the whole build costs 36,750 tokens. That’s the entire feature, and it’s small enough to walk by hand.

Now run the checkpoints where a destination misread could actually get caught, in the order they happen, and ask how much of that 36,750 is already spent, and therefore already exposed - gone if the destination turns out to be wrong - at each one. Reviewing the requirements doc is the very first checkpoint, before any plan exists: 700 tokens invested. 1.9% of the build. Remember that number - it’s the gate. Writing the plan adds 650 more, still before a line of code: 1,350 tokens, 3.67%. Then the phases start spending real money: 8,250 after Phase 1, 17,600 after Phase 2, 24,650 after Phase 3, and 36,750 - the whole thing - after Phase 4 ships.

Divide the last row by the first and there’s the number from the top, exactly, no rounding: 36,750 / 700 = 52.5x. Catching the misread at the gate costs 1.9% of the build. Catching the identical misread after Phase 4 ships costs all of it - the opening anecdote, forty files in. The mistake never changed size. Only when someone looked at it did.

Look at how fast that curve steepens: one phase in, exposure is already 22.45% of the build - 11.79x the gate’s exposure - before the feature is even half done. The expensive part of a wrong destination was never the mistake itself. It’s every hour spent building faithfully on top of it before anyone checks.

The arithmetic is plain addition, run top to bottom. Writing the curve down at all is what does the work.

Call the review step at the top of that table the destination gate: a checkpoint placed at the single cheapest point on the entire curve, before the plan is written, before any code exists.

The gate earns its keep structurally. People miss things in a requirements doc just as they miss things in a diff, so the review itself is ordinary. The advantage is entirely in the price: review is nearly free and code is not, and that gap widens explosively the longer a misread survives undetected. Placing the check at the cheapest point on the curve is the whole technique. Nothing about the review itself has to be smarter than the reviews you’re probably already skipping.

A destination gate catches the same mistakes a code review catches, at 1.9% of the price.

Three boundaries, all worth drawing right after a number like 52.5x, because that’s exactly the moment a win like this stops getting questioned.

First: a requirements doc only catches a misread the reviewer would recognize as a misread. A reviewer who shares the writer’s blind spot, or an ask that’s genuinely too vague for anyone to catch on a read-through, sails through the gate the same as a correct doc does. The gate has no way to flag an exclusion nobody knew to question. This piece assumes a human already knows what’s out of scope and just needs somewhere cheap to write it down. The case where nobody knows yet is a separate, harder technique.

Second, a boundary this piece draws on purpose: it says nothing about why a long single-window build degrades, why accuracy sags as a window fills. That mechanism, the context rot argument, already has its own citations and its own arithmetic in The Relay, Not the Window and Treat the Plan File as External Memory, and re-deriving it here would only duplicate them. This piece assumes the relay works perfectly and asks a different question: what happens when the thing being relayed was wrong on line one.

Third: readers with a traditional software-engineering background have probably already thought of this piece’s grandparent - Barry Boehm’s cost-of-change curve (Software Engineering Economics, 1981), backed up in Boehm and Basili’s “Software Defect Reduction Top 10 List” (IEEE Computer, January 2001), which found a defect fixed after delivery cost roughly 100 times what fixing the same defect at the requirements stage cost, on the waterfall-era projects the study measured. It’s worth naming, and worth hedging exactly as hard as the source is: the multiplier is contested for iterative, non-waterfall teams (see the Mountain Goat Software critique, and the empirical revisit “Are delayed issues harder to resolve?” by Menzies, Nichols, Layman, and Shull, Empirical Software Engineering, 2017). It’s also worth keeping separate from this piece’s own 52.5x - different eras, different defect classes, no shared units. Two numbers landing in the same order of magnitude is a coincidence worth a raised eyebrow. Neither measurement props up the other.

And the anti-hype, plainly: none of this makes the agent smarter. It doesn’t guarantee the requirements doc itself is complete - see the first limit above. And the strictest version of the same idea, EARS notation (a rigid if/when/the-system-shall grammar that removes even more ambiguity than a free-form user story), was deliberately not adopted here, because Team Invitations didn’t need that much ceremony to be understood correctly.

A destination gate catches a documented misread cheaply. It was never going to catch an undocumented one, or write the document for you.

A handful of other pieces on this blog work the same territory from different angles, worth naming so this one doesn’t quietly re-argue their point. Bake the acceptance test into the spec hardens what counts as done for a destination that’s already right; this piece is about whether that destination was the right one to aim for. A permissions gate stops an irreversible tool call, a destructive database operation, before it happens. Building the wrong thing was never a disallowed action, so that gate never fires on it. A handoff file carries state across one compaction boundary near a window’s practical end; the two documents here get written before any work starts, and the requirements doc stays fixed for the whole build instead of getting rewritten at every restart. Cache the explore caches where things live in the repo; this piece is about what correct looks like and what order to build it in, a different axis of context entirely. Deterministic context loads files that already exist, in one shot; the two documents here don’t exist yet, and a human has to author them before anything gets loaded. And hierarchical context splits a standing, repo-wide rules file by directory; the requirements doc and the plan are per-feature and get thrown away once the feature ships.

Six techniques, six different jobs - and not one of them asks whether the destination underneath was right.

This is ceremony, and ceremony costs. For a one-file bugfix or a rename, writing a requirements contract and a phased plan is theater - the documents take longer than the change, and the agent never needed them.

The tell isn’t the size of the build. It’s the ambiguity of the ask and the blast radius of getting it wrong. A big, boring, well-understood migration - touch these 40 files the same mechanical way - doesn’t need a destination gate; there’s no destination to misread, only a journey to execute, and Treat the Plan File as External Memory already covers that case on its own. A small feature with real ambiguity in it - who exactly counts as “a teammate,” what “expires” means for a link that’s already been clicked - earns the gate even if it fits in one sitting, because a misread’s cost grows with how much gets built on top of a wrong assumption before anyone checks it.

Reach for the two documents when the ask is ambiguous or the mistake is expensive to unwind. Size alone never earns them.

Every section above points back to one row of the cost-curve table. The requirements-doc review is the top row: 700 tokens, 1.9% of the build, the destination gate doing its one job. Skipping it and finding out at Phase 4 is the bottom row: 36,750 tokens, 100%, the opening anecdote’s forty files. Same mistake. The only variable that moved between those two rows was when someone looked.

That leaves the gate’s own blind spot as the open question this piece didn’t answer. A requirements doc only catches the exclusion the writer thought to write down, and a destination gate only catches what the reviewer thought to check. What surfaces the exclusion nobody thought of, before it’s a destination anyone commits to, is a different technique, and it’s already on this site: Interview me before you build, where the value is the interrogation that produces the document. This piece assumed a human already knows what’s out of scope and just needs a cheap place to write it down. The next one is the harder case, where nobody knows yet.

The 52.5x this piece is about only shows up once a destination gets checked. What checks the destination nobody thought to write down is the next open question.

About the numbers. The opening anecdote is a composite of the failure mode, told for stakes; it is not a logged session. The “eight words” and “two hours” figures in the requirements-doc section are illustrative the same way, not measurements. The four phases’ file counts, diff-line counts, and the two documents’ token sizes (700 for requirements.md, 650 for plan.md) are toy values, invented for traceability and sized to be a plausible mid-size feature matching the four phases named on this page - not measured from any real file. The 2,000-tokens-per-file-read and 15-tokens-per-diff-line rates are stated assumptions, not measurements; the per-file rate matches the convention this blog already uses elsewhere, and the per-diff-line rate is introduced here. Every other number here - the six phase and checkpoint loads, the six percentages, the 52.5x ratio, and the 11.79x jump after Phase 1 - is exact arithmetic derived from those inputs and checked against an independent script before publishing. The Boehm citation is quoted and dated: the paper’s title, authors, venue, and finding were verified directly, described only in the terms the source itself uses, and kept structurally separate from this piece’s own 52.5x - unrelated measurements, a coincidence of order of magnitude at most.

For the per-tool mechanics, see Rules for the requirements doc as committed context, Plan mode for proposing the build order before any code, and Subagents for the isolated-context pattern the relay pieces cover in full.