Turn a Request into a Delivery Contract

In this chapter

• Separate a business outcome from a model capability.
• Write measurable acceptance checks with explicit exclusions.
• Create a deterministic baseline before introducing generation.

Start with a decision, not a chatbot

A facilities coordinator asks for an assistant that handles office requests. That is an aspiration, not an implementation contract. Ask who creates a request, who authorizes it and what currently goes wrong. For Relay Room, staff struggle to describe rooms and equipment, while coordinators waste time requesting missing details. The first useful outcome is a complete, reviewable draft, not an autonomous agent with unrestricted system access.

Write a one-page delivery brief with five headings: audience, useful outcome, permitted actions, excluded actions and evidence. A permitted action is suggesting a clearer description based on a supplied note. An excluded action is placing an order. Choose a measurable outcome such as eight of ten synthetic requests producing drafts that contain a room, an allowed category and a meaningful summary. Treat that small fixture result as a lab acceptance threshold, not a claim about future users.

Make the first baseline executable

A deterministic gate establishes the minimum information a request needs. This example returns missing fields rather than inventing them. It does not diagnose equipment faults or classify emergencies. Unsupported categories require a coordinator, and real safety incidents must use the organization's established emergency process. Run the snippet as delivery_contract.py. Both assertions should pass; the second result intentionally names a missing room.

CATEGORIES = {"furniture", "cleaning", "presentation-equipment"}

def draft_readiness(request):
    missing = [name for name in ("room", "summary")
               if not isinstance(request.get(name), str)
               or not request[name].strip()]
    if type(request.get("category")) is not str or request["category"] not in CATEGORIES:
        missing.append("supported category")
    return {"ready_for_review": not missing,
            "missing": missing, "can_submit": False}

complete = {"room": "Cedar 204", "summary": "Projector cable is missing",
            "category": "presentation-equipment"}
assert draft_readiness(complete)["ready_for_review"] is True
assert draft_readiness({**complete, "room": " "})["missing"] == ["room"]
print(draft_readiness(complete))

Recognize a misleading success

The failure mode is a polished answer with no accountable outcome. A fluent paragraph may conceal an invented room number, and a high satisfaction score can hide unauthorized submissions. Keep content quality, safety boundaries and system reliability as separate columns in the acceptance matrix. Include an owner and a test fixture for every promise. If a requirement has no observable check, narrow it until a reviewer can decide whether it passed.

Preserve unresolved decisions rather than quietly guessing. If the coordinator has not agreed which rooms belong to which site, record that as an integration question and use labeled synthetic identifiers for the lab. A first release can still deliver a useful draft while explicitly leaving ticket submission manual. This makes the boundary visible to the business owner and prevents a demonstration shortcut from becoming an accidental production commitment.

Write the Relay Room acceptance matrix

• Create ten synthetic requests: six complete, two missing rooms, one blank summary and one unsupported category.
• Run each through draft_readiness and record expected versus actual outcomes.
• Add a separate acceptance row stating that every draft remains unable to submit until a human reviews it.

Expected checks

• Exactly six fixtures are ready for review.
• Every response has can_submit set to false.
• The delivery brief lists excluded actions and the named reviewer.

Check your understanding

Which acceptance criterion best establishes a useful first release?

• The assistant answers every question confidently.
• For the ten agreed fixtures, drafts preserve supplied facts and expose missing fields without submitting tickets.
• The interface contains a chat window and a model selector.

Official tools & further reading

• Python unittest: executable checks