# QA Shortcut Integration

> Shortcut (formerly Clubhouse) integration for creating stories, managing epics/iterations, and tracking QA workflows via REST API.

- Skill: `azanir/qa-shortcut-integration` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add azanir/qa-shortcut-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/azanir/qa-shortcut-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: azanir (https://skillmd.com/u/azanir)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/azanir/qa-shortcut-integration

---


# QA Shortcut Integration

## Purpose

Integrate QA workflow with Shortcut for project management. Create and update stories from bug reports, test coverage gaps, and QA tasks. Sync QA metadata (severity, test type, labels) with Shortcut epics, iterations, and workflow states.

## Primary Target

**Shortcut** (formerly Clubhouse) via REST API v3. Base URL: `https://api.app.shortcut.com/api/v3`.

## Features

### Create/Update Stories

- **Create** stories in projects with full metadata
- **Update** existing stories (status, labels, description, external links)
- **Search** stories by query, epic, iteration, or label

### Epics and Iterations

- **Epics** — Group stories by feature/release; link stories to epics
- **Iterations** — Assign stories to sprints; query by iteration
- **Workflow states** — Map QA status to Shortcut workflow states

### Labels and Story Types

- **Story types** — Bug, feature, chore (map from QA task type)
- **Labels** — Component, severity, test type, coverage area
- **Custom fields** — Use Shortcut custom fields for QA metadata when configured

### Story Relationships

- **Blocking / blocked by** — Link stories for dependencies
- **External links** — Link to test cases, requirements, coverage reports
- **Comments** — Add reproduction steps, evidence, verification notes

## Authentication

| Variable | Description |
| -------- | ----------- |
| `SHORTCUT_API_TOKEN` | API token from Shortcut Settings → Account → API Tokens |

Store in `.env`; never hardcode. Header: `Shortcut-Token: <token>`.

## Key API Endpoints

| Method | Endpoint | Use |
| ------ | -------- | --- |
| POST | `/api/v3/stories` | Create story |
| GET | `/api/v3/stories/{story_id}` | Get story |
| PUT | `/api/v3/stories/{story_id}` | Update story |
| GET | `/api/v3/search/stories` | Search stories (query, epic, iteration) |
| GET | `/api/v3/epics` | List epics |
| GET | `/api/v3/iterations` | List iterations |
| GET | `/api/v3/workflows` | List workflow states |

See `references/api-patterns.md` for request/response patterns.

## Integration with QA Skills

| Skill | Integration |
| ----- | ----------- |
| **qa-bug-ticket-creator** | Create Shortcut story from bug report; map severity/priority to labels |
| **qa-task-creator** | Create Shortcut story from QA task; link to epic/iteration |
| **qa-coverage-analyzer** | Create stories for coverage gaps; label by component |
| **qa-flaky-detector** | Create stories for flaky tests; story type = bug |

When qa-bug-ticket-creator or qa-task-creator outputs a structured ticket, this skill translates it to Shortcut story format and creates/updates via API.

## Trigger Phrases

- "Create Shortcut story from [bug report / test failure]"
- "Add QA task to Shortcut"
- "Create story in Shortcut for coverage gap"
- "Update Shortcut story #123 with verification result"
- "Search Shortcut for stories in epic [name]"
- "Link story to test case / requirement"
- "Bulk-create Shortcut stories from [coverage / spec / flaky] output"

## Workflow

1. **Input** — Bug report, QA task, coverage gap, or user request
2. **Map** — Translate to Shortcut story format per `references/field-mapping.md`
3. **Resolve** — Get project_id, epic_id, iteration_id from workspace (or user input)
4. **Create/Update** — POST or PUT via REST API
5. **Link** — Add external links to test cases, requirements, evidence
6. **Output** — Return story URL and ID

## Scope

**Can do (autonomous):**
- Create stories from bug reports and QA tasks
- Update story status, labels, description
- Search stories by query, epic, iteration
- Map QA metadata to Shortcut labels and story types
- Add external links to test cases and requirements
- Work with qa-bug-ticket-creator and qa-task-creator outputs

**Cannot do (requires confirmation):**
- Create stories without project_id (user must provide or configure)
- Assign to members without mapping
- Create epics/iterations without workspace admin

**Will not do (out of scope):**
- Modify production or test code
- Close or archive stories (stakeholder responsibility)
- Integrate with Jira/Linear/GitHub (use respective skills)

## Quality Checklist

- [ ] Story includes title, description, and appropriate story type
- [ ] Labels map to QA metadata (severity, component, test type)
- [ ] External links added for test cases/requirements when applicable
- [ ] No hardcoded secrets; token from `SHORTCUT_API_TOKEN`
- [ ] Field mapping follows `references/field-mapping.md`
- [ ] API patterns from `references/api-patterns.md` used correctly

## Troubleshooting

| Symptom | Likely Cause | Fix |
| ------- | ------------ | --- |
| 401 Unauthorized | Missing or invalid token | Check `SHORTCUT_API_TOKEN`; regenerate at Shortcut Settings |
| 404 Not Found | Invalid story_id or project_id | Verify IDs; use search to resolve by name |
| 422 Validation Error | Invalid field value | Check field-mapping; ensure enum values match Shortcut |
| Rate limit (429) | >200 req/min | Throttle requests; batch where possible |
| Epic/iteration not found | ID from wrong workspace | List epics/iterations; use correct IDs |
| Labels not applied | Label doesn't exist | Create labels in Shortcut; use exact names |

## Reference Files

| Topic | File |
| ----- | ---- |
| API patterns (stories, epics, iterations) | `references/api-patterns.md` |
| QA field → Shortcut field mapping | `references/field-mapping.md` |