# Design To Jira

> Guides product designers from vague input to a structured Jira Epic with linked Story tickets in SpecX Design (OD), auto-assigned to the current user with Team inferred from their Jira history. Always asks clarifying questions via AskQuestion (one at a time, selectable options) before drafting tickets. Use when designers want to create, draft, or file design work — exploration, UI design, research, handoff, design system, or design epics/stories in Jira.

- Skill: `alvarsp/design-to-jira` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add alvarsp/design-to-jira`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alvarsp/design-to-jira/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: alvarsp (https://skillmd.com/u/alvarsp)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/alvarsp/design-to-jira

---


# Design to Jira

Turn vague design requests into a structured **Epic + linked Stories** in **SpecX Design (OD)**.

**Defaults:** See [CONFIG.md](CONFIG.md) — project key `OD`, site `naspersclassifieds.atlassian.net`, team `SpecX Design`.

## Quick start

Designer says: *"Create a design Epic for checkout error states"*

1. Classify work type
2. **Always** ask clarifying questions via `AskQuestion` — one at a time ([QUESTIONS.md](QUESTIONS.md))
3. Propose Epic + Stories ([BREAKDOWN.md](BREAKDOWN.md), [TEMPLATES.md](TEMPLATES.md))
4. Resolve assignee + Team ([ASSIGNMENT.md](ASSIGNMENT.md))
5. **Wait for approval** — never create without confirmation
6. Create Epic in OD first, then Stories with `parent="OD-XXX"`
7. Return all ticket links

## Workflow

### 1. Classify

Determine primary work type: **Exploration**, **UI design**, **Handoff**, **Research**, **Design system**, or **Other**.

If multiple types apply, pick the dominant one for Epic framing; use per-Story types in the breakdown.

### 2. Clarify (mandatory — before any ticket draft)

**Always ask questions before defining tickets** — even when the user gave a detailed brief. Never skip straight to a preview.

Use the **`AskQuestion` tool** for every clarifying question and for breakdown approval. Do **not** ask clarifying questions as plain chat text.

**How to ask:**
- **One question per `AskQuestion` call** — wait for the answer before the next question
- Provide **2–5 selectable options** per question (plus an "Other / not sure" option when useful)
- Use `allow_multiple: true` only when the question genuinely allows multiple selections (e.g. platforms)
- Follow the decision tree in [QUESTIONS.md](QUESTIONS.md): Round 1 (scope/type) → Round 2 (type-specific) → stop when you can draft acceptance criteria
- Typical flow: 3–6 questions total; max ~8 if input was very vague

Do **not** ask for project key; default to `OD`.

### 3. Draft Epic + Stories

- **Epic:** initiative scope — see Epic template in [TEMPLATES.md](TEMPLATES.md)
- **Stories:** 2–6 independently reviewable slices — see [BREAKDOWN.md](BREAKDOWN.md)
- Apply type-specific Story sections from [TEMPLATES.md](TEMPLATES.md)

### 4. Resolve assignee and team

Before preview, resolve who and which team ([ASSIGNMENT.md](ASSIGNMENT.md)):

1. `atlassianUserInfo()` → assign all **Stories** to the current user (unless user named someone else)
2. Query user's recent OD issues with Team set → pick Team (fallback: SpecX Design)
3. Optionally infer Product Teams from area keywords or past tickets

Do **not** ask about assignee/team unless inference failed or user wants an override.

### 5. Preview and confirm

Present full breakdown using preview format in [TEMPLATES.md](TEMPLATES.md). State: **Creating in SpecX Design (OD)**. Include the **Assignment** block.

Confirm with **`AskQuestion`** (single question, selectable options) — e.g. "Create these tickets?", "Looks good — create", "Needs changes". Do not create on a plain-text "yes" in chat unless it came from `AskQuestion`.

Iterate if they request changes (including "assign to X" or "use team Y"); re-preview and re-confirm with `AskQuestion`.

### 6. Resolve Jira metadata

Before creating:

```
getAccessibleAtlassianResources → cloudId for naspersclassifieds.atlassian.net
getJiraProjectIssueTypesMetadata(projectIdOrKey="OD") → Epic + Story types
```

If creation fails on required fields: `getJiraIssueTypeMetaWithFields` and ask user or infer from context.

### 7. Create Epic FIRST

```
createJiraIssue(
  projectKey="OD",
  issueTypeName="Epic",
  summary="[Epic summary]",
  description="[Epic body from template]",
  additional_fields={
    "labels": ["ai-assisted", "ai-cursor"],
    "customfield_12200": "[team-id]",
    "customfield_19563": [{ "id": "[option-id]" }]  // optional
  }
)
```

**Save the Epic key** (e.g. `OD-123`).

### 8. Create Stories linked to Epic

For each approved Story, in dependency order:

```
createJiraIssue(
  projectKey="OD",
  issueTypeName="Story",
  summary="[Story summary]",
  description="[Story body — include Epic: OD-123 at bottom]",
  parent="OD-123",
  assignee_account_id="[current-user-or-override-account-id]",
  additional_fields={
    "labels": ["ai-assisted", "ai-cursor"],
    "customfield_12200": "[team-id]",
    "customfield_19563": [{ "id": "[option-id]" }]  // optional
  }
)
```

Use the same Team (and Product Teams, if set) as the Epic.

### 9. Summarize

```
✅ Created in SpecX Design (OD)

**Assignment:** [Name] · Team: [Team name] · Product team: [value or —]

**Epic:** OD-123 — [summary]
https://naspersclassifieds.atlassian.net/browse/OD-123

**Stories (N):**
1. OD-124 — [summary]
   https://naspersclassifieds.atlassian.net/browse/OD-124
...
```

## Reference files

| File | Purpose |
|------|---------|
| [CONFIG.md](CONFIG.md) | OD project defaults, labels, MCP setup |
| [TEMPLATES.md](TEMPLATES.md) | Epic + Story description templates |
| [BREAKDOWN.md](BREAKDOWN.md) | How to split initiatives into Stories |
| [QUESTIONS.md](QUESTIONS.md) | Clarifying question decision tree |
| [ASSIGNMENT.md](ASSIGNMENT.md) | Assignee + Team inference and overrides |
| [EXAMPLES.md](EXAMPLES.md) | End-to-end examples |

## Hard rules

- **Questions before tickets** — always use `AskQuestion` to clarify before drafting; never skip to preview on the first turn
- **One question at a time** — each `AskQuestion` call has one `questions` entry; wait for the answer before the next
- **Selectable options** — every clarifying question must offer options the user can pick from (not open-ended chat only)
- **Epic before Stories** — never create child tickets first
- **Always preview** before creating
- **Always label** `ai-assisted` and `ai-cursor` on Epic and every Story
- **Default assignee = current user** on Stories — see [ASSIGNMENT.md](ASSIGNMENT.md)
- **Always set Team** on Epic and Stories — infer from user history, then context, then SpecX Design fallback
- **Default project OD** — override only when user explicitly requests another project
- **Stories are type Story** — ask only if Story unavailable in OD

## When NOT to use

- Bug triage → use `triage-issue`
- Meeting action items → use `capture-tasks-from-meeting-notes`
- Confluence spec → eng backlog → use `spec-to-backlog`
- Single eng implementation tickets → use `to-issues`

## Team usage

Share this one-liner with designers:

> **"Create a design Epic for [your vague idea]"** — Cursor will ask interactive clarifying questions (one at a time, with selectable options), show a preview, and file an Epic + Stories in OD when you approve.

Examples: [EXAMPLES.md](EXAMPLES.md)