D3 · Inputs, Outputs and Contracts

This domain is worth 16% of the mock — roughly 8 of 50 items. It tests whether you can make a workflow predictable by defining, for every step, exactly what goes in and exactly what comes out. Decomposition (Domain 2) gives you steps; this domain gives each step a contract so the steps fit together reliably and a colleague running the workflow gets the same result you do.

What you need to know

A contract for a step specifies five things: the named inputs it consumes, which of them are required versus optional, the output shape it must produce (a schema, a template, or fixed fields), the acceptance criteria that define a good output, and the behaviour on missing or malformed input. Contracts turn “it usually works” into “it works predictably” because every step knows what it can rely on receiving and what it is obliged to return. The single most common source of workflow flakiness is an undefined output shape feeding into the next step, or an unhandled missing input that the model silently guesses around.

Learning objectives

By the end of this page you should be able to:

1. Specify a step’s named inputs and mark each required or optional.
2. Define an output as a schema, template or fixed field set that downstream steps can rely on.
3. Write acceptance criteria that make “good output” checkable rather than subjective.
4. Decide what a step does when a required input is missing or malformed — ask, default, or fail.
5. Design the handoff between two steps so the producer’s output exactly matches the consumer’s expected input.

3.1 The five parts of a step contract

CONTRACT for step "Categorise invoice"
  INPUTS         invoice_text (required), known_categories (required),
                 prior_vendor_map (optional)
  OUTPUT         { vendor, amount, currency, category, confidence }  (JSON)
  ACCEPTANCE     category ∈ known_categories; amount is a number;
                 confidence in [0,1]; every field present
  ON MISSING     if invoice_text absent → FAIL with "no invoice supplied"
                 if known_categories absent → FAIL (cannot categorise safely)

3.2 Named inputs and required fields

Every step should declare its inputs by name and mark each required or optional. This matters most at handoffs: if step 2 requires a total field, step 1’s contract must promise to produce it.

A frequent bug: a field that is actually required is treated as optional, so when it is missing the model fabricates a plausible value. Declaring it required with an explicit missing-input rule stops that.

3.3 Output as a schema, template or fixed fields

The output shape is the contract’s spine because it is what the next step depends on. Choose the tightest shape the consumer needs.

{
  "vendor": "string",
  "amount": 0.0,
  "currency": "USD",
  "category": "one of the supplied categories",
  "confidence": 0.0
}

## Weekly digest — {week}
### Highlights (max 5 bullets)
### Risks (each: risk — owner — mitigation)
### Decisions needed

Return exactly these three lines:
CATEGORY: <one of the list>
AMOUNT: <number>
NEEDS_REVIEW: <yes|no>

The rule: match the output shape to the consumer. A human reader wants a template; a parser wants a schema; a quick human triage wants fixed fields.

3.4 Acceptance criteria — making “good” checkable

Acceptance criteria turn a subjective “is this good?” into a checklist a person or a later step can apply. Good criteria are observable.

Acceptance criteria are also what the draft-then-critique step and the human review gate check against — so writing them here pays off in Domain 5.

3.5 Behaviour on missing or malformed input

The most dangerous default in any workflow is silent guessing. When a required input is absent, a step must do one of three defined things — never invent data.

Required input missing?
│
├─ Can a human quickly supply it?  ─► ASK   (route back / flag for input)
│
├─ Is there a safe, explicit default? ─► DEFAULT  (and mark it as defaulted)
│
└─ Otherwise ─► FAIL LOUDLY  (stop, return a clear reason; do not fabricate)

The wrong answer is a fourth option nobody writes down: guess. A model asked to categorise an invoice with no category list will happily invent categories — plausible, wrong, and undetectable downstream.

3.6 Designing the handoff between steps

A workflow is a chain of contracts, and it only holds if each producer’s output contract matches the next consumer’s input contract.

Step 1  OUTPUT: { scope[], dates[], constraints[] }
                 │  must match  ▼
