How epics and features work
An epic is a task too large for one runner. Instead of handing it to a single runner, Jaah splits it into subtasks and runs them in stages: first the requirements are pinned down, then the approach is chosen, then the work is planned and divided, then each piece is built, and finally the result is checked as a whole. You describe the goal once; the stages do the rest.
A feature is something different: a folder that keeps related tasks together inside a project. An epic can sit in a feature like any other task.
This page explains the ideas. For the steps, see Start an epic and follow its stages, Steer an epic's subtasks and Organize tasks into features. For tasks in general, see How tasks work.
Terms
| Term | Meaning |
|---|---|
| Epic | A task that is never worked on directly. Jaah splits it into subtasks, and its state follows theirs. |
| Subtask | A task that belongs to an epic. It has the epic as its Parent. |
| Stage | The part of the epic a subtask does, such as Analyze or Plan. Each stage has its own persona. |
| Persona | The kind of expert a runner acts as. See Personas. |
| Feature | A folder for related tasks inside one project. Optional. |
When to use an epic
Choose Epic when you start a task and the work is too big or too unclear for one change: a new area of your product, a change that touches many parts, or a goal you can describe but not yet break down. Choose Task when one runner can deliver it as a single merged change.
An epic costs more than a task, because several runners work on it, but each of them does a smaller, clearer job.
The stages
When you save an epic, Jaah creates its first three subtasks: Analyze, Design and Plan. They wait as Not started until you start the epic. Plan adds the build subtasks — usually Coder, sometimes Translate for text in other languages — and the Finish subtask. On the board, a subtask's persona names its stage:
| Stage | What it does | What it hands on |
|---|---|---|
| Analyze | Pins down the requirements: what is asked, what is out of scope, and how to tell it is done. | A requirements document. |
| Design | Chooses the approach, given the requirements and your project's code. | A design document. |
| Plan | Splits the work into pieces and creates one Coder subtask for each. | The Coder subtasks. |
| Coder | Builds one piece and delivers it as a merged change. There can be many. | A merged change. |
| Finish | Checks the delivered result as a whole against the requirements. | The epic's final report. |
On the epic's Subtasks tab, the subtasks are grouped the same way: Prepare holds Analyze, Design and Plan; each phase the plan names holds the subtasks that build one part of the work; and Finish comes last. See Task page.
The stages run in order. A stage starts only when the stages before it are done: Design waits for Analyze, Plan waits for both, every Coder subtask waits for Plan (and sometimes for another Coder whose work it builds on), and Finish waits for every Coder. While a subtask waits, it shows as Waiting, and hovering its badge names the stage it waits for. Each subtask runs like an ordinary task, in its own worktree, and shows its own state, cost and outcome.
Finish may find one last thing missing. It can then add one more Coder subtask to the epic, which runs after it. The epic is done only once that subtask's change is merged too.
Involvement
An epic offers two levels of involvement: Unattended and Guided. Chat isn't offered for an epic.
- Unattended — every stage decides for itself.
- Guided — the Analyze and Design stages ask you about the requirements and the design before they settle them. Plan, Coder and Finish never ask about a decision.
Any stage can still stop to ask when it needs something only a person can give, such as access to a system. See Answer a task's question.
The epic's state
An epic has no runner of its own, so its state follows its subtasks:
- It is Running while any subtask still has work to do.
- It is Asking while one of its subtasks waits for your answer. Hover the badge to see which one.
- It is Failed when a subtask has used all its attempts. Fix or restart that subtask, and the epic carries on. Rarely, an epic fails while splitting its work, with no failed subtask; select Start on the epic to try again.
- It is Done once every subtask is done. Its Artifacts tab then holds the final report from Finish, or from the last Coder subtask Finish added, and its Details tab shows Finisher Notes when Finish left any.
Run the stages one at a time
Normally each subtask starts as soon as the ones before it are done. Tick Debug when you start an epic to hold them instead: a subtask whose turn has come shows as Held, and it runs only when you start it yourself, with its Start button on the Subtasks tab. Starting a subtask by hand runs it at once, even if the stages before it aren't done. Use it to read each stage's output before the next one runs.
Stop, start and complete
- Stop on the epic stops every subtask that hasn't finished. Their work is kept.
- Start on a stopped or failed epic sets it running again. Subtasks that were waiting their turn carry on; a subtask that was stopped stays Paused until you start it from its own ⋯ menu.
- Complete marks the epic done by hand. Its subtasks stay as they are.
- Reset on the epic resets it and all its subtasks to Draft, so Start runs it again from the first step.
Features
A feature keeps related tasks together inside one project, such as everything for a new report. Its screens are described in Feature. Features appear under their project in the board's sidebar; select one to see only its tasks, with a count of how many are done. A task, an epic included, belongs to at most one feature, and tasks outside any feature show as (other).
A feature is either active or Shipped. When its work is finished, Mark shipped records it as shipped; Reopen makes it active again. Deleting a feature moves its tasks to (other) and changes no task.
A feature never runs anything itself: it only groups tasks. An epic is what splits work and runs it.
Who can do what
- Creating an epic needs the create-tasks permission, like any task.
- Starting, stopping and completing an epic or its subtasks needs edit access to its project.
- Creating a feature needs the create-tasks permission for its project.
- Moving tasks into a feature, shipping or deleting it needs edit access to the project.
A control you don't have access to isn't shown. See Groups for how access is granted, and Tasks for every control on the board.