Add create-jira-card skill for Jira issue creation
Introduces a project-level Cursor skill that guides agents through creating well-structured Jira cards from natural language requests. Includes workflow for drafting, confirming, and creating issues with proper issue type selection, assignee lookup, and field templates. Co-authored-by: ScottGits <ScottGits@users.noreply.github.com>
This commit is contained in:
Cursor Agent
parent
af1cd602a3
commit
1b5d3434b5
3 changed files with 652 additions and 0 deletions
396
.cursor/skills/create-jira-card/SKILL.md
Normal file
396
.cursor/skills/create-jira-card/SKILL.md
Normal file
|
|
@ -0,0 +1,396 @@
|
||||||
|
---
|
||||||
|
name: create-jira-card
|
||||||
|
description: "Create well-structured Jira issues (cards) from natural language requests. When Claude needs to: (1) Create a Jira card, issue, ticket, story, task, bug, or epic, (2) File work in Jira from a description or conversation, (3) Create multiple Jira issues from a list or notes, (4) Add a card to an existing epic or sprint, or (5) Draft and create a Jira issue with assignee, priority, and labels. Gathers context, selects the right issue type, handles required fields, and confirms before creating."
|
||||||
|
---
|
||||||
|
|
||||||
|
# Create Jira Card
|
||||||
|
|
||||||
|
## Keywords
|
||||||
|
create jira card, create jira issue, create ticket, file a ticket, new jira card, new story, new task, new bug, new epic, log a ticket, add to jira, create issue in jira, make a jira ticket, open a ticket, jira card creation, bulk create issues, create multiple tickets
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Create individual or multiple Jira issues from natural language requests. This skill handles the full card-creation workflow: gathering context, selecting the right issue type, drafting a clear summary and description, resolving assignees and custom fields, and creating the issue after user confirmation.
|
||||||
|
|
||||||
|
**Use this skill when:** The user wants to create one or more Jira cards from a description, request, or list — without the specialized workflows covered by other skills.
|
||||||
|
|
||||||
|
**Do NOT use this skill for:**
|
||||||
|
- Bug triage or duplicate checking → use `triage-issue`
|
||||||
|
- Meeting notes with action items → use `capture-tasks-from-meeting-notes`
|
||||||
|
- Confluence specs → full backlog with Epic → use `spec-to-backlog`
|
||||||
|
- Status reports → use `generate-status-report`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workflow
|
||||||
|
|
||||||
|
Follow this 6-step process:
|
||||||
|
|
||||||
|
1. **Understand the request** — Parse what the user wants created
|
||||||
|
2. **Resolve project context** — Identify project, issue type, and parent links
|
||||||
|
3. **Draft the card(s)** — Write summary, description, and metadata
|
||||||
|
4. **Present for confirmation** — Show draft(s) before creating anything
|
||||||
|
5. **Create in Jira** — Call MCP tools to create issue(s)
|
||||||
|
6. **Confirm and link** — Return keys, URLs, and next steps
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 1: Understand the Request
|
||||||
|
|
||||||
|
Extract as much as possible from the user's message before asking questions.
|
||||||
|
|
||||||
|
### Extract These Elements
|
||||||
|
|
||||||
|
| Element | How to infer |
|
||||||
|
|---------|--------------|
|
||||||
|
| **Summary** | Main action or title the user provides |
|
||||||
|
| **Issue type** | Keywords: bug/error → Bug; feature/user story → Story; work item → Task; large initiative → Epic |
|
||||||
|
| **Project** | Explicit key (e.g., CASH, PROJ) or project name |
|
||||||
|
| **Assignee** | @mention, "assign to X", or "for Sarah" |
|
||||||
|
| **Priority** | urgent/critical → High; nice-to-have → Low |
|
||||||
|
| **Parent** | "under epic PROJ-123", "subtask of PROJ-456" |
|
||||||
|
| **Labels / components** | Any tags or area names mentioned |
|
||||||
|
| **Bulk items** | Numbered lists, bullet lists, or "create 3 tickets for..." |
|
||||||
|
|
||||||
|
### Ask Only for Missing Critical Info
|
||||||
|
|
||||||
|
If the user gave enough to draft a card, draft it and ask for confirmation. Only ask upfront when truly blocked:
|
||||||
|
|
||||||
|
- **No project and can't infer:** "Which Jira project should I create this in?"
|
||||||
|
- **Ambiguous issue type with very little context:** "Should this be a Story, Task, or Bug?"
|
||||||
|
- **Bulk without project:** "Which project for all of these?"
|
||||||
|
|
||||||
|
Do not ask for every optional field. Use sensible defaults and let the user adjust in the confirmation step.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 2: Resolve Project Context
|
||||||
|
|
||||||
|
### Get Cloud ID
|
||||||
|
|
||||||
|
If not already known, call `getAccessibleAtlassianResources` to obtain the `cloudId` for the user's Atlassian site.
|
||||||
|
|
||||||
|
### Resolve Project Key
|
||||||
|
|
||||||
|
**If user provided a key:** Use it directly (e.g., `CASH`, `PROJ`).
|
||||||
|
|
||||||
|
**If user provided a name or is unsure:**
|
||||||
|
```
|
||||||
|
getVisibleJiraProjects(
|
||||||
|
cloudId="...",
|
||||||
|
action="create"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Present matching projects and confirm the key.
|
||||||
|
|
||||||
|
### Check Available Issue Types
|
||||||
|
|
||||||
|
Always check issue types before creating:
|
||||||
|
```
|
||||||
|
getJiraProjectIssueTypesMetadata(
|
||||||
|
cloudId="...",
|
||||||
|
projectIdOrKey="PROJ"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue type selection guide** (see `references/issue-type-guide.md` for detail):
|
||||||
|
|
||||||
|
| User intent | Preferred type |
|
||||||
|
|-------------|----------------|
|
||||||
|
| Defect, error, broken behavior | Bug |
|
||||||
|
| User-facing feature or capability | Story |
|
||||||
|
| Technical work, chore, investigation | Task |
|
||||||
|
| Large body of work spanning multiple tickets | Epic |
|
||||||
|
| Work under an existing issue | Sub-task (if available) |
|
||||||
|
|
||||||
|
**Fallback:** Use the first available non-Epic type, or ask the user if none match.
|
||||||
|
|
||||||
|
### Resolve Parent / Epic Link
|
||||||
|
|
||||||
|
If the user references a parent epic or issue:
|
||||||
|
- Use the `parent` parameter when creating child issues
|
||||||
|
- Verify the parent key exists with `getJiraIssue` if uncertain
|
||||||
|
|
||||||
|
### Resolve Assignee
|
||||||
|
|
||||||
|
If an assignee is mentioned:
|
||||||
|
```
|
||||||
|
lookupJiraAccountId(
|
||||||
|
cloudId="...",
|
||||||
|
searchString="Sarah Johnson"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Handle 0, 1, or multiple matches per the patterns in `capture-tasks-from-meeting-notes`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 3: Draft the Card(s)
|
||||||
|
|
||||||
|
Write a clear summary and description before calling any create API.
|
||||||
|
|
||||||
|
### Summary Format
|
||||||
|
|
||||||
|
**Pattern:** `[Component/Area]: [Action] — [Brief context]`
|
||||||
|
|
||||||
|
**Good examples:**
|
||||||
|
- `Schedule page: Fix mobile recal loop on date change`
|
||||||
|
- `Payment: Add Afterpay breakout when deductible > 0`
|
||||||
|
- `Auth API: Implement token refresh endpoint`
|
||||||
|
|
||||||
|
**Bad examples:**
|
||||||
|
- `Bug` (not actionable)
|
||||||
|
- `Fix the thing` (too vague)
|
||||||
|
- Full paragraph in summary (belongs in description)
|
||||||
|
|
||||||
|
Keep summaries under ~100 characters when possible.
|
||||||
|
|
||||||
|
### Description Templates
|
||||||
|
|
||||||
|
Use templates from `references/field-templates.md` based on issue type. At minimum include:
|
||||||
|
|
||||||
|
- **Context** — Why this work exists
|
||||||
|
- **Requirements or steps** — What needs to happen
|
||||||
|
- **Acceptance criteria** — How to know it's done (for Stories/Tasks)
|
||||||
|
|
||||||
|
### Optional Metadata
|
||||||
|
|
||||||
|
Include in `additional_fields` when the user specifies or the project requires:
|
||||||
|
|
||||||
|
| Field | Example `additional_fields` value |
|
||||||
|
|-------|-----------------------------------|
|
||||||
|
| Priority | `{"priority": {"name": "High"}}` |
|
||||||
|
| Labels | `{"labels": ["frontend", "mobile"]}` |
|
||||||
|
| Components | `{"components": [{"name": "Checkout"}]}` |
|
||||||
|
|
||||||
|
### Bulk Creation
|
||||||
|
|
||||||
|
When the user provides multiple items:
|
||||||
|
1. Draft each card separately with its own summary and type
|
||||||
|
2. Number them in the confirmation preview
|
||||||
|
3. Create sequentially, tracking each returned key
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 4: Present for Confirmation
|
||||||
|
|
||||||
|
**CRITICAL:** Always show the draft and wait for user approval before calling `createJiraIssue`.
|
||||||
|
|
||||||
|
### Single Card Format
|
||||||
|
|
||||||
|
```
|
||||||
|
Here's the Jira card I'll create:
|
||||||
|
|
||||||
|
**Project:** CASH
|
||||||
|
**Type:** Story
|
||||||
|
**Summary:** Schedule page: Fix mobile recal loop on date change
|
||||||
|
**Assignee:** Sarah Johnson
|
||||||
|
**Priority:** High
|
||||||
|
**Parent Epic:** CASH-1234
|
||||||
|
|
||||||
|
**Description:**
|
||||||
|
[Rendered description preview]
|
||||||
|
|
||||||
|
Shall I create this card?
|
||||||
|
```
|
||||||
|
|
||||||
|
### Bulk Format
|
||||||
|
|
||||||
|
```
|
||||||
|
I'll create 3 cards in CASH:
|
||||||
|
|
||||||
|
1. **[Story]** Schedule page: Fix mobile recal loop
|
||||||
|
Assignee: Sarah | Epic: CASH-1234
|
||||||
|
|
||||||
|
2. **[Task]** Add unit tests for schedule recal logic
|
||||||
|
Assignee: Mike
|
||||||
|
|
||||||
|
3. **[Bug]** Payment summary shows wrong deductible on mobile
|
||||||
|
Priority: High
|
||||||
|
|
||||||
|
Create all 3, or would you like to change anything?
|
||||||
|
```
|
||||||
|
|
||||||
|
### User Can
|
||||||
|
|
||||||
|
- Confirm → proceed to Step 5
|
||||||
|
- Edit summary, type, assignee, or priority → update draft and re-present
|
||||||
|
- Skip items in a bulk list → create only selected ones
|
||||||
|
- Cancel → stop without creating
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 5: Create in Jira
|
||||||
|
|
||||||
|
### Single Issue
|
||||||
|
|
||||||
|
```
|
||||||
|
createJiraIssue(
|
||||||
|
cloudId="...",
|
||||||
|
projectKey="PROJ",
|
||||||
|
issueTypeName="Story",
|
||||||
|
summary="Schedule page: Fix mobile recal loop on date change",
|
||||||
|
description="[markdown description]",
|
||||||
|
assignee_account_id="[accountId if resolved]",
|
||||||
|
parent="CASH-1234",
|
||||||
|
additional_fields={
|
||||||
|
"priority": {"name": "High"},
|
||||||
|
"labels": ["mobile", "schedule"]
|
||||||
|
}
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Epic Creation
|
||||||
|
|
||||||
|
When creating an Epic (not part of a bulk backlog — use `spec-to-backlog` for that):
|
||||||
|
|
||||||
|
```
|
||||||
|
createJiraIssue(
|
||||||
|
cloudId="...",
|
||||||
|
projectKey="PROJ",
|
||||||
|
issueTypeName="Epic",
|
||||||
|
summary="Mobile Schedule Experience Improvements",
|
||||||
|
description="[epic description with objectives and success criteria]"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Save the returned Epic key if follow-up child cards are requested in the same session.
|
||||||
|
|
||||||
|
### Handle Required Field Errors
|
||||||
|
|
||||||
|
If creation fails due to missing required fields:
|
||||||
|
|
||||||
|
1. Fetch field metadata:
|
||||||
|
```
|
||||||
|
getJiraIssueTypeMetaWithFields(
|
||||||
|
cloudId="...",
|
||||||
|
projectIdOrKey="PROJ",
|
||||||
|
issueTypeId="10001"
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Ask the user for required values
|
||||||
|
3. Retry with `additional_fields`
|
||||||
|
|
||||||
|
### Handle Permission Errors
|
||||||
|
|
||||||
|
If creation fails with permission errors, inform the user clearly:
|
||||||
|
- They may lack create permission in that project
|
||||||
|
- The MCP app may need admin authorization
|
||||||
|
- Suggest trying a different project or contacting a Jira admin
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 6: Confirm and Link
|
||||||
|
|
||||||
|
After successful creation, return a concise summary.
|
||||||
|
|
||||||
|
### Single Card
|
||||||
|
|
||||||
|
```
|
||||||
|
✅ **Jira card created**
|
||||||
|
|
||||||
|
**CASH-2564** — Schedule page: Fix mobile recal loop on date change
|
||||||
|
Type: Story | Priority: High | Assignee: Sarah Johnson
|
||||||
|
https://yoursite.atlassian.net/browse/CASH-2564
|
||||||
|
|
||||||
|
**Next steps:**
|
||||||
|
- Add story points or sprint if needed
|
||||||
|
- Link related issues
|
||||||
|
- Attach designs or logs if you have them
|
||||||
|
```
|
||||||
|
|
||||||
|
### Bulk Creation
|
||||||
|
|
||||||
|
```
|
||||||
|
✅ **Created 3 cards in CASH:**
|
||||||
|
|
||||||
|
1. **CASH-2564** — Schedule page: Fix mobile recal loop
|
||||||
|
https://yoursite.atlassian.net/browse/CASH-2564
|
||||||
|
|
||||||
|
2. **CASH-2565** — Add unit tests for schedule recal logic
|
||||||
|
https://yoursite.atlassian.net/browse/CASH-2565
|
||||||
|
|
||||||
|
3. **CASH-2566** — Payment summary shows wrong deductible on mobile
|
||||||
|
https://yoursite.atlassian.net/browse/CASH-2566
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Edge Cases
|
||||||
|
|
||||||
|
### User Says "Create a Ticket" With Minimal Detail
|
||||||
|
|
||||||
|
Draft the best card you can from context (including conversation history and open files), present it, and ask the user to refine:
|
||||||
|
|
||||||
|
```
|
||||||
|
Based on our conversation, here's a draft card:
|
||||||
|
|
||||||
|
**Summary:** [inferred from context]
|
||||||
|
**Description:** [what I understood from the discussion]
|
||||||
|
|
||||||
|
Is this right, or what should I change?
|
||||||
|
```
|
||||||
|
|
||||||
|
### Linking to Existing Work
|
||||||
|
|
||||||
|
If the user wants to link (not parent) to another issue, note that link creation may require a separate MCP call or manual step in Jira. Mention related issue keys in the description under a **Related** section.
|
||||||
|
|
||||||
|
### Subtasks
|
||||||
|
|
||||||
|
Subtasks require a parent issue key, not an Epic key (unless the project uses a flat hierarchy). Confirm the parent issue before creating.
|
||||||
|
|
||||||
|
### Duplicate Concerns
|
||||||
|
|
||||||
|
This skill does not perform full duplicate triage. If the user asks "is this already filed?" or provides an error to triage, switch to `triage-issue`. For a quick sanity check, you may run one JQL search:
|
||||||
|
|
||||||
|
```
|
||||||
|
searchJiraIssuesUsingJql(
|
||||||
|
cloudId="...",
|
||||||
|
jql='project = "PROJ" AND summary ~ "keywords" ORDER BY created DESC',
|
||||||
|
fields=["summary", "status", "assignee"],
|
||||||
|
maxResults=5
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Mention any close matches in the confirmation step.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tips
|
||||||
|
|
||||||
|
### Do
|
||||||
|
- Infer project and type from conversation context when reasonable
|
||||||
|
- Present drafts before creating
|
||||||
|
- Use action verbs in summaries
|
||||||
|
- Include acceptance criteria for Stories and Tasks
|
||||||
|
- Look up assignees by name when mentioned
|
||||||
|
- Check issue type availability per project
|
||||||
|
|
||||||
|
### Don't
|
||||||
|
- Create issues without user confirmation
|
||||||
|
- Use vague summaries like "New task" or "Fix bug"
|
||||||
|
- Assume project key — verify or ask
|
||||||
|
- Hard-code issue types without checking metadata
|
||||||
|
- Use this skill for full spec-to-backlog breakdowns
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
| Step | Tool |
|
||||||
|
|------|------|
|
||||||
|
| Get cloud ID | `getAccessibleAtlassianResources` |
|
||||||
|
| List projects | `getVisibleJiraProjects(cloudId, action="create")` |
|
||||||
|
| Issue types | `getJiraProjectIssueTypesMetadata(cloudId, projectIdOrKey)` |
|
||||||
|
| Required fields | `getJiraIssueTypeMetaWithFields(cloudId, projectIdOrKey, issueTypeId)` |
|
||||||
|
| Assignee lookup | `lookupJiraAccountId(cloudId, searchString)` |
|
||||||
|
| Create issue | `createJiraIssue(...)` |
|
||||||
|
| Quick duplicate check | `searchJiraIssuesUsingJql(cloudId, jql, fields, maxResults)` |
|
||||||
|
|
||||||
|
**Workflow:** Understand → Resolve context → Draft → Confirm → Create → Summarize
|
||||||
|
|
||||||
|
**References:**
|
||||||
|
- `references/issue-type-guide.md` — Choosing Story vs Task vs Bug vs Epic
|
||||||
|
- `references/field-templates.md` — Description templates by issue type
|
||||||
138
.cursor/skills/create-jira-card/references/field-templates.md
Normal file
138
.cursor/skills/create-jira-card/references/field-templates.md
Normal file
|
|
@ -0,0 +1,138 @@
|
||||||
|
# Jira Card Description Templates
|
||||||
|
|
||||||
|
Copy and adapt the template that matches the issue type.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Story Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Context
|
||||||
|
[Why this story matters — user problem or business goal]
|
||||||
|
|
||||||
|
## User Story
|
||||||
|
As a [user type], I want [goal] so that [benefit].
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
- [Requirement 1]
|
||||||
|
- [Requirement 2]
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
- [ ] [Testable outcome 1]
|
||||||
|
- [ ] [Testable outcome 2]
|
||||||
|
- [ ] [Testable outcome 3]
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
[Any design links, dependencies, or out-of-scope items]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Context
|
||||||
|
[Why this task is needed]
|
||||||
|
|
||||||
|
## Objective
|
||||||
|
[What needs to be accomplished]
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
1. [Step 1]
|
||||||
|
2. [Step 2]
|
||||||
|
3. [Step 3]
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
- [ ] [Done when...]
|
||||||
|
- [ ] [Done when...]
|
||||||
|
|
||||||
|
## Technical Notes
|
||||||
|
[Stack, files, or approach hints if known]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Bug Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Description
|
||||||
|
[1-2 sentences describing the problem]
|
||||||
|
|
||||||
|
## Steps to Reproduce
|
||||||
|
1. [Step 1]
|
||||||
|
2. [Step 2]
|
||||||
|
3. [Step 3]
|
||||||
|
|
||||||
|
## Expected Behavior
|
||||||
|
[What should happen]
|
||||||
|
|
||||||
|
## Actual Behavior
|
||||||
|
[What happens instead]
|
||||||
|
|
||||||
|
## Environment
|
||||||
|
- **Platform:** [Web / iOS / Android / API]
|
||||||
|
- **Browser/OS:** [if applicable]
|
||||||
|
- **Environment:** [Production / Staging / Dev]
|
||||||
|
|
||||||
|
## Impact
|
||||||
|
[Who is affected and how severely]
|
||||||
|
|
||||||
|
## Additional Context
|
||||||
|
[Screenshots, logs, related tickets]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Epic Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Overview
|
||||||
|
[1-2 sentences on what this epic delivers]
|
||||||
|
|
||||||
|
## Objectives
|
||||||
|
- [Objective 1]
|
||||||
|
- [Objective 2]
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
- [ ] [Measurable outcome 1]
|
||||||
|
- [ ] [Measurable outcome 2]
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
[What's included]
|
||||||
|
|
||||||
|
## Out of Scope
|
||||||
|
- [Explicit exclusions]
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
[Dependencies, timeline, or stakeholders]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Minimal Template
|
||||||
|
|
||||||
|
Use when the user provides little detail and you need a lightweight card:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Summary
|
||||||
|
[Restate the work in 1-2 sentences]
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
- [ ] [Primary done condition]
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
[Source: conversation / request on DATE]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Summary Formula
|
||||||
|
|
||||||
|
**[Area/Component]: [Action verb] [object] — [optional context]**
|
||||||
|
|
||||||
|
| Issue type | Verb examples |
|
||||||
|
|------------|---------------|
|
||||||
|
| Story | Add, Implement, Build, Enable |
|
||||||
|
| Task | Configure, Refactor, Document, Investigate |
|
||||||
|
| Bug | Fix, Resolve, Correct |
|
||||||
|
| Epic | (noun phrase, no verb required) |
|
||||||
118
.cursor/skills/create-jira-card/references/issue-type-guide.md
Normal file
118
.cursor/skills/create-jira-card/references/issue-type-guide.md
Normal file
|
|
@ -0,0 +1,118 @@
|
||||||
|
# Issue Type Selection Guide
|
||||||
|
|
||||||
|
Use this reference when choosing the right Jira issue type for a card.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decision Tree
|
||||||
|
|
||||||
|
```
|
||||||
|
Is it a defect or incorrect behavior?
|
||||||
|
├── Yes → Bug (if available)
|
||||||
|
└── No → Is it a large initiative with multiple child tickets?
|
||||||
|
├── Yes → Epic
|
||||||
|
└── No → Is it user-facing functionality or product value?
|
||||||
|
├── Yes → Story (if available)
|
||||||
|
└── No → Is it work under an existing issue?
|
||||||
|
├── Yes → Sub-task (if available)
|
||||||
|
└── No → Task
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Bug
|
||||||
|
|
||||||
|
**Use when:**
|
||||||
|
- Something is broken or behaves incorrectly
|
||||||
|
- Users see errors, crashes, or wrong data
|
||||||
|
- Regression of previously working behavior
|
||||||
|
|
||||||
|
**Keywords:** bug, fix, broken, error, defect, regression, incorrect, fails, crash, exception
|
||||||
|
|
||||||
|
**Summary verbs:** Fix, Resolve, Correct, Debug
|
||||||
|
|
||||||
|
**Example summaries:**
|
||||||
|
- `Checkout: Fix null total when coupon applied`
|
||||||
|
- `Mobile: Resolve infinite spinner on schedule page`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Story
|
||||||
|
|
||||||
|
**Use when:**
|
||||||
|
- New user-facing feature or capability
|
||||||
|
- Product enhancement with clear user value
|
||||||
|
- Work that can be described as "As a user, I want..."
|
||||||
|
|
||||||
|
**Keywords:** feature, add, enable, user can, new capability, enhancement, implement UI
|
||||||
|
|
||||||
|
**Summary verbs:** Add, Implement, Build, Enable, Create, Introduce
|
||||||
|
|
||||||
|
**Example summaries:**
|
||||||
|
- `Profile: Add email notification preferences`
|
||||||
|
- `Search: Enable filter by date range`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task
|
||||||
|
|
||||||
|
**Use when:**
|
||||||
|
- Technical work without direct user-facing outcome
|
||||||
|
- Refactoring, infrastructure, DevOps, documentation
|
||||||
|
- Investigation or spike work
|
||||||
|
- Chores and maintenance
|
||||||
|
|
||||||
|
**Keywords:** refactor, configure, setup, migrate, document, investigate, spike, upgrade, optimize
|
||||||
|
|
||||||
|
**Summary verbs:** Configure, Refactor, Migrate, Document, Investigate, Upgrade, Optimize
|
||||||
|
|
||||||
|
**Example summaries:**
|
||||||
|
- `CI: Upgrade Node.js to v20 in pipeline`
|
||||||
|
- `API: Refactor auth middleware for testability`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Epic
|
||||||
|
|
||||||
|
**Use when:**
|
||||||
|
- Work spans multiple stories/tasks over time
|
||||||
|
- User explicitly asks for an epic
|
||||||
|
- Large feature area that will have child issues
|
||||||
|
|
||||||
|
**Keywords:** epic, initiative, program, large feature, phase
|
||||||
|
|
||||||
|
**Do NOT use Epic for:**
|
||||||
|
- Single tickets (use Story or Task)
|
||||||
|
- Full spec breakdowns with many tickets (use `spec-to-backlog` skill)
|
||||||
|
|
||||||
|
**Summary style:** Noun phrase describing the initiative
|
||||||
|
- `Mobile Schedule Experience`
|
||||||
|
- `Payment Gateway Migration`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Sub-task
|
||||||
|
|
||||||
|
**Use when:**
|
||||||
|
- Work is a slice of an existing parent issue
|
||||||
|
- User says "subtask of PROJ-123"
|
||||||
|
|
||||||
|
**Requires:** Valid parent issue key (not Epic key in most Jira configurations)
|
||||||
|
|
||||||
|
**Summary style:** Specific action within parent scope
|
||||||
|
- `Write unit tests for recal logic`
|
||||||
|
- `Update API contract documentation`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Project-Specific Types
|
||||||
|
|
||||||
|
Some teams use custom types (e.g., "Improvement", "Initiative", "Spike"). After calling `getJiraProjectIssueTypesMetadata`, map user intent to the closest available type and confirm with the user if ambiguous.
|
||||||
|
|
||||||
|
| Custom type | Usually maps to |
|
||||||
|
|-------------|-----------------|
|
||||||
|
| Improvement | Story or Task |
|
||||||
|
| Initiative | Epic |
|
||||||
|
| Spike | Task |
|
||||||
|
| Technical debt | Task |
|
||||||
|
| Incident | Bug or Task |
|
||||||
Loading…
Reference in a new issue