# Writing tickets an agent can finish

> What a ticket needs so an agent can finish it without guessing, a weak ticket rewritten, when to split one, and which mode to start it in.

This guide helps you write tickets that an agent can take from start to merged without coming back to you. By the
end you'll know the four things every good ticket says, when a ticket should become several, and which mode to start
it in.

An agent reads your ticket the way a new teammate would on their first day. It can read the whole codebase, but it
can't read your mind, and it doesn't know what was said in the meeting. Whatever the ticket leaves out, the agent
either asks about or guesses, and a guess is what comes back to you in review.

## The four things a ticket says

1. **The outcome.** What's different for someone when this is done. Write it as a result, not as a task: "customers
   can download their invoices as a spreadsheet", not "add a CSV endpoint".
2. **Done when.** How you'll check it. These become the plan's **Acceptance checks**, the list the agent ticks off
   as it goes, so make each one something you could see or test.
3. **Context.** What the agent can't find in the code: why this matters, who asked, a link to the design or the
   customer's message, a decision that's already been made.
4. **Limits.** What not to change, and where to stop. "Don't change the invoices API" or "the PDF export is a separate
   ticket" saves a review round each.

You don't need headings for these. A few sentences that cover all four make a better ticket than a long one that
misses one.

## A ticket, rewritten

Here is the first version of a ticket from the billing project in [Intro to By Dawn](https://docs.bydawn.com/learn/intro-to-saw/):

> **Invoice export**
>
> Customers want to export invoices.

An agent can start on this, but it has to guess at everything that matters: which format, which invoices, which
columns, and where the button goes. Each guess is a question in the plan or a change you ask for in review.

Here it is rewritten:

> **Add a CSV export to the invoices page**
>
> Customers keep asking support for their invoices as a spreadsheet (three tickets last month). Add an **Export CSV**
> button to the invoices page that downloads the invoices currently shown, with the filters applied. Columns: number,
> date, customer, total, status. Dates as YYYY-MM-DD, totals without a currency symbol, so spreadsheets read them as
> numbers.
>
> Done when:
> - the button downloads a file that opens in Excel and Google Sheets
> - the rows match what's on screen with any filter applied
> - an empty list downloads a file with just the header row
>
> Don't change the invoices API; build the file in the browser from what the page already loaded. PDF export is
> BIL-150.

It's still short. The outcome is in the title. The "done when" list is something a reviewer can check. The context
(three support tickets) tells the agent this is for customers, not for accounting. The limits keep it out of the API
and away from the PDF work.

## Let By Dawn help you write it

You don't have to write all of this from a blank page. In the desktop app, press `⌘N` and choose
**Advanced** to open the full composer, write a sentence or two, then:

- **Draft it** turns your sentence into a draft with an outcome, acceptance checks, touchpoints, constraints and open
  questions, from what it finds in the repo.
- **Grill me** asks you the questions the repo can't answer, and your answers go into the draft.

Read the draft as you would a teammate's. It knows the code, but only you know what the customer meant. [Tickets and
sub-tickets](https://docs.bydawn.com/tickets/#use-the-full-composer) covers the composer and every property.

A question about the code that isn't a ticket yet is better asked first. Press `⌘J` to ask about the
code, and when the answer shows there's work to do, choose **Make it a ticket** to carry the question and the answer
into a new ticket. [Questions](https://docs.bydawn.com/questions/) covers asking in full, and [Keyboard shortcuts](https://docs.bydawn.com/keyboard-shortcuts/) lists
the rest of the keys, with the ones the web app uses instead.

## One ticket or several

A ticket should be one change you'd review in one sitting. Split it when:

- **it has parts that could ship on their own.** Each gets its own pull request, and one stuck part doesn't hold up
  the rest.
- **it touches several repos or areas** that different people review.
- **you'd write "and then" in the outcome.** "Add the export, and then email it monthly" is two tickets.

To split, open the ticket and choose **Sub-ticket** under **Linked work**. Each sub-ticket gets its own identifier,
such as `BIL-142.1`, and its own agent, branch and pull request. When one part has to land before another, link them
with **Blocked by**: By Dawn won't start a blocked ticket until its blocker is completed. See [Break work into
sub-tickets](https://docs.bydawn.com/tickets/#break-work-into-sub-tickets) and [Link tickets](https://docs.bydawn.com/tickets/#link-tickets).

When the work is bigger still, a feature of many tickets, plan it as an epic instead. See [Planning a feature as an
epic](https://docs.bydawn.com/learn/planning-an-epic/).

## Choose the mode to start it in

When you start a ticket, By Dawn asks how:

| Mode | Use it when |
|---|---|
| **Plan first** | You're not sure what the right change is. The agent researches and writes a plan, but can't change any code. You read it, then start the build yourself. |
| **Plan + build** | You know what you want, but want to agree how before the agent starts. It plans, waits for your approval, then builds. By Dawn offers it first, until you start a ticket in another mode. |
| **Build now** | The ticket is small and clear, such as a fix with an obvious cause. It builds in one go, and still stops at each step that asks you. |

Starting with **Plan + build** is a good habit until you know how an agent reads your team's tickets. When you send
a plan back, say what should change and why, in a sentence. The agent revises the plan to answer your note, so a
specific note gets a specific fix. [Start a ticket](https://docs.bydawn.com/start-a-ticket/#plan-build-or-plan--build) covers each mode and
the steps you can tick before it starts.

## Do and don't

**Do:**

- Write the outcome as a result someone will notice.
- Make every "done when" line something you could check in a minute.
- Link the design, the thread or the customer's message rather than retelling it.

**Don't:**

- Leave the agent to guess between two reasonable readings. Pick one, or say both are fine.
- Put two features in one ticket because they touch the same file.
- Write the implementation for it. Say what has to be true, and let the plan say how. If you do care how, say so as a
  limit.

## Where to go next

- [Planning a feature as an epic](https://docs.bydawn.com/learn/planning-an-epic/): from an idea to a set of ordered tickets.
- [Reviewing agent work](https://docs.bydawn.com/learn/reviewing-agent-work/): what to check when the ticket comes back.

Source: https://docs.bydawn.com/learn/writing-tickets/