---
name: jira-create-ticket
description: "🎫 JIRA: Create tickets — generate well-structured Jira tickets (Task, Story, Bug, Epic + Sub-tasks) for any project based on Slack conversations, Fireflies meeting transcripts, manual notes, or existing Jira tickets. Shows a draft for approval, then creates tickets directly in Jira after confirmation. Trigger whenever asked to \"create a ticket\", \"generate a user story\", \"add to backlog\", \"log a bug\", \"break this into tickets\", \"create an epic\", \"dodaj do backloga\", \"stwórz ticket\", or when a clear scope of work appears in conversation without tickets. Also trigger proactively when feature descriptions or problem statements appear that clearly need Jira tickets but none have been created yet."
---

# Jira Create Ticket Skill

## Step 1 — Resolve project context

Before scanning any sources, determine:
- **Jira project key** — ask if not provided, or infer from context (e.g. recent conversation, project name)
- **Cloud ID** — use the Atlassian Cloud ID from your project context (e.g. `yourorg.atlassian.net`). If not set, ask the user.
- **Ticket language** — ask if unclear; default to English

If no project key is provided and context is ambiguous, ask:
> "Which Jira project should I create tickets in? (e.g. ACME, PROJ, WEB...)"

---

## Step 2 — Gather context

### A) Source provided (link, note, channel, ticket)
Use the provided source directly.

### B) No source provided
Automatically scan in parallel:
1. **Slack** — search channels related to the project (last 48h). Look for mentions of new features, issues, decisions, tasks.
2. **Fireflies** — fetch meeting transcripts from the last 7 days. Extract action items and topics that need tickets.

After gathering: **provide a short summary** of found topics and ask which ones should be logged as tickets.

### C) Existing Jira ticket provided
Fetch the ticket and propose breaking it into smaller sub-tasks or filling in missing fields.

---

## Step 2.5 — Check for Figma mockups

After gathering context, ask:

> "Do you have a Figma link for this feature? If yes, paste it and I'll scan the mockups to use as context."

**If a Figma link is provided:**
1. Try to use the Figma MCP (`get_design_context` or `get_screenshot`) to fetch the design context from the provided node/file URL.
2. If the Figma MCP is unavailable, not installed, access is denied, the link/node cannot be read, or fetching fails for any reason, **do not block ticket creation**. Tell the user briefly that the mockup could not be accessed and continue without Figma-derived context.
3. In that fallback case, ask for a short textual UI summary, for example:
   > "I couldn't access the Figma mockup. Please give me a short UI summary (screens, main components, states, and expected user flow), and I'll continue the ticket based on that."
4. If Figma context is retrieved successfully, extract relevant UI details: screen names, component labels, described states/variants, flows — and use these to enrich the ticket description and Acceptance Criteria.
5. **The Figma link is placed in a dedicated "Figma" section** in the ticket, between the description and Acceptance Criteria, separated by horizontal dividers — both in the chat draft and in the Jira ADF description (see Step 5 and Step 7 for exact format). If a Figma link was provided but the mockup could not be accessed, still include the link there and note that mockup context was unavailable, then proceed with the ticket using the other gathered context and/or the user's textual UI summary.

---

## Step 3 — Determine ticket type and structure

Select type based on context:

| Situation | Ticket type |
|---|---|
| New feature / functionality | **Story** |
| Technical task, configuration, refactor | **Task** |
| Reported bug | **Bug** |
| Large functional area (≥3 stories) | **Epic** + child Stories |
| Part of a larger task | **Sub-task** (linked to Story/Task) |

**If the input describes a large feature:**
- Create an **Epic** with a short description (no AC)
- Break it into **Stories** — each with a full description and AC
- Propose the structure before generating the draft

**If unsure about the type — ask.**

---

## Step 4 — Fetch Epic list from Jira

Before generating the draft, fetch current epics from the resolved project:

```
JQL: project = <KEY> AND issuetype = Epic AND statusCategory != Done ORDER BY created DESC
```

Display the epic list (key + title) and ask which one to link the new tickets to. If none fits — propose creating a new epic or leaving the field empty.

---

## Step 5 — Generate ticket drafts

### Scope signal — 1 ticket or multiple?

Before drafting, check:
- If the input describes **one user-facing capability** → 1 Story
- If it describes **one internal change** (refactor, config, migration) → 1 Task
- If it describes **multiple independent user capabilities** → Epic + Stories
- If any single piece would take **more than one sprint** to complete → break it down
- If someone says "and also..." more than twice in describing one thing → likely needs splitting

When splitting: propose the breakdown *before* drafting tickets, and get confirmation on the structure.

---

### Format for each ticket (display in chat):

```
────────────────────────────────────────
[STORY / TASK / BUG] (draft)
────────────────────────────────────────
Title:       <Concise, action-oriented title>
Type:        Story | Task | Bug | Epic | Sub-task
Epic:        <Epic title or "– none –">
Parent:      <Parent ticket key, if sub-task>

As a <user role>, I want <action> so that <value>.

[For Task / Bug — a short paragraph describing the problem/task instead of user story format]

[Context: 1–2 sentences explaining background a new reader would need. Assume the reader
hasn't been in any recent meetings about this.]

---
## Figma
🎨 [<screen or component name>](<figma_url>)

[← Only include this section if a Figma link was provided. Omit entirely otherwise.]

---
## Acceptance Criteria
- <condition 1>
- <condition 2>
- <condition 3>

---
## Notes / Open Questions
- ⚠️ [Needs clarification: <question>]  ← only if info is missing
────────────────────────────────────────
```

> **Notes / Open Questions** section is only included when there are actual open questions or ⚠️ flags.

---

### Description quality rules

