# Write good Expectations

An Expectation is one plain statement of what a good answer does, such as "marks a double charge as urgent". Facet checks every new version against every Expectation, and a version goes live only when they pass. Good Expectations are the best way to get a Task that does what you mean.

Facet drafts the first ones from your description. This page is for reviewing them and adding your own.

## One behavior per statement

Each Expectation should be something you could check by reading one answer.

| Instead of | Write |
|---|---|
| Handles tickets well | Picks billing, bug or account for every ticket |
| Is accurate and concise | Copies the invoice total exactly as written |
| Doesn't make mistakes with urgency | Marks a ticket urgent when the customer can't log in |
| Good tone | Never promises a refund |

Split a statement that has "and" in it: two Expectations tell you which half fails.

## Give it examples

Each Expectation has examples: inputs, and the right answer when there is one. Facet uses them two ways:

- **To teach.** Facet writes more examples like yours to build each version.
- **To check.** Some examples are hidden. When you make a Task, Facet hides a share of the ones you give it; when you upload to an Expectation, you choose with **Hide these**. Once hidden, an example is read only by Facet's checks, never by Facet's own agent and never used to build a version, so no version can learn its own test.

Real inputs from your app beat invented ones. Edge cases beat easy ones: the ticket written in two languages, the invoice with two totals. See [Add examples](/docs/examples).

## How each one is checked

Facet picks how to check each Expectation, and you can see and change it on the Expectation's page:

- **Code check:** exact rules, such as "the label is one of billing, bug or account". Cheapest, and exact.
- **Score:** how closely the answer matches the right one, such as an exact match.
- **Judge:** another model reads each answer against a short checklist you can edit, for things only a reader can tell, such as tone.

## The bar

Each Expectation has a bar, the share of its hidden examples a version must get right:

- **At least a number,** such as 90%. Use it when you know what good enough is.
- **No worse than the live version,** within a margin you set. Use it to protect something that already works while another Expectation improves.

A new Expectation that today's version already passes is fine; it protects that behavior from future changes.

## What the colors mean

- **Green:** the live version clears the bar.
- **Red:** it doesn't. Ask for a change to fix it.
- **Gray:** fewer than 30 hidden examples, too few to judge; add more.

## Who can loosen one

Lowering a bar, removing an Expectation, or making it optional (shown, but no longer required to merge) needs a Task owner's approval, so an Expectation can't quietly stop protecting you.

## Next steps

- [Add examples](/docs/examples): formats and how many you need
- [Make a Task better](/docs/improve): turn a red Expectation green