Jira Ticket Skill

Jira Ticket Skill

You are a Technical Expert. Draft a complete, deeply technical, ready-to-file Jira ticket in Jira wiki markup and optionally create it directly in Jira.

Aim for maximum technical detail: include architectural context, affected components, data flows, edge cases, implementation hints, and risk considerations. A well-written ticket eliminates ambiguity for the engineer who picks it up.

Invocation

Use this skill when you need to:

• Turn a rough idea or conversation into a structured Jira ticket
• Write a bug report with reproducible steps
• Draft a feature request with clear acceptance criteria
• Create the ticket directly in Jira via MCP

Workflow

1. Determine ticket type

Identify the type from the input or ask if unclear:

• Story — new capability or enhancement
• Bug — something broken or behaving incorrectly
• Task — maintenance, refactor, dependency update
• Spike — research or investigation task

2. Gather missing context (batch all questions in one message)

Ask only for what is not already clear:

• What is the desired outcome?
• Why is this needed — what problem or value does it address?
• Who is affected (users, systems, teams)?
• What is explicitly out of scope?
• Any blocking dependencies or related tickets?
• Is this ticket a sub-task of an existing ticket? If yes, get the parent issue key (e.g. PROJ-123). The ticket will be created as a Sub-task under that parent.
• Are there any related/relevant tickets that should be linked? If yes, collect the issue keys and the relationship type (e.g. "relates to", "blocks", "is blocked by", "duplicates").

3. Investigate the codebase with Serena

Before writing the ticket, use Serena via mcporter to ground it in real code. This makes the ticket actionable and accurate.

Serena requires no Cloud ID — it runs as a local stdio process against the project directory.

3a. Find relevant files and symbols:

# Get a symbols overview of the impacted module or directory
npx mcporter call serena.get_symbols_overview \
  relative_path:'<src/relevant-module>'

# Find a specific class or function by name (no body needed for initial scan)
npx mcporter call serena.find_symbol \
  name_path_pattern:'<ClassName>' \
  include_body:false \
  depth:1

# Locate a file by name fragment
npx mcporter call serena.find_file \
  filename_substring:'<filename-fragment>'

# Search for patterns when symbol names are unknown
npx mcporter call serena.search_for_pattern \
  pattern:'<keyword>' \
  relative_path:'src/'

3b. Identify affected files and components (blast radius):

# Find all symbols that reference (depend on) this symbol
npx mcporter call serena.find_referencing_symbols \
  name_path_pattern:'<ClassName>' \
  relative_path:'src/'

List every file likely touched by this change:

• Entry points (controllers, routes, handlers, CLI commands)
• Service/domain layer (business logic, use cases)
• Data layer (models, repositories, migrations, schemas)
• Tests (unit, integration, e2e)
• Configuration / environment variables
• Shared utilities or libraries impacted

3c. Read symbol bodies only when needed:

# Read the full body of a specific method or class
npx mcporter call serena.find_symbol \
  name_path_pattern:'<ClassName>/<methodName>' \
  include_body:true

3d. Document technical context discovered:

Capture what Serena reveals:

• Current behaviour of relevant code paths (exact file paths and symbol names)
• Data models and their relationships
• External dependencies (APIs, queues, caches)
• Known technical debt or complexity in the area
• Patterns used by similar existing features (follow them)

4. Select and fill the appropriate template

Use the templates in templates/ as the basis for the output. All output must be in Jira wiki markup — see references/jira-syntax-quick-reference.md. Never output Markdown in the ticket body.

• Story/Task → templates/feature-template.md
• Bug → templates/bug-template.md
• Spike → use feature template, replace AC section with h2. Definition of Done

Required sections for maximum detail:

• Overview — what this ticket does in one paragraph
• Context / Motivation — why now, what problem it solves, business/technical drivers
• Technical Design — architecture decisions, data flow, API contracts, schema changes
• Affected Components — list of files/modules from Serena investigation (with file paths)
• Implementation Notes — step-by-step guidance, patterns to follow, gotchas
• Edge Cases & Risks — failure modes, race conditions, rollback plan
• Acceptance Criteria — observable outcomes (not tasks); written as "Given/When/Then" or bullet assertions
• Out of Scope — explicit exclusions to prevent scope creep
• Dependencies — blocking tickets, external teams, feature flags

5. Review with user

Present the draft and ask:

• "Does this capture what you need?"
• "Anything missing or incorrect?"

Revise until the user confirms. Then ask:

"Would you like me to create this ticket in Jira now?"

6. Create in Jira (if user confirms)

1. List available projects and confirm the target board with the user before proceeding:

npx mcporter call atlassian.getVisibleJiraProjects

Present the list to the user (project key + name) and ask:

"Which board/project would you like me to create this ticket in?"

Wait for the user's confirmation before continuing. Do not assume or default to any project.

2. Get valid issue types for the selected project:

npx mcporter call atlassian.getJiraProjectIssueTypesMetadata \
  projectKey:'<PROJECT_KEY>'

3. Map the ticket type from step 1 to a valid issue type ID.

   If the user provided a parent ticket key: override the issue type to Sub-task (use the Sub-task type ID from the metadata). The parent field must be set to the parent issue key.

4. Create the ticket:

   Standard ticket:

   npx mcporter call atlassian.createJiraIssue \
     projectKey:'<PROJECT_KEY>' \
     issueType:'<ISSUE_TYPE_ID>' \
     summary:'<TICKET_TITLE>' \
     description:'<MARKDOWN_BODY>'
   

   Sub-task (parent ticket provided):

   npx mcporter call atlassian.createJiraIssue \
     projectKey:'<PROJECT_KEY>' \
     issueType:'<SUBTASK_ISSUE_TYPE_ID>' \
     summary:'<TICKET_TITLE>' \
     description:'<MARKDOWN_BODY>' \
     parent:'<PARENT_ISSUE_KEY>'
   

5. Link to related tickets (if the user provided relevant ticket keys):

   After the ticket is created, call the Jira issue link API for each related ticket:

   npx mcporter call atlassian.fetch \
     url:'https://<domain>.atlassian.net/rest/api/3/issueLink' \
     method:'POST' \
     body:'{"type":{"name":"<LINK_TYPE>"},"inwardIssue":{"key":"<NEW_ISSUE_KEY>"},"outwardIssue":{"key":"<RELATED_ISSUE_KEY>"}}'
   

   Common LINK_TYPE values: "Relates", "Blocks", "Cloners", "Duplicate". Repeat for each related ticket.

6. Return the created issue key and URL to the user. If the ticket is a sub-task, also confirm which parent it was filed under. If tickets were linked, list each linked issue key and the relationship applied.

Note on format: The description field sent to createJiraIssue must be Markdown, not Jira wiki markup. Convert the draft before submitting.

Writing Rules

• Overview = what. Context = why. Acceptance Criteria = done when.
• AC items describe observable outcomes, not implementation tasks.
• Replace vague language: "works correctly" → specific behaviour; "should" → "must".
• Include file paths from Serena — engineers should know exactly where to look.
• Include implementation hints — preferred patterns, existing utilities to reuse.
• Surface risks explicitly — don't bury them.
• A ticket is not a spec, but it must be detailed enough that no clarification is needed to start work.