From a Vague Request to an AI-Executable Requirement

An abstract technical work packet with checked items

A coding agent can finish a vague request. It cannot know whether it finished the right thing.1

A requirements package is not the only fix, but it is one of the most reliable ways to harness how an agent behaves: it gives the work an outcome, boundaries, and proof instead of leaving the agent to guess. This part is a tutorial for writing one.

We will use a single feature across the whole series: Tablewait, a restaurant waitlist app, needs waitlist auto-promote — when a host frees a table, the next eligible party is automatically offered the table on a short hold. By the end of this part you will have produced requirements.md, the first of six delivery documents.

Step 1: Start from the raw request

Here is what the request usually looks like:

When a table opens up, send it to the next person on the waitlist.

It sounds small. It leaves the important questions open:

  • How long does the next party have to respond?
  • What if they do not answer, or decline?
  • Can two tables freeing at once offer the same slot twice?
  • Who is eligible — anyone, or only parties that fit the table?

An agent will answer these by guessing. The guesses might compile. They can still be wrong.

Step 2: Generate the package from a template

Do not write the package from a blank page, and do not let the agent invent a new shape on every run. Give it one generative prompt plus the template — the requirements.md template is the shape to fill.

Draft requirements.md for this feature.
 
Use requirements.md as the exact template:
keep its sections: feature summary, current vs desired boundary, in scope,
out of scope, roles and permissions, acceptance criteria numbered AC1, AC2
and so on, Given/Then examples, and constraints.
 
Read first:
- the raw request below
- the repository (models, services, permissions); cite a file for every fact
 
Raw request:
"When a table opens up, send it to the next person on the waitlist."
 
Fill only what the request and the code support. Mark anything you must
assume as an OPEN DECISION for a human to resolve. Do not invent product
behaviour.

The prompt is the instruction; the template is the shape. Together they make the output consistent enough to review. The draft it returns looks like this:

# Requirements — Waitlist Auto-Promote
 
## Feature summary
 
**Tablewait** is a restaurant reservation & waitlist app. Diners join a restaurant's waitlist;
hosts manage the floor and tables. Today, when a table frees, a host manually scans the
waitlist and texts the next party. It is slow and, under pressure, double-books.
 
**Waitlist Auto-Promote** automates this. When a host marks a table available, the system
selects the next eligible waiting party and creates a 5-minute **HOLD** offering that table. If
the party accepts, they are seated; if they decline or the hold expires, the system
auto-rolls the offer to the next eligible party. A table is never on hold for two parties at
once.
 
## Current vs desired boundary
 
**Current state**
- A waitlist entry (party) has: `id, restaurantId, size, phone, joinedAt, status (waiting|seated|removed)`.
- A table has: `id, restaurantId, capacity, status (occupied|available)`.
- Hosts manually scan and text the next party. Slow; double-books under load.
- Notifications go through the existing `NotificationService` (SMS + in-app).
- Only hosts change table status. Only parties on that restaurant's waitlist are eligible.
 
## Out of scope (non-goals)
- No changes to reservations (future-dated bookings are untouched).
- No new notification channel — reuse `NotificationService` (SMS + in-app) only.
- No priority/VIP queue, no re-ordering of the waitlist in this change.
- No changes to how parties join or leave the waitlist.
 
## Acceptance criteria
 
- **AC1** Marking a table available creates exactly one active hold for the next eligible party.
- **AC2** Accepting an active hold seats the party and marks the table occupied.
- **AC3** An unanswered hold expires after 5 minutes and rolls to the next eligible party.
- **AC4** A declined hold immediately rolls to the next eligible party.
- **AC5** Two tables freeing at the same time never double-book one table and never create two active holds for one table.
- **AC6** A party already seated or removed is skipped during selection.
- **AC7** With the `waitlist_auto_promote` flag OFF, behaviour is identical to today's manual flow.
- **AC8** Re-marking an already-held table available does not create a second hold (idempotent).

The syntax does not matter. The decisions do. A good package says what must change, what must not change, and how the team will know it worked.

You do not have to write the template alone

The template is an artifact too, and you can build it with the agent. Brainstorm the sections, push back on what is missing, and ask it to write and revise requirements.md until it fits how your team works. Treat it as a conversation, not a form you fill in by hand.

I want a requirements.md template for AI-assisted work.
 
Ask me what a good requirement must settle before an agent writes code.
Propose the sections, challenge any that overlap, and draft the template.
Then show me one short example filled in.

