# Missions and templates

> What a mission is, how its steps are checked, and how a team sets the step library, mission templates and defaults that every new ticket starts from.

This page explains missions: the steps By Dawn's agent is held to while it works on a ticket. By the end you'll know
what a step can do, how By Dawn shows what was really checked, and how your team decides which steps a new ticket
starts with.

A **mission** is the list of steps a ticket goes through while the agent works on it: a plan a person approves, tests
that must pass, a pull request By Dawn merges. You choose the steps when you [start the ticket](https://docs.bydawn.com/start-a-ticket/), and
By Dawn holds the agent to them. The agent can't finish while a required step hasn't passed, so "done" means the same
thing on every ticket, whoever picked it up.

## Steps and phases

Each step belongs to a **phase**, and phases run in order. By Dawn starts with five: **Plan** (before anything is built),
**Design** (how it will be shaped), **Build** (while the work is written), **Verify** (proving it actually works) and
**Ship** (after it lands). An organization can rename, add, reorder and retire phases in
**Settings › Organization › Mission phases**.

Every step is one of four kinds, and the app labels each with whose move it is:

- **The worker does this**: the agent does the work and something checks the result, such as running your tests.
- **You decide**: a person answers before the mission carries on, such as **Approve the plan** or **Your
  sign-off**. These are the steps that pause for you.
- **SAW does this**: By Dawn acts on its own once the agent has finished and the steps before it pass, such as **Mark the
  PR ready**, **Get CI green**, **Approve the PR**, **Merge the PR** and **Move to Done**.
- **Guidance**: an instruction the agent follows for the whole session or from a phase onward. Nothing checks it, so
  it never blocks the finish. The ticket lists these under **Standing guidance**: "Instructions the worker follows,
  not checks it must pass."

Some steps only apply to certain work. A step that checks screens, for example, runs only if the change touches a
screen. Until the agent's changes say whether it applies, the picker shows "Runs only if this ticket's repos support
it", and afterwards the ticket lists the steps it skipped under "Nothing in this diff needs these".

## How By Dawn shows what was checked

When a step passes, the ticket keeps a receipt for it, and **Read the receipts** shows them. Each receipt says how
much it proves, at one of three levels:

| Level | Means |
|---|---|
| **Verified** | By Dawn ran it and read the exit code. |
| **AI-reviewed** | A model judged the work against a rubric. Not proof. |
| **Reported** | The worker said so. Nothing checked it. |

A step that falls back to **Reported** is shown that way everywhere, so a claim never looks like a check. That
happens when a person skips a check with a reason, or when the agent records what it did for a step that asks it to.

## Where the steps come from

Every step comes from the organization's **step library**, in **Settings › Organization › Missions**.
By Dawn seeds it, and the people who manage the organization's missions edit it: they can change a step, retire it, or
add their own with **Add a step**.
For each step they choose how far projects may go, under **Every project**:

- **Offered**: on for every project, and any project may switch it off.
- **Required**: no project can switch it off. It shows as **always runs** in the picker.
- **Required and frozen**: no project value applies to the step at all.

A project's step library, in **Settings › This project › Missions**, shows the inherited steps and
lets the project make them stricter for itself. It can switch an offered step off or add its own steps, but it
can't change what an organization step does. Retiring a step removes it from new missions only. Missions already
running keep their copy.

## Templates and defaults

When someone starts a ticket, the picker's ticks start from one of two places:

- A **preset**: **Auto**, **Quick**, **Standard** or **Thorough**. By Dawn works out a preset's ticks for each ticket,
  from its labels, its repos and the size of the work.
- A **mission template**: a named set of ticked steps that a person wrote. It may also hold step settings, such as
  how many mockups to draw.

Whatever the picker starts from, the person starting the ticket can untick any step except the required ones.

A template is written **For** one mode, **Planning** or **Build**, and that's fixed once it's saved. Each mode can
have one **Default** template, and that's what a new ticket's picker starts from. A ticket started with **Plan +
build** starts from both defaults together. A project's default beats the organization's, and with neither, the
picker starts from Auto. The person starting the ticket can still choose any other template or preset chip.

A template differs from a preset in one way that matters. A template may tick the steps By Dawn does itself, such as
**Merge the PR**, because a person chose them. A preset never does. An organization or project that never wants By Dawn
to merge switches **Merge the PR** off in its step library, and then no ticket or template can tick it.

To manage templates, open **Mission templates** in **Settings › Organization › Missions**, or the same
section in a project's settings. Choose **New template**, give it a **Name**, choose what it's **For**, tick its
steps, then **Create template**. On each saved template you can **Make default**, **Edit** or **Delete** it.
Deleting a template doesn't change tickets already started from it. Anyone can read the templates, but only people
who manage the organization's missions, or that project's, can change them.

## Turning missions off

Missions are on unless someone turns them off. An org owner or admin chooses **Missions on** or **Missions off** in
**Settings › Organization › Missions**, and a project can override it under **Proof-of-work checks**
in its own **Missions** section. With missions off, tickets start with **Start worker** and finish without any steps
to pass.

## What your code can read

Templates, the step library and a ticket's mission aren't part of the public API yet, so an API key can't read or
change them. Two fields in the public API do tell you about missions:

| Field | On | What it tells you |
|---|---|---|
| `heldAt` | a ticket | The mission step By Dawn is holding the ticket at, as `{ stepKey, label, implicit }`. `label` is the text to show. `implicit: true` means the project has missions off, and the hold comes from By Dawn's built-in default. |
| `missionsEnabledOverride` | a project | `true` or `false` when the project overrides the organization's missions switch, or `null` when it follows it. |

Read `heldAt` from [`GET /tickets/{ticketId}`](https://docs.bydawn.com/reference/#api/tag/tickets/getTicket) when a ticket sits in the
`building` column after its agent has finished. The ticket is waiting on that step, for example for CI to go green,
and isn't stuck. Show `heldAt.label` to people rather than hard-coding a step key such as `ci-green-before-done`,
because teams rename steps and retire By Dawn's own.

## FAQ

**Can I add a step to a ticket that's already running?**

Yes. Choose **Add a step** in the ticket's **Mission** section and pick from the library. An added step can't be
removed, only skipped with a reason.

**Can I get past a check that keeps failing?**

Yes, if you decide it can't pass here. **Approve & skip** on the step, or **Record as Reported & continue** on the
failure card, asks for a reason, logs it with your name, and marks the step **Reported** rather than Verified. A CI
wait has its own **Skip CI wait**, which moves the card to Review, though CI your repo requires still gates the
merge.

**Why does a step say it differs from default?**

Your organization edited one of By Dawn's seeded steps, so later fixes to By Dawn's version won't reach it. An org owner or
admin can open the step and choose **Reset to default** to take By Dawn's version back.

## Where to go next

- [Start a ticket](https://docs.bydawn.com/start-a-ticket/): choosing a mode and the steps in the picker.
- [Checkpoints and debriefs](https://docs.bydawn.com/mission-checkpoints/): answering a step that pauses for you, and reading what a mission
  did.
- [Words we use](https://docs.bydawn.com/glossary/#mission) defines mission, step and template in a sentence each.

Source: https://docs.bydawn.com/missions/