This independently written lesson draws on public sources. It is not an official MEGA lesson. QueueCare and all specifications below are original teaching examples. Continue with the repair-clinic booking product from the previous lesson, or substitute a comparable workflow in your own application.
Learning goals
- Turn a desired user result into requirements with observable behavior.
- Supply relevant context without burying the decision in documents.
- Decompose work around dependencies and verifiable slices.
- Define evaluation before an agent starts implementation.
Intent needs an observable boundary
Intent describes the change you want in a person's experience. A requirement states a behavior the product must support. A specification resolves enough ambiguity that someone can implement and evaluate that behavior. These serve different purposes. A beautifully detailed specification can still implement an unhelpful requirement.
For QueueCare, the intent is to help residents release appointments they cannot attend. A requirement is that a resident can cancel from a reminder. A specification must answer who may use the link, when cancellation is allowed, what status appears afterward, and what happens on a repeat request. “Add a cancel button” leaves all of those questions open.
Kent recommends establishing agreement about the problem and completion conditions before giving commands to an agent. Read the shared-understanding section of You Own the Outcome. We can operationalize that advice with a short brief that includes the person, difficulty, desired behavior, exclusions, unknowns, and evidence needed for acceptance.
Do not force every unknown into a guessed answer. Some uncertainties require codebase inspection; others require a product decision. Tell the agent which questions it may resolve through local investigation and which require an explicit choice. For example, it may discover the existing booking status names. It should not invent a refund policy because a cancellation screen needs copy.
Context should explain the constraints
Useful context narrows the space of acceptable solutions. For our reminder task, provide the current booking lifecycle, the existing identity boundary, approved message provider, local-time policy, and commands that verify the relevant flow. Add the product decision record so the agent knows why conversational replies are excluded.
A pile of files is not equivalent to understanding. Explain which source governs each question. The database schema describes stored fields, while the service policy describes when cancellation is allowed. When they disagree, the conflict itself needs attention. Asking the model to silently reconcile them hides an important decision.
Supply examples near boundaries. A booking at 00:30 local time, a booking canceled while a reminder is queued, and an already-used cancellation link will reveal more ambiguity than ten ordinary daytime bookings. Keep real personal information out of fixtures. Invent residents and addresses, and preserve only the structural conditions needed to test behavior.
Separate observations from proposals. “The current handler returns 500 after a repeat cancellation” is an observation. “Repeat cancellation should show the original result” is a proposed contract. Labeling them prevents the agent from preserving a defect merely because it appears in the existing code.
Requirements should survive implementation changes
An implementation-independent requirement describes what a user or public caller can observe. “The cancel handler calls updateBooking once” constrains internals. “A repeated authorized cancellation leaves one canceled booking and returns a stable confirmation” states the behavior that matters.
Kent's testing article shows why coupling checks to internal state can both break during harmless refactoring and miss broken user interactions. Read Testing Implementation Details. Apply the same reasoning when writing requirements: specify the boundary contract before choosing internal functions.
A good requirement has a precondition, an action, an expected result, and an explicit forbidden effect where needed. Avoid subjective adjectives such as seamless or secure without describing the relevant behavior. For this exercise, security means a resident cannot cancel another resident's booking by changing a visible identifier, and a token cannot expose booking details outside its intended scope.
Performance requirements also need context. “Fast” is not evaluable. “The confirmation appears within two seconds in the agreed test environment with the provider stub responding immediately” is inspectable, but proves only that environment. Production expectations require separate observation under representative conditions.
Worked example: an agent-ready specification
The following document is illustrative and API-neutral. It does not imply a production-ready token design.
Intent: Let residents release unwanted appointments quickly.
Scope: Cancellation from the existing reminder channel.
Context: Booking service owns status; scheduler reads that status.
R1: Valid cancellation changes confirmed -> canceled.
R2: Repeat cancellation returns the same canceled outcome.
R3: Wrong, expired, or altered authorization changes nothing.
R4: A canceled booking is ineligible for future reminders.
R5: Resident sees local appointment details before confirming.
R6: Record a cancellation event without storing the raw token.
Excluded: Refunds, transfers, rescheduling, automatic cancellation.
Unknown: Which existing authorization primitive meets R3?
Authority: Inspect existing primitives; propose options if none fits.
Evidence: User journey checks, service checks, event inspection.Now decompose the work. First inspect the booking and authorization boundaries and report conflicts. Next implement one cancellation path through the existing interface, service, and storage. Then connect reminder eligibility and verify the canceled case. Finally inspect the event and user message together.
This order resolves the most consequential uncertainty before creating UI that depends on it. It also produces useful intermediate evidence. Splitting work into “frontend,” “backend,” and “tests” may be convenient, but a completed frontend alone cannot prove cancellation works. Slices should cross the smallest set of boundaries needed to demonstrate a coherent behavior.
Expected results are concrete. Starting with booking B17 confirmed, an authorized action yields canceled status and one durable cancellation record. Repeating it yields the same user outcome without a second state transition. Changing the authorization value yields no booking mutation and no disclosure of B17. A scheduler scan after cancellation must exclude B17.
A race remains: a worker could read confirmed status just before cancellation. The specification has exposed the issue but has not solved it. Ask the agent to identify the dispatch commitment point and propose an enforceable rule. “No future reminders” is too vague until the team decides what counts as already dispatched.
Evaluation is part of the task
Before implementation, give each requirement a check and a limitation. A browser interaction checks the visible path. A service check exercises authorization and repeated requests. A concurrency fixture examines the cancellation race. A provider stub shows the requested payload but cannot establish real inbox delivery.
Ask the agent to return the changed behavior, evidence, untested conditions, and remaining decisions. Evaluation should compare the artifact with the requirements, rather than compare the agent's final summary with its own plan. An agent can confidently describe a requirement it never exercised.
Failure modes
- Treating detailed instructions as proof of a well-chosen outcome.
- Mixing current behavior and desired behavior in one unlabeled paragraph.
- Decomposing by file ownership without testing integration boundaries.
- Leaving authorization, timing, or repeated actions implicit.
- Asking for evaluation only after the implementation makes it inconvenient.
Practice
Extend the specification with rescheduling, but keep cancellation behavior intact. Write six observable requirements, three explicit exclusions, and two unresolved product questions. Define a dependency order and one acceptance check per requirement.
Acceptance requires a valid reschedule, no available replacement, repeat submission, unauthorized submission, reminder timing, and the original slot's availability. Describe which system owns the authoritative appointment time.
A good answer treats rescheduling as a state transition with a failure policy. It does not cancel the original booking before knowing a replacement can be secured unless that loss is an explicit product choice. Its checks observe both the original and replacement slots. It also distinguishes an evaluation fixture from evidence of production delivery.
Check your understanding
- Why is “call updateBooking once” a weak product requirement? Answer: It specifies an internal technique and can miss incorrect visible behavior.
- Should an agent guess a missing cancellation policy? Answer: No. It should surface the decision with evidence and options.
- Why define evaluation early? Answer: It exposes ambiguous requirements before code makes them expensive to change.