Step 2  INPUT (required): scope[], dates[]     ← consumed
        INPUT (optional): constraints[]        ← used if present
        OUTPUT: { timeline, pricing_table }
                 │  must match  ▼
Step 3  INPUT (required): timeline, pricing_table

When you add or change a step, re-check both edges: does it get what it needs, and does it produce what the next step requires? Most “the workflow broke after I tweaked step 2” bugs are a contract mismatch at one of these edges.

3.7 Contracts as living documentation

A written contract is also the thing that lets a colleague run your workflow. The contract is the interface: “give it these named inputs, expect this output shape, it is done when these criteria hold.” That is why this domain feeds directly into repeatability (Domain 6) — an undocumented step lives only in your head and cannot be handed over, versioned, or improved.

Decision framework

The CONTRACT card — before you build a step, fill in one card. If any row is blank, the step is not ready.

The card’s discipline is that Missing and Handoff are mandatory rows. Most flaky workflows have those two blank.

Common mistakes

Scenario challenge

Scenario. Lena automated a step that reads customer feedback emails and outputs a structured record for the CRM: sentiment, product area, and a one-line summary. It worked for weeks. Then two problems appeared. First, a colleague who took over the workflow got different-looking output — sometimes a paragraph, sometimes bullet points, occasionally a sentiment value like “mostly positive” instead of the expected positive/neutral/negative. Second, when an email arrives with no clear product mention, the step confidently outputs a product area anyway — and those guessed values have been polluting the CRM. Lena’s instinct is to rewrite the prompt to be “clearer”.

Expert reasoning trace.

1. Diagnose problem one as an output-shape failure. The output has no fixed schema, so the model varies format and even invents new sentiment values. A clearer prose prompt will not fix this reliably — the contract has no pinned output shape. The fix is to specify a schema: sentiment ∈ {positive, neutral, negative}, product_area ∈ <allowed list>, summary as one line, and to demand only the JSON.
2. Diagnose problem two as a missing-input failure. The step treats product_area as always-derivable, so when the email lacks a clear product it guesses — the forbidden fourth option. The contract must define the missing-input behaviour: if no product can be identified with confidence, output product_area: "unknown" and needs_review: yes (a marked default plus a flag), never a fabricated area.
3. Reject the “clearer prompt” reflex. The problem is not persuasion; it is an under-specified contract. Rewording might reduce format drift briefly but will not constrain the value set or handle the missing product, and the colleague will still get drift because the shape is not pinned.
4. Fix the handoff. The CRM (the consumer) requires an enumerated sentiment and a valid or explicitly-unknown product area. The producer’s output contract must promise exactly that enum and that unknown-handling, so the CRM never receives a free-text sentiment again.
5. Add acceptance criteria for review. “Every record has all fields; sentiment is one of three values; product_area is from the list or ‘unknown’; guessed areas are flagged.” Now a sampling check (Domain 5) can catch violations, and the contract is documentation the colleague can follow to get identical output.

The decision: replace the vague prompt with a defined output schema (enumerated values, only-JSON) and an explicit missing-input rule (unknown + needs_review, never guess), matched to the CRM’s required input, plus observable acceptance criteria — not a “clearer” prose prompt. Both symptoms — format drift across users and polluted product areas — trace to the two contract rows people most often leave blank: output shape and missing-input behaviour.

Assessment traps

Practice questions

Each item states how many responses to select. Commit before revealing.

Key takeaways

• Every step is a contract: named inputs, required vs optional, output shape, acceptance criteria, and missing-input behaviour.
• Pin the output shape to the consumer — schema for machines, template for readers, fixed fields for quick triage — and return only that shape for parseable outputs.
• Acceptance criteria must be observable and checkable, not “high quality”; they are what critique steps and human gates verify against.
• On missing required input, ask, default-and-mark, or fail loudly — never let the model guess.
• A workflow is a chain of contracts: after editing a step, re-check both handoff edges.
• The written contract is the interface that lets a colleague run, version and improve the workflow — the bridge to Domains 5 and 6.
• The two rows most often left blank — output shape and missing-input behaviour — are the usual cause of flaky workflows.