Planning a feature as an epic

This guide helps you turn a feature that’s too big for one ticket into an epic that agents can work through on their own. By the end you’ll know how to have an agent propose the tickets, what to check before you agree them, and how to launch the epic so each ticket starts when it’s ready.

An epic groups a project’s tickets into one feature you can ship, with its progress rolled up in one place. A milestone splits an epic into phases, each with a target date. Both are optional: most tickets don’t need an epic, and most epics don’t need milestones.

The feature

The billing team from Intro to By Dawn wants team invoices: a customer with several teams should get one invoice per team, each sent to that team’s billing contact. It touches the data model, the invoice run, the emails and the settings page. That’s too much for one pull request, and some of it has to land before the rest can start.

Let an agent propose the split

Maya writes one ticket for the whole feature, the way Writing tickets an agent can finish describes: the outcome, how she’ll know it’s done, the context (the three customers who asked) and the limits (no change to how single-team customers are billed).

When she starts it, she picks Plan first, so the agent can research but not change any code. In the mission’s steps she ticks Split it into tickets: when the work is too big for one ticket, the agent proposes a set of tickets for her to approve, instead of one large plan.

The agent reads the code and comes back with a card titled Split it into tickets. It proposes:

• a New epic, “Team invoices”, that all the tickets will go under
• the Issues, as a tree with any sub-tickets indented under their parent
• the Blocked by links between them, such as “BIL-160 blocks BIL-161”

Nothing has been created yet. The card is a proposal, and Approve a split into tickets lists the ways to answer it.

Check the proposal

This is the most useful review you’ll do for the whole feature, because every ticket’s agent will work from what you agree here. Read it for three things:

• Is each ticket one reviewable change? A ticket that says “and” twice is probably two. A ticket that can’t be tested on its own should probably be folded into its neighbour.
• Is the order right? Each Blocked by link means the second ticket won’t start until the first is completed. Too few links and agents build on code that isn’t there yet. Too many and the tickets run one at a time when they could run side by side.
• Is anything missing? Migrations, settings, emails, docs. The agent proposes what the code tells it, so it may miss what only you know, such as the support article that has to change.

To change it, choose Let me reshape it and write what should change, such as “Split the email ticket into the template and the sending, and let the settings page start straight away”. The agent revises the tree and asks again. When it’s right, choose Create the tree and then Answer.

By Dawn creates it all at once: the epic, the tickets, the sub-tickets and the blocked-by links. Every new ticket goes in the epic, and so does the ticket that did the planning, unless it was already in one. The planning ticket’s own plan still asks for your approval as usual, and agreeing it ends the planning run.

Add milestones, if the dates matter

Open the epic from Epics & Milestones in the sidebar (⌘2). Its Milestones tab splits it into phases. Maya adds two with New milestone: “Pilot” for the three customers who asked, with a date two weeks out, and “Everyone” after it. Each ticket’s flag menu has Move to milestone, so she moves the data model, the invoice run and the emails into Pilot, and the settings page into Everyone.

Skip milestones when the epic will ship in one go. They earn their place when part of the feature has a date of its own. Epics and milestones covers editing, reordering and deleting them.

Launch the epic

Instead of starting each ticket by hand, Maya chooses Launch epic on the epic’s page. The dialog asks three things:

• Mode: Build now, or Plan + build if she wants to agree each ticket’s plan before it builds. Plan first isn’t offered, because a ticket that only plans stops in Review and would block the tickets after it.
• Preset: which mission steps each ticket starts with.
• Max at once: how many of the epic’s tickets may be building at the same time, from 1 to 20. It starts at 3.

The dialog says how many tickets start now and how many start later. Only tickets that are ready start: ones nobody has started, with no open blocker and no unfinished sub-tickets. The launch keeps running after that, and starts each waiting ticket as room frees up or its blockers finish, so the order she agreed is the order they build in.

She chooses Start 2 now. The epic’s page shows the launch with how many tickets are running, waiting and done, and she can Pause it or Stop it at any time. Stopping it starts nothing new, and tickets already building keep going. See Launch an epic for every setting.

If she’d known she wanted the tickets started as soon as she agreed them, she could have ticked the mission step Start the tickets as well. By Dawn then launches the epic for her once she has approved the tree and the plan.

While it runs

The epic’s page is where Maya follows the feature. The header shows how many tickets are complete, with a count per column, and the Overview tab gathers the pull requests and the relations in one place. Each ticket still has its own plan to agree and its own review, so her day is the same as for any ticket: answer what’s waiting in Needs you, and review what lands in Review. Running a cycle with agents describes that rhythm.

When every ticket is complete, the epic says so, and Mark done retires it from the epic lists.

Do and don’t

Do:

• Spend your time on the proposed tree. A wrong split costs a review round on every ticket after it.
• Add a Blocked by link only where the second ticket really needs the first one’s code.
• Keep Max at once low on your first launch, so you can keep up with the reviews.

Don’t:

• Start an epic’s tickets by hand while a launch is running. Let the launch keep the order.
• Use an epic for one ticket and its sub-tickets. A ticket with sub-tickets is enough.

Where to go next

• Running a cycle with agents: planning the next two weeks around epics like this one.
• Missions and templates: where the mission’s steps, such as Split it into tickets, come from.