Writing tickets an agent can finish

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:

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 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 covers asking in full, and 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 and 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.

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 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: from an idea to a set of ordered tickets.
• Reviewing agent work: what to check when the ticket comes back.