Overview
Shortcut (formerly Clubhouse) is a project management tool designed specifically for software development teams. It organizes work around stories (tasks), epics (large features), and iterations (sprints), providing a streamlined workflow that connects planning to execution. Shortcut balances simplicity with the power needed by growing engineering teams.
Shortcut offers multiple views including Kanban boards, backlogs, roadmaps, and reports. It integrates deeply with development tools like GitHub, GitLab, Bitbucket, Slack, and Figma. The platform supports custom workflows, labels, estimates, and team-specific configurations.
Core Concepts
Stories
| Story Type | Icon | Use Case |
|---|
| Feature | Star | New functionality |
| Bug | Bug | Defect to fix |
| Chore | Wrench | Maintenance, tech debt |
Story Fields
| Field | Description |
|---|
| Name | Story title |
| Description | Markdown-supported details |
| Type | Feature, Bug, or Chore |
| State | Current workflow state |
| Owner(s) | Assigned team members |
| Team | Responsible team |
| Epic | Parent epic |
| Iteration | Sprint assignment |
| Labels | Tags for categorization |
| Estimate | Story points |
| Priority | Urgent, High, Medium, Low, None |
| Due date | Deadline |
| Tasks | Subtask checklist |
Workflow States
| Category | Default States |
|---|
| Unstarted | Unscheduled, Ready for Development |
| Started | In Development, Ready for Review, In Review |
| Done | Completed |
Keyboard Shortcuts
| Shortcut | Action |
|---|
N | New Story |
E | New Epic |
I | New Iteration |
S | Search |
/ | Focus search bar |
Ctrl+K | Quick actions |
B | Toggle sidebar |
? | Show shortcuts |
J / K | Navigate down / up |
Enter | Open selected story |
X | Select / deselect story |
Epics
| Field | Description |
|---|
| Name | Epic title |
| Description | Detailed scope and goals |
| State | To Do, In Progress, Done |
| Owner(s) | Responsible leads |
| Labels | Categorization tags |
| Objective | Parent objective (OKR) |
| Planned dates | Start and target dates |
Iterations (Sprints)
| Field | Description |
|---|
| Name | Iteration name |
| Start date | Sprint start |
| End date | Sprint end |
| Stories | Assigned work items |
| Velocity | Sum of completed story points |
Views
Reports
| Report | Description |
|---|
| Velocity | Story points completed per iteration |
| Burn-down | Remaining work in current iteration |
| Cumulative Flow | Story state distribution over time |
| Cycle Time | Average time from start to completion |
| Lead Time | Average time from creation to completion |
Integrations
| Integration | Features |
|---|
| GitHub | Link PRs and branches; auto-state transitions |
| GitLab | Merge request linking and status sync |
| Bitbucket | PR and branch integration |
| Slack | Create stories from messages; notifications |
| Figma | Embed design files in stories |
| Sentry | Link error reports to bug stories |
| Zapier | Connect to 5,000+ tools |
Git Integration
# Branch naming convention (auto-links to story)
git checkout -b username/sc-12345/feature-name
# Commit message linking
git commit -m "Implement login flow [sc-12345]"
# PR description linking - include sc-12345 anywhere
API
# List stories
curl -L https://api.app.shortcut.com/api/v3/stories \
-H "Shortcut-Token: YOUR_API_TOKEN"
# Create a story
curl -X POST https://api.app.shortcut.com/api/v3/stories \
-H "Shortcut-Token: YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Implement OAuth login",
"story_type": "feature",
"description": "Add OAuth2 login support",
"labels": [{"name": "auth"}],
"estimate": 5
}'
# Search stories
curl "https://api.app.shortcut.com/api/v3/search/stories?query=is:started%20owner:me" \
-H "Shortcut-Token: YOUR_API_TOKEN"
Troubleshooting
| Issue | Solution |
|---|
| GitHub PRs not linking | Check branch name includes sc-XXXXX |
| Workflow states not matching | Configure custom workflow per team |
| Iteration velocity inaccurate | Ensure stories have estimates before completing |
| Search not finding stories | Use operators: is:started, label:bug, owner:me |
| Bulk import failing | Check CSV format matches import template |
| Notifications overwhelming | Adjust preferences; unfollow non-critical stories |
| Roadmap dates wrong | Update epic planned dates |
| Slow board loading | Archive completed iterations; reduce visible stories |
