Requirements That Survive Contact With Reality
Most requirement documents fail in week three — not because nobody read them, but because they describe screens instead of decisions.
The lead developer opened the signed requirements document on a Tuesday in sprint two and searched for one sentence: what happens when the purchase order arrives before the advance ship notice. The mockups showed a clean receive screen. The integration diagram showed two arrows. Nobody had written whether the warehouse clerk waits, overrides, or receives against expected quantity. That gap is not a communication failure. It is a missing decision record — and it is exactly where most builds begin to argue with the document that was supposed to prevent argument.
Week three is when contact with reality starts. Data models meet production feeds. Role names meet the identity provider someone renamed last quarter. The happy path from the workshop meets partial shipments, retries, and the spreadsheet someone still maintains because nobody specified the automation. Industry surveys still rank inaccurate requirements gathering among the top causes of project failure. Documents fail all the time. Teams keep writing the same kind and expecting a different week three.
When the Signed Document Goes Quiet
Sign-off is the wrong finish line. Approval means stakeholders agreed on intent at a point in time. It does not mean the artifact contains what a builder needs when the sponsor is in another meeting and the ASN file is six hours late.
On day fifteen, developers are not rereading vision statements. They want constraints they can implement without a phone call: who owns data when two systems disagree, what happens on timeout, who may override a hold, what the audit trail must show. When those answers live only in someone's memory from a workshop, the document has gone quiet. The team improvises. Improvisation works until QA asks how to prove the behaviour was correct.
The pattern repeats wherever formal sign-off substitutes for encoded decisions — gaps between what was documented, what stakeholders said they wanted, and what shipped still track with worse cost and schedule outcomes. The document existed. The decisions did not.
The Week-Three Gap — Screens Without Failure Modes
Most failing requirements documents are thorough about what the user sees and thin about what the system must decide when reality diverges.
Picture a retail inventory program rolling out to twelve stores. The business requirements document specifies receive screens, allocation rules on paper, and nightly sync to the central warehouse system. Sprint two starts. A store receives a PO line for forty units. The ASN says thirty-five. The central system has already allocated twenty of those thirty-five to ecommerce orders. The screen spec does not say whether the clerk can receive forty against a thirty-five-unit ASN, whether partial receipt creates a backorder automatically, or which system's quantity wins when the nightly job runs at 2:00 a.m. versus when the clerk acts at 10:00 a.m.
None of that is exotic edge-case thinking. It is Tuesday.
Research on requirements specification quality across dozens of projects found a pattern teams that measure completeness by page count keep missing: when Section 1 — purpose, scope, operational context — was thin while function descriptions were exhaustive, projects tended towards cost overruns. Balanced documents, where context and features received proportionate attention, clustered with healthier outcomes. Thick feature catalogues without context are not complete.
They are detailed fiction about a world where integrations are on time and master data stays still.
That is the Week-Three Gap: the distance between specified screens and unspecified decisions.
The Surviving Requirements Stack
Requirements that survive contact with reality separate three layers that age at different speeds. Mix them in one paragraph and every edit feels like reopening contract negotiations.
Layer 1 — Intent (negotiable). User stories or thin capability statements belong here. Official agile guidance describes them as negotiable expressions of intent — placeholders for conversation, elaborated just in time, not contracts for specific functionality. They answer who benefits and what outcome matters. They should stay small enough to split when learning arrives.
Layer 2 — Decision records (amendable, but explicit). Cross-cutting rules that survive multiple stories live here: integration timing, data precedence, override authority, failure handling. These are the sentences developers search for in week three. They should be atomic and unambiguous — one decision per record, written so two engineers would implement the same behaviour. When the org chart changes, you amend the record and trace who approved the change. You do not bury the rule inside a story that was closed last sprint.
Layer 3 — Verification hooks (testable). Each decision record earns at least one check a tester can run without interpreting sponsor intent. Systems engineering practice distinguishes verification (is the requirement well-formed and provable?) from validation (does it communicate the right intent?). Builders live in verification during the sprint. "The clerk sees a warning" is not a hook. "Given ASN quantity 35 and PO quantity 40, receive is blocked unless the user holds Inventory Override role, and the attempt is logged with both quantities" is a hook.
Here is the same retail receive feature written across the stack.
Intent: As a store receiver, I need to record inbound stock against today's shipments so on-hand counts are trustworthy for allocation.
Decision record DR-INV-014: When PO quantity exceeds ASN quantity for the same line, receive is permitted only up to ASN quantity unless an override is granted. Override requires role INV_OVERRIDE. Central allocation quantities are authoritative until the nightly sync completes; clerk actions before sync must not reduce allocated ecommerce stock.
Verification hook: Test case INV-TC-09 — PO 40 / ASN 35 / central allocated 20 — assert receive capped at 35 without override; assert override to 40 writes audit row with both quantities and user id.
The story stays negotiable. The decision survives sprint boundaries. The test settles arguments without reopening the workshop.
Practitioner writing on agile mistakes puts the distinction plainly: use stories when exploring value; use specifications when behaviour must be verified under complexity. The stack is how you keep both without inflating every story into a miniature requirements tomb.
Writing Decision Records Builders Will Open
A decision record is not a paragraph in a slide deck. It is a requirement in the narrow sense systems standards use: necessary, feasible, verifiable, and stated once.
Start from the failure mode, not the screen. Ask what the system must do when the feed is late, the field is null, or the role is missing. If the answer is "the user calls helpdesk," write that as a temporary workaround and mark the automation gap explicitly. Silent manual workarounds are how requirements documents lie while staying technically true.
Complete means enough detail for the next task to continue — not every pixel. Testable means a reviewer can determine pass or fail without debating what "fast" or "user-friendly" meant in October. Unambiguous means one interpretation for implementers and QA. If you need the word "appropriate," replace it with a rule.
Section 1 of the document — scope, systems in play, timing windows, authority sources — deserves disproportionate care. When builders hit week three, they are reconciling timing and ownership, not rereading screen labels.
Link stories to decision records and, where needed, to focused specs for complex UI states. The story remains easy to discard when priorities shift. The decision record remains findable when they do not.
What to Stop Doing Next Cycle
Three habits keep producing documents that go quiet.
Stop embedding full specifications inside user stories. Bloated stories cannot be split, discarded, or renegotiated without losing the only copy of a constraint.
Stop treating acceptance criteria as the full rule set. Criteria verify an increment; they do not replace decision records for rules that cross five increments.
Stop freezing the document at kickoff. Contact with reality produces new decisions. The artifact needs a visible amendment path — version, author, date — not change-control theatre that pushes edits into hallway conversations.
The goal is not a longer business requirements document. It is a thinner document with thicker decision records and tests attached to the places builders actually look when the ASN is late.
Write the screen in week one. Write the decision before week three. Attach the test that ends the argument.