Once you agree on the shape, save the file and freeze it for the run. The agent helped design the template. It does not change the template while it fills it in. Improve it between runs, when a review shows a section was missing or never used.

Step 3: Ask an agent to find gaps — not to code

Do not open with "build this." Open with "tell me what the package does not settle."

Read requirements.md and inspect the repository.
 
Do not edit files.
 
Return exactly three sections:
1. Confirmed behaviour — cite the file path and symbol for each fact.
2. Open decisions — list only what the requirements do not settle.
3. Smallest safe boundary — affected systems, existing contracts, risks.
 
Do not invent product behaviour. If a fact is not in the package or the
code, mark it as unknown.

This prompt has a narrow job: make the agent useful before it becomes powerful. If it discovers that two tables can free at the same instant, that is an open decision for you, not a licence to invent locking behaviour.

Step 4: Resolve the open decisions yourself

The agent surfaces unknowns. A person settles them. For auto-promote, the decisions that matter:

  • Hold length: 5 minutes, fixed for this change.
  • Eligibility: first-come order, party size must fit the table capacity, status must be waiting.
  • Concurrency: a table may hold for only one party at a time.
  • Flag-off behaviour: identical to today's manual flow.

Write each answer back into the package. The agent should never silently decide these.

What the finished requirements.md looks like

Put together, the reviewed document has nine sections, in this order. The first eight are what the template in Step 2 asks the agent to fill. The last one is what this step adds:

# Requirements — Waitlist Auto-Promote
 
## Feature summary
 
## Current vs desired boundary
 
## In scope
 
## Out of scope (non-goals)
 
## Roles & permissions
 
## Acceptance criteria
 
## Given / Then examples
 
## Constraints
 
## Resolved open decisions

"Resolved open decisions" holds the answers you wrote back into the package. The agent never fills it in on its own.

Step 5: Enforce the shape with a script, not a vibe

An agent can help draft the package. A script should guarantee the required sections exist.

// scripts/check-requirements.ts
import { readFileSync } from "node:fs";
 
const doc = readFileSync("requirements.md", "utf8");
const required = [
  "## Feature summary",
  "## Out of scope",
  "## Constraints",
  "## Acceptance criteria",
];
 
for (const heading of required) {
  if (!doc.includes(heading)) {
    throw new Error(`requirements.md is missing: ${heading}`);
  }
}
 
if (!/\*\*AC\d+\*\*/.test(doc)) {
  throw new Error("requirements.md has no numbered acceptance criteria");
}

This is intentionally boring. It does not judge whether an acceptance check is good; it stops a pull request from claiming one exists when it does not.

Keep it smaller than the change

A requirements package should be shorter than the feature it governs. For a one-file rename, write a precise prompt instead. For a change that spans a service, a scheduler, and a UI — like auto-promote — write the package, and add detail only where an agent could make a costly guess.

The goal is fewer decisions.

What else a requirements document can contain

Tablewait's template has nine sections. A bigger change may need more. Larger teams use fuller documents, such as a business requirements document (BRD) or a software requirements specification. Add what the change needs and skip the rest.2

  • Background and objectives: the problem, and the business goal it serves.
  • Stakeholders: who asked for it, who uses it, and who approves it.
  • User scenarios: who does what, in order of priority, as plain steps or Given/When/Then.
  • Functional requirements: numbered statements of what the system must do. One common format is EARS: "When a host frees a table, the system shall offer it to the next eligible party."
  • Non-functional requirements: limits on performance, security, privacy, accessibility, reliability, and compliance.
  • Key entities: the business things involved (party, table, waitlist), without implementation detail.
  • Edge cases: the unusual and error situations the change must handle.
  • Assumptions and dependencies: what you take as true, and which systems or teams you rely on.
  • Success criteria: measurable outcomes that do not depend on the technology, such as "hosts no longer text parties by hand".

Notice what is still missing: a data model, an API, a migration. Those belong in the design, which is the next part.

The package you just built

requirements.md is now the first of six documents. The next part turns it into a solution design before any code is written.

Download this stage's package (.zip) — the requirements artifact and the pack README. The complete pack is linked from the series guide and the final part.

Footnotes

  1. This holds for the coding agents available in early 2026. Newer models will likely get better at it, especially as software factories are refined and coding agents improve. The need to define the outcome clearly will not go away, but the amount of guessing an agent does on its own should shrink. ↩

  2. This list draws on BRD templates such as Microsoft's BRD template, the requirements clauses of ISO/IEC/IEEE 29148, the Spec Kit spec template, and the EARS format used by Kiro. ↩