Back to Home

Best Practices for Managing Bugs

Learn how to effectively manage bugs in Shortcut.

  1. Epics Backlog for Bugs
  2. Bug Management Tips & Tricks

Step 1 - Epics Backlog for Bugs

Learn how to use Epics to create a Backlog for your Bugs.


There are many ways you can manage bugs for your team and org, but these best practices are what we have seen work well and are a great list of tips to help you improve your process.

Epics Backlog for Bugs

When it comes to Bugs we suggest you create an Epic Backlog for each Team. This gives a place for bugs to live and then get pulled from and worked on. Unless you are a small team, we recommend organizing by Team rather than only having one large bug backlog. This keeps it more manageable and ensures ownership is clear. 

From the Milestones page, you can then use the Epic Team filter to see the bugs list that is relevant to you.

Use Custom Fields & Labels to sort

Being able to prioritize and organize are key to successful bug management and Custom Fields and Labels are the easiest way to get there. Story elements such as Labels and Custom Fields can quickly be created to help your team stay organized and can be used to filter across Shortcut, including Epics and the Stories page.

Custom Fields

Custom Fields allow you to select from a customizable dropdown of selections in order to tag your work. Two fields that are great for bug management are Severity and Priority.

Severity is how bad the impact is of a bug on the customer experience.  Priority is how quickly the team needs to fix it. If you sort by severity and then scroll through looking for high-priority items to pull from or you can filter by high priority. Sort by Severity and and then pull high priority items into the next Iteration.

Create and link your work from the Doc

Create and link existing Stories, Epics, Milestones, and Iterations in the Doc. This makes it really easy to hover to see the status and click in to view additional details. Use the / search and link work. Highlight any text and then Create to create a Story, Epic, or more. This allows you to view at a glance, hover for more details, and even open the Story to make adjustments or gain content without ever leaving the Doc.


Labels are similar to custom fields but rather than a structured drop-down they are a free-form text tag you can add to Stories. They can also be helpful in bug management.

Use labels to tag bugs as quick wins, low-hanging fruit, or good for new developers to work on. These tend to be bugs that are vetted, pointed, have been discussed, and it’s clear what the solution is. Labels are a great way to flag these. You could create a Label called New Dev Issue (or something related) or Quick Win. So it’s quick and easy to spot bugs that can be picked up by a new dev or if someone is blocked and has some extra time in their day to pick up something small.

You can use these labels to sort the Stories on the Epic.