# Evaluators

URL: /code/file-conventions/evaluators · Id: `page:code/file-conventions/evaluators`

> A file in evaluators/ defines one Evaluator, a rubric and the Function that grades an output against it.

A file in `evaluators/` defines one [Evaluator](/business/nouns/evaluator): a rubric and the [Function](/business/nouns/function) that grades an output against it and returns a verdict.

```text
evaluators/
└── notice-tone.ts      grades every renewal notice before it sends
```

## Reference
TypeScript with one default export.

| Export | Type | Holds |
| --- | --- | --- |
| `default` | `evaluator({ rubric, grade })` | The Evaluator |
| `rubric` | string | What a passing output does, in plain words |
| `grade` | `(output, $) => verdict` | Returns `{ pass, score, reason }`; its kind follows its code, as in any Function |

A [Verb](/business/nouns/verb), a [Role](/business/nouns/role) or an [Offer](/business/nouns/offer) names an Evaluator by its path.

## Examples
### Minimal
```ts title="evaluators/notice-tone.ts"
import { evaluator } from 'startup-builder'

export default evaluator({ rubric: 'Under 120 words.', grade: (text: string) => ({ pass: text.split(' ').length < 120 }) })
```

### Leaseline
```ts title="evaluators/notice-tone.ts"
import { evaluator } from 'startup-builder'

export default evaluator({
  rubric: 'States the end date and the new rent, offers one clear next step, and makes no threat.',
  grade: async (notice: string, $) => $`Grade this renewal notice against the rubric: ${notice}`,
})
```

## What it builds
The [SoftwareBuilder](/code/builders/software) compiles the file into one Evaluator [Version](/business/nouns/version).

- an `Evaluator` with its rubric
- a verdict [Event](/business/nouns/event) for each graded output, written to the [Action](/business/nouns/action)
- a failing verdict on a required Evaluator blocks the output and opens a [Task](/business/nouns/task)

## Good to know
- `Change.review` runs every Evaluator on a [Change](/business/nouns/change)'s preview.
- A Role's autonomy climbs on its Evaluators' verdicts; see [Role tests](/code/file-conventions/role-tests).