**User story format (Stories):**
- Role must be specific: "logged-in user", "admin", "warehouse manager" — not just "user"
- Action must be concrete: "filter products by category" — not "use the filtering feature"
- Value must explain *why it matters*, not restate the action: "so that I can find relevant items without scrolling" — not "so that filtering works"

**Task/Bug format:**
- 2–4 sentences. Describe the problem or task clearly enough that a developer who missed all meetings can understand what to do.
- For bugs: include (1) what the current behaviour is, (2) what the expected behaviour is, (3) steps to reproduce if known.
- Don't pad. If it takes one sentence, one sentence is fine.

**Context field:**
- Always include 1–2 sentences of background that wouldn't be obvious from the title alone.
- Assume zero context: the assignee may not have been in the meeting where this was discussed.

---

### Acceptance Criteria rules

**How many:** aim for 3–6 AC per Story. Fewer suggests the scope isn't fully thought through; more suggests the ticket should be split.

**What "testable" actually means:** a QA engineer or the PM should be able to verify each criterion without asking a question. If verifying it requires a judgement call, rewrite it.

| ❌ Not testable | ✅ Testable |
|---|---|
| The UI looks good | All elements follow the design file at [link] |
| Fast loading | Page loads within 2 seconds on a 4G connection |
| Proper error handling | An error message is shown when the form is submitted with an empty required field |
| Works on mobile | Layout matches the mobile breakpoint in Figma on screens ≤ 375px |

**Format:** flat bullet list. No sub-points. Each criterion is one line.
- Start with the actor: "User can...", "System shows...", "Admin receives..."
- Use present tense: "User sees X" not "User will see X"
- Epics have no AC — only a 2–3 sentence scope description

**If context is insufficient to write meaningful AC — ask before generating, do not guess.**


---

## Step 6 — Ask for approval

After displaying the draft, ask:

> "Does this draft look good? I can make edits before creating tickets in Jira. Should I assign to the active sprint or leave in the backlog?"

- **Default**: backlog (no sprint assignment)
- **If asked about a sprint**: fetch the active sprint and ask for confirmation

---

## Step 7 — Create tickets in Jira

After approval, create tickets via Jira API (Atlassian MCP):

> ⚠️ **CRITICAL — description formatting on create:**
> `createJiraIssue` does **not** render markdown. Passing a markdown string (with `\n`, `##`, `*` etc.) results in those characters appearing literally in Jira — broken formatting.
>
> **Always use one of these two approaches:**
>
> **Option A (preferred) — ADF on create:** Pass the description as ADF JSON with `contentFormat: "adf"`. See the ADF reference below.
>
> **Option B (fallback) — create then edit:** Create the ticket with only `summary` and `issuetype` (no description), then immediately call `editJiraIssue` on the new key with `contentFormat: "markdown"` to set the full description. This is safe because `editJiraIssue` + `contentFormat: "markdown"` renders correctly.
>
> Never pass a multiline markdown string directly to `createJiraIssue` and assume it will render.

**Creation order:**
1. Epic (if new)
2. Stories / Tasks
3. Sub-tasks (after parents are created)
4. Bugs with a relation to the linked Story/Task (if indicated)

**Fields to set:**
- `summary` — title
- `issuetype` — type
- `description` — use ADF format (`contentFormat: "adf"`) with this exact structure:
  1. Paragraph — user story / task description + context (no heading)
  2. `rule` node — horizontal divider
  3. *(if Figma link exists)* `heading` level 2 — "Figma"
  4. *(if Figma link exists)* `paragraph` — inline hyperlink to the Figma file (text: screen/component name or "Figma mockups")
  5. *(if Figma link exists)* `rule` node — horizontal divider
  6. `heading` level 2 — "Acceptance criteria"
  7. `bulletList` — AC items
  8. *(if open questions exist)* `rule` node — horizontal divider
  9. *(if open questions exist)* `heading` level 2 — "Notes / Open Questions"
  10. *(if open questions exist)* `bulletList` — open questions / ⚠️ flags
- `parent` / `customfield_10014` — epic link (if applicable)
- `project` — `{ key: "<KEY>" }`

**ADF structure reference:**
```json
{
  "type": "doc",
  "version": 1,
  "content": [
    { "type": "paragraph", "content": [{ "type": "text", "text": "As a <role>, I want <action> so that <value>.\n\nContext: ..." }] },
    { "type": "rule" },
    { "type": "heading", "attrs": { "level": 2 }, "content": [{ "type": "text", "text": "Figma" }] },
    { "type": "paragraph", "content": [
      { "type": "text", "text": "Figma mockups", "marks": [{ "type": "link", "attrs": { "href": "<figma_url>" } }] }
    ]},
    { "type": "rule" },
    { "type": "heading", "attrs": { "level": 2 }, "content": [{ "type": "text", "text": "Acceptance criteria" }] },
    { "type": "bulletList", "content": [
      { "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "<criterion>" }] }] }
    ]},
    { "type": "rule" },
    { "type": "heading", "attrs": { "level": 2 }, "content": [{ "type": "text", "text": "Notes / Open Questions" }] },
    { "type": "bulletList", "content": [
      { "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "⚠️ ..." }] }] }
    ]}
  ]
}
```
Omit the Figma section (and its preceding `rule`) if no Figma link was provided.
Omit the Notes section (and its preceding `rule`) if there are no open questions.

After creation: display links to all created tickets.

---

## General rules

- **Always ask** when information is missing, or unsure about scope, type, assignee, or priority — do not guess and do not leave fields empty without flagging it
- **Never create tickets** without approval of the draft
- **Do not log** day-to-day UX micro-decisions or obvious clarifications — only items with real scope of work
- **Proactively suggest** splitting into sub-tasks if a task is too large for a single ticket
- **Flag ⚠️** in the Notes section when a ticket requires additional input from the client or another team