Backlog
The Backlog page of a project: every story, task, sub-task, bug, spike and improvement with its reference, kind, status, priority, people, estimates and the fields its kind adds, its lifecycle, its hand-over and its versions.
By the end of this page you will have written down the work of a project as stories, tasks, sub-tasks, bugs, spikes and improvements, know every field each kind carries and what reads it downstream, and know how an item moves along its lifecycle, who holds it, how it is deleted and where every version of it is kept.
A work item is one row of the tracker. All six kinds share the project's tracker sequence, so a
reference such as CRM-142 is always one thing whether it is a story, a bug or a spike, and each
kind adds its own fields to the ones they share: a story's persona and its as a / I want / so
that sentence, a bug's severity, environment and reproduction, a spike's time box and outcome. A
story also carries acceptance criteria, the sentences that say
when it is done, and every save of an item is kept as a
version with the criteria inside it.
Before you begin
| You want to | You need |
|---|---|
| Open the Backlog page | work-item:view-any on the project, which every default role carries. A client guest sees the agreed items only. |
| Add an item | work-item:create. Project managers, analysts, developers and QA have it by default. |
| Edit an item | work-item:update. |
| Move an item along its lifecycle | work-item:transition. |
| Hand an item to someone | work-item:assign. |
| Delete an item | work-item:delete. |
| Name a person on an item | The person to be a member of the team. |
The page lives under a project: open the project and choose Backlog in the sidebar, badged with how many open items you may see. An epic the items hang under is written first, on the Epics page.
Read the backlog
The table lists one item per row:
| Column | What it shows |
|---|---|
| Reference | The item's key, painted in the colour of its kind. |
| Item | The title, with the epic it hangs under and the parent it sits under beneath it. Press the title to open the detail flyout. |
| Kind | Story, task, sub-task, bug, spike or improvement, as a badge with the kind's icon. |
| Status | Backlog, ready, in progress, in review, in QA, done or cancelled, as a badge. Hidden from a guest. |
| Priority | Lowest to highest, as a badge with an arrow. |
| Assignee | The person doing the work, or Unassigned. Hidden from a guest. |
| Points | The story points, or Not sized. |
| Updated | How long ago the record last changed. |
| Row menu | View Item, Edit Item, Move to, Assign to, Sprint, Activity, Delete Item. |
Sort by reference, title, kind, status, priority, points or updated by pressing a column heading; press it again to flip the direction. The list opens in the project's own order.
Above the table, narrow the list with the search box (words in the reference or the title), the kind, status and priority lists, the epic list and the assignee list. The filters travel in the page address, so a filtered list can be shared; Clear Filters on the empty state drops them all.
Add an item
- Press New Item.
- Pick the Kind and the Priority. A story is the default; the fieldset the kind needs appears as soon as you pick it.
- Type the Title. It is the only field required; the rest can follow, and Heimdall will draft stories from the epics and the brief once the brief import lands.
- Write the Description and pick the Epic the item hangs under. A sub-task also needs a Parent (the story, task, bug or improvement it belongs to); a bug may name the story it was found in.
- Fill the fieldset of the kind: for a story the Persona and the sentence (As a, I want, So that) with the Business Value; for a bug the Severity, whether it is Reproducible, the Environment it was seen in, the component it was Found In, the Steps to Reproduce and the Expected and Actual Result; for a spike the Time Box and, when it closes, the Outcome.
- Under Who, pick the Assignee, the Reporter (you, unless it came from someone else), the Reviewer and the QA Owner; under Size and Dates the Story Points, the Due date, the Estimate and what is Remaining.
- Pick the Labels, tick the Components Touched and write the acceptance criteria.
- Press Create Item.
The item takes the next number of the project (the first item of CRM after its epics is the next
in the same series), starts in the backlog, names you as its reporter unless you said otherwise,
appears in the table at once, writes its first version with its criteria inside it, and
work_item.created goes out to every endpoint subscribed to it.
One sequence for the tracker
Epics, stories, tasks, sub-tasks, bugs, spikes and improvements share one
number series per project, so CRM-142 is always one thing and a reference in
a commit or a conversation never needs a kind. A number is never reused, even
after a delete.
Open an item
Press an item's title, or View Item in its row menu, to open the detail flyout: the reference, kind, status, resolution, priority and severity at the top, the title and the story sentence, then the description, the fields of the kind, the acceptance criteria, the epic, the parent, the people, the sizes, the dates, the components touched and the Versions section with every save of the item. From the flyout:
- Edit opens the editor on this item.
- Move to changes the status in one step, offering only the moves the lifecycle allows, with the reason to pick when the move is into cancelled.
- Assign to hands the item to you, to a member of the team or to nobody.
- Sprint plans the item into a planned or running sprint of the project, or sends it back to the backlog; the editor's Sprint field does the same, and the backlog's sprint filter shows one sprint's items or the items in no sprint.
- Restore this version under any earlier version puts it back, criteria included; see revisions and versions.
- Activity opens the item's history: every change, who made it and where it came from.
- Delete opens the confirmation.
A link such as /projects/<id>/backlog?show=<item id> opens the page with that item's flyout
already open; Heimdall's View buttons use it.
Edit an item
- Press Edit Item in the row menu, or Edit in the flyout.
- Change what you need, the criteria rows included. Every person named must be a member of the team; the epic, the persona, the environment and every component must be the project's; a sub-task keeps a parent and a parent is a story, task, bug or improvement of the same project. Changing the kind clears the fields the new kind does not carry.
- Press Save Changes.
The save writes a new version of the item, criteria included, and work_item.updated goes out
with the columns that changed, each with its old and new value. An edit that changes nothing
writes nothing and announces nothing. The status does not change from the editor; it moves from
the list or the flyout.
Move an item along its lifecycle
Move to in the row menu or the flyout offers the moves the lifecycle allows from where the item stands:
| From | To |
|---|---|
| Backlog | Ready, in progress, cancelled |
| Ready | Backlog, in progress, cancelled |
| In progress | Ready, in review, in QA, done, cancelled |
| In review | In progress, in QA, done, cancelled |
| In QA | In progress, done, cancelled |
| Done | In progress |
| Cancelled | Backlog |
A move into Cancelled asks why: won't do, duplicate, cannot reproduce or deferred; a move into
Done resolves the item as done. The first move into progress stamps when work started, a move
into done stamps when it was finished, and a move back into an open status clears the resolution
and the finish. Every move writes a version with the reason moved and work_item.transitioned
goes out with the status before and after and the resolution.
A column the project caps takes no more once it is full. The work-in-progress limits under project settings name the most items an open status may hold across the whole project; a move into a status at its limit is refused here, on the board, from an agent and over the API alike, and the message names the column, what it holds and the limit.
A story's approval is separate from its board status. Submit for review on the approval bar in its flyout asks the people the project's policy names; the story keeps its status throughout, and the approval stamps it approved at a version, from which moment a client guest sees it. Only an open story is submitted; a task, a bug, a spike or a done story is not.
The same move, three ways
Items move from this page, from the flyout and from the board, where a card dragged into another column runs the same move and a card dragged up or down changes the item's place in the project's order, the one this page's default sort reads. The Git integration will move a story into review when its pull request opens and into QA when it merges, and the Definition of Done will hold a move into done until its checklist is ticked, as those modules land.
Hand an item over
Assign to in the row menu or the flyout lists Me, every member of the team and Nobody.
Pick one and the item is theirs: the table and the flyout show the name, their
My Work reads it, and work_item.assigned goes out with the
person before and after. Handing an item to the person who already holds it changes nothing and
announces nothing. A person who is not a member of the team is refused.
Delete an item
Delete Item in the row menu or Delete in the flyout opens the confirmation. Deleting
removes the item with its criteria, every version it kept and its activity history; the items
under it lose their parent and stay in the backlog, and its number is never handed out again.
work_item.deleted goes out. Prefer Cancelled with a reason for work the team dropped: it keeps
the record and the reasoning.
All the fields
What happens next
- Every save, move, hand-over and restore writes a version, criteria included, and an entry in the project's activity history.
work_item.created,work_item.updated,work_item.transitioned,work_item.assigned,work_item.ranked,work_item.criteria_changed,work_item.restoredandwork_item.deletedgo out to the webhook endpoints subscribed to thework_item.*family;work_item.rankedcarries the position an item took when it was dragged to a new place on the board or ranked over the API.- The board, the sprints, the time logs, the Git links, the test cases drafted from the criteria and the releases composed from done items will all read the backlog as those modules land.
Heimdall on this page
Quality sits in the flyout above the links: Review now asks Heimdall to read the item against INVEST, its criteria, the project's business rules and its siblings, score it out of 100 and list what to fix, quoting the words and suggesting the rewrite; the row then carries the score beside its reference. See Quality review.
Heimdall reads the backlog and every item's versions through the same tools the MCP server offers, drafts stories into it as drafts a person reviews, moves and assigns items when you ask, and carries the open project as its context.
On the editor, Ask Heimdall beside each long field drafts it, improves it, shortens it, makes it testable or rewrites it as Given, When, Then; the draft waits under the field until you take it or drop it. See inline assists.
A story Heimdall drafts lands in the backlog as a draft with its sentence and its criteria; the brief import will draft whole epics' worth of them into a review queue once it lands.
From the API and MCP
Work Items API
List, read, add, change, move, hand over and delete items, replace their criteria, and read and restore their versions.
Build tools
list_work_items, list_my_work, get_work_item, move_work_item and assign_work_item: the MCP tools that read and move the tracker.
create_story_draft
The MCP tool that drafts a story with its sentence and criteria into the backlog.
Permissions
| Action | Permission |
|---|---|
| See the backlog | work-item:view-any, work-item:view; a client guest sees the agreed items only |
| Add an item | work-item:create |
| Edit an item or its criteria | work-item:update |
| Move an item | work-item:transition |
| Hand an item over | work-item:assign |
| Delete an item | work-item:delete |
| Read or restore its versions | work-item:view to read, work-item:update to restore; never a client guest |
Frequently asked
Related
- Quality review — the Quality panel in the flyout: Heimdall's score and findings, and the badge on the row
- Traceability — the Links panel in the flyout: what this implements, verifies, depends on or relates to, read from either side
- Comments and mentions — the Discussion panel in the flyout: questions, answers, mentions, followers
- Attachments — the Files panel in the flyout: wireframes, specifications and samples pinned on the record
- Labels — the project's own words on its items, and the filter by one
- Acceptance criteria — the rows that say when a story is done
- Epics — the bodies of work the items hang under
- Revisions and versions — every save kept, any version put back
- Status reference — every kind, status, resolution, priority, severity and reproducibility
work_item.*webhook events
How is this guide?
Last updated on
Epics
The Epics page of a project: each body of work with its reference, goal, value, measures, owner, MoSCoW priority, status, dates and colour, its lifecycle and its versions.
Labels
A project's own words pinned on its work items: pick labels on an item, filter the backlog by one, and shape the vocabulary from the backlog's label manager with a colour and a meaning for each word.