# Planning a feature as an epic

> Take a feature too big for one ticket from an idea to an epic of ordered tickets, let an agent propose the split, and launch it so the tickets start as their blockers finish.

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](https://docs.bydawn.com/learn/intro-to-saw/) 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](https://docs.bydawn.com/learn/writing-tickets/) 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](https://docs.bydawn.com/mission-checkpoints/#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](https://docs.bydawn.com/epics-and-milestones/#milestones) covers editing, reordering and deleting them.

## Launch the epic

Instead of [starting each ticket by hand](https://docs.bydawn.com/start-a-ticket/), 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](https://docs.bydawn.com/epics-and-milestones/#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](https://docs.bydawn.com/learn/running-a-cycle/) 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](https://docs.bydawn.com/learn/running-a-cycle/): planning the next two weeks around epics like this one.
- [Missions and templates](https://docs.bydawn.com/missions/): where the mission's steps, such as **Split it into tickets**, come from.

Source: https://docs.bydawn.com/learn/planning-an-epic/