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

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

Key API Endpoints

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

Integration with QA Skills

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

Reference Files