What is an Issue?
An issue represents a single piece of work. It has:- Title - A short description of what needs to be done
- Description - Detailed information, requirements, or context
- Status - Which column it’s in (To Do, In Progress, Done, etc.)
- Priority - How urgent it is (Urgent, High, Medium, Low)
- Assignees - Who’s responsible for the work
- Tags - Labels for categorisation and filtering
- Simple ID - A unique identifier like
TASK-123for easy reference
Creating Issues
From a Column
To create an issue in a specific column:- Click the + button at the top of any status column
- The New Issue panel opens with that status pre-selected
- Fill in the issue details and click Create Task
From the Header
To create an issue using the header button:
Set priority (optional)
Select a priority level (default is no priority):
| Priority | When to Use |
|---|---|
| Urgent | Needs immediate attention, blocking other work |
| High | Important, should be done soon |
| Medium | Normal priority |
| Low | Nice to have, can wait |
Assign team members (optional)
Click the assignee field and select one or more team members. You can assign multiple people to the same issue.
Add description (optional)
Write a detailed description using the rich text editor. You can format text, add lists, code blocks, and links.
Create with Workspace
If you want to immediately start working on an issue with AI assistance:
- When creating an issue, enable Create draft workspace immediately
- The issue is created with a linked workspace
- You can start working with coding agents right away
Editing Issues
Opening an Issue
Click any issue card on the board to open the issue panel. The panel slides in from the right side.Auto-Save
Changes to the title and description save automatically as you type. You don’t need to click a save button - just edit and your changes are saved.Auto-save has a small delay (about half a second) to avoid saving every keystroke. If you close the panel immediately after typing, wait a moment for the save to complete.
Editing Properties
Properties like status, priority, assignees, and tags save immediately when you change them:| Property | How to Edit |
|---|---|
| Status | Click the status dropdown and select a new status, or drag the card to another column |
| Priority | Click the priority dropdown and select a level |
| Assignees | Click the assignees field, select/deselect team members |
| Tags | Click the tags field, select/deselect tags |
Editing the Description
The description uses a rich text editor with formatting options:- Bold, italic,
strikethrough - Bullet lists and numbered lists
- Code blocks for technical content
- Links to external resources
Issue Sections
The issue panel has collapsible sections for additional information:Workspaces Section
Shows development workspaces linked to this issue. Workspaces are where coding agents do their work.
- Status - Active, idle, or completed
- Age - How long ago it was created
- PR status - Whether a pull request has been created
Sub-Issues Section
Issues can have child issues (subtasks) for breaking down work:
- Add Sub-Issue - Create a new child issue
- Link Existing Issue - Make an existing issue a subtask
- View Parent - If this is a sub-issue, see its parent
Comments Section
Discussion thread for the issue:- Add Comment - Share updates, ask questions, or provide feedback
- React - Add emoji reactions to comments
- Edit/Delete - Modify or remove your own comments
Sub-Issues (Subtasks)
Break large issues into smaller, manageable pieces using sub-issues.Creating a Sub-Issue
Click Add Sub-Issue
Click the + button in the Sub-Issues section header. A dropdown appears with options to create a new issue or link an existing one.
Viewing the Parent Issue
When viewing a sub-issue, you’ll see a Parent link below the issue properties. Click it to navigate to the parent issue.
Sub-Issue Behaviour
- Sub-issues appear on the board just like regular issues
- They can have their own status, priority, and assignees
- Completing all sub-issues doesn’t automatically complete the parent
- Sub-issues can’t have their own sub-issues (only one level deep)
Issue Actions
Issue Actions provide quick access to common operations on an issue. You can access them in two ways:From the Issue Panel
Click the More button (three dots) in the top-right corner of the issue panel.
From the Command Bar
Open the command bar withCmd/Ctrl + K, then select Issue Actions.
Available Actions
| Action | Shortcut | Description |
|---|---|---|
| Create Issue | I C | Create a new issue |
| Change Status | I S | Move issue to a different status |
| Change Priority | I P | Set or change priority level |
| Change Assignees | I A | Add or remove assignees |
| Make Sub-issue of | I M | Make this issue a child of another |
| Add Sub-issue | I B | Add a sub-issue to this issue |
| Link Workspace | I W | Connect a workspace to this issue |
| Duplicate Issue | I D | Create a copy of this issue |
| Delete Issue | - | Permanently delete this issue |
Copying Issue Links
To share an issue with someone:- Open the issue panel
- Click the Copy Link button () in the panel header
- The issue URL is copied to your clipboard
Deleting Issues
To delete an issue:- Open the issue panel
- Click the More button (three dots) to open Issue Actions
- Select Delete Issue
- Confirm the deletion
Issue Simple IDs
Every issue has a Simple ID - a short, unique identifier likeTASK-123. This makes it easy to reference issues in conversations, commits, and documentation.
The Simple ID is shown:
- On issue cards on the board
- In the issue panel header
- In the URL when viewing an issue
Best Practices
Write clear titles
Issue titles should describe what needs to be done, not the problem. “Add password reset flow” is better than “Users can’t reset password”.
Use priority wisely
Reserve “Urgent” for genuine emergencies. If everything is urgent, nothing is.
Assign deliberately
Assign issues to people who will actually work on them. Unassigned issues are fine for backlog items.
Keep descriptions updated
As requirements change or you learn more, update the description. It’s the source of truth for what needs to be done.
Related Documentation
- Kanban Board - Moving and organising issues on the board
- Filtering & Sorting - Finding issues quickly
- Customising Your Board - Configuring statuses and tags
- Workspaces - Working with coding agents