Skill

MIGRATIONS Jira Project Guide

Skill Version: {{VERSION}} | Check for updates: npx @andrekurait/jira-mcp-skill@latest --version

🔄 Skill Improvement Protocol

When you notice patterns in how I should handle Jira tasks differently, tell me! For example:

• "Always specify a sprint when creating tasks"
• "Default to Story type instead of Task"
• "Always add the RFS component for snapshot-related work"

I'll ask: "Would you like me to add this as a permanent rule in the skill?"

If yes, here's how to contribute the improvement:

Quick Contribution Guide

# 1. Fork the repo (one-time)
gh repo fork AndreKurait/jira-mcp-skill --clone
cd jira-mcp-skill

# 2. Create a branch for your change
git checkout -b feature/your-improvement-name

# 3. Edit the skill guide
# Open skill/SKILL.md and add your rule to the appropriate section

# 4. Commit and push
git add skill/SKILL.md
git commit -m "Add rule: [describe your rule]"
git push origin feature/your-improvement-name

# 5. Create PR
gh pr create --title "Add rule: [your rule]" --body "This adds guidance to [explain what it does]"

Where to Add Rules

Project Overview

Issue Creation Defaults

When creating issues, apply these defaults unless specified otherwise:

Examples of Good Prompts → Actions

• Project Key: MIGRATIONS
• Project Name: Migration and Upgrades
• URL: https://opensearch.atlassian.net/jira/software/c/projects/MIGRATIONS
• Board IDs: 3 (Migrations - All Releases), 39 (Migrations - for estimation API)
• Lead: Brian Presley
• Style: Classic Jira Software

Story Points

Set story points using jira_update_issue with customfield_10032:

{"customfield_10032": 5}

Field: customfield_10032 - Story Points

Sprints

We use monthly sprints named by month and year (e.g., "Feb 2026", "Mar 2026").

• Sprint field: customfield_10020
• Sprints are managed on Board ID 39

Current Sprints

Discovering Sprints

jira_get_sprints_from_board(board_id="39", state="future")  # or "active", "closed"

Adding Issues to Sprint

jira_update_issue(issue_key="MIGRATIONS-XXX", fields={"customfield_10020": 314})

Issue Types

Default: Always create new issues as Story unless it's a defect (Bug). | Sub-task | Part of a larger Story/Task | Child (Level -1) |

Components (20 total)

Core Migration Components

Infrastructure & Tooling

Specialized Components

Workflow Statuses

TRIAGE → Needs Definition → Needs Refinement → To Do → In Progress → Ready for Review → Under Review → Done
                                                  ↓
                                              BLOCKED
                                                  ↓
                                              DROPPED
                                                  ↓
                                             PUBLISHED

Active Versions

Current Development

Special Versions

• for-review: Issues pending review
• not-scheduled-for-release: Backlog items

Labels

Priority Levels

Custom Fields

Issue Link Types

Team Members

User Discovery

Find users via JQL:

project = MIGRATIONS AND assignee IS NOT EMPTY

Or use jira_get_user_profile with display name or email:

jira_get_user_profile(user_identifier="Brian Presley")

Setting Assignee and Reporter

Use display name (e.g., "Andre Kurait") or email for both assignee and reporter fields:

# Set assignee
jira_update_issue(issue_key="MIGRATIONS-XXX", fields={"assignee": "Andre Kurait"})

# Change reporter (requires project admin or "Modify Reporter" permission)
jira_update_issue(issue_key="MIGRATIONS-XXX", fields={"reporter": "Brian Presley"})

The MCP resolves display names to accountIds automatically.

Required Fields for Issue Creation

When creating issues, fixVersions is required. Use:

• {"fixVersions": [{"id": "10021"}]} for "not-scheduled-for-release" (backlog)
• Or specify a release version like MAv3.0, MAv3.1, etc.

To link a task to an epic, use parent field:

{"parent": "MIGRATIONS-1234"}

Useful JQL for Discovery

-- Find team members (unique assignees)
project = MIGRATIONS AND assignee IS NOT EMPTY

-- Find all epics
project = MIGRATIONS AND issuetype = Epic

-- Find tasks under an epic
parent = MIGRATIONS-1234

-- Find unestimated tasks
project = MIGRATIONS AND "Story Points" IS EMPTY AND issuetype = Task

Ticket Writing Best Practices

Jira Wiki Markup Formatting

When writing descriptions, use Jira wiki markup (not markdown):

Important: Avoid # for numbered lists - it can render incorrectly. Use * bullets or explicit numbers instead.

Summary Guidelines

✅ Good Summaries:

• "Implement Migration Confidence Scoring System"
• "aws-bootstrap --build-images cannot build cross-platform"
• "Add Jenkins test for Serverless Target"

❌ Bad Summaries:

• "Fix bug" (too vague)
• "Update code" (no context)
• "URGENT: Need this done" (no description)

Summary Format by Type

Description Templates

Story Template

[Brief description of the user need or feature]

## Background
[Context and motivation]

## Requirements
1. [Requirement 1]
2. [Requirement 2]

## Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]
- [ ] Unit tests
- [ ] Integration tests
- [ ] Documentation updated

Task Template

[What needs to be done and why]

## Details
[Technical details, approach, or constraints]

## Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]

Bug Template

## Problem
[Clear description of the bug]

## Steps to Reproduce
1. [Step 1]
2. [Step 2]
3. [Step 3]

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happens]

## Environment
- Version: [version]
- Platform: [platform]

## Workaround
[If any]

Epic Template

## Overview
[High-level description of the initiative]

## Goals
- [Goal 1]
- [Goal 2]

## Scope
### In Scope
- [Item 1]
- [Item 2]

### Out of Scope
- [Item 1]

## Success Criteria
- [Metric 1]
- [Metric 2]

## Child Issues
- [ ] [Story/Task 1]
- [ ] [Story/Task 2]

Example: Well-Written Story

Summary: Implement Migration Confidence Scoring System

Description:

Create an aggregate confidence scoring system that combines technical parity, 
relevance similarity, and business metrics into a single "migration readiness" 
score to guide go/no-go decisions.

## Confidence Score Components
1. **Data Parity Score (0-100):** Document counts, index metadata
2. **Relevance Score (0-100):** NDCG, ranking correlation
3. **Business Impact Score (0-100):** CTR, conversion rate
4. **Performance Score (0-100):** Latency, throughput
5. **Risk Score (0-100):** Query translation coverage

## Scoring Logic
Overall Confidence = weighted_average(
  Data Parity: 20%,
  Relevance: 30%,
  Business Impact: 30%,
  Performance: 10%,
  Risk Assessment: 10%
)

Recommendation:
  >= 90: Ready for production
  80-89: Ready with minor concerns
  70-79: Needs investigation
  < 70: Not recommended

## Acceptance Criteria
- [ ] Create MigrationConfidenceScorer class
- [ ] Aggregate metrics from all validation sources
- [ ] Calculate weighted confidence score (0-100)
- [ ] Provide per-keyspace confidence scores
- [ ] Generate confidence trend over time
- [ ] Create recommendation engine (ready/not ready)
- [ ] Display confidence score in Migration Console
- [ ] Unit tests for scoring algorithm
- [ ] Integration tests with real migration data

Example: Well-Written Task

Summary: Add Jenkins test for Serverless Target

Description:

Add comprehensive Jenkins CI/CD test coverage for migrations targeting 
OpenSearch Serverless. This ensures that serverless-specific migration 
scenarios are validated automatically in the build pipeline.

## Acceptance Criteria
- [ ] Jenkins test suite includes serverless target test cases
- [ ] Tests validate successful migration to OpenSearch Serverless
- [ ] Tests cover authentication and authorization for serverless
- [ ] Tests verify data integrity after migration to serverless
- [ ] Tests validate performance meets acceptable thresholds
- [ ] Tests run automatically on relevant code changes
- [ ] Test results are reported clearly in Jenkins
- [ ] Failed tests provide actionable error messages
- [ ] Test execution time is reasonable (<30 minutes)

Checklist Before Creating

• Summary is clear and specific
• Type is correct (Epic/Story/Task/Bug)
• Component(s) assigned
• Fix Version set if known
• Priority set appropriately
• Description includes acceptance criteria
• Labels added if applicable
• Epic Link set for Stories/Tasks

JQL Quick Reference

-- My open issues
assignee = currentUser() AND status != Done

-- Issues in current sprint
project = MIGRATIONS AND Sprint in openSprints()

-- Bugs by priority
project = MIGRATIONS AND issuetype = Bug ORDER BY priority DESC

-- Recently updated
project = MIGRATIONS AND updated >= -7d ORDER BY updated DESC

-- Unassigned in backlog
project = MIGRATIONS AND assignee IS EMPTY AND status = "To Do"

-- By component
project = MIGRATIONS AND component = "RFS"

-- By fix version
project = MIGRATIONS AND fixVersion = "MAv3.0"

-- Epics with children
project = MIGRATIONS AND issuetype = Epic AND "Epic Link" IS NOT EMPTY

Refinement Request Output

After creating or updating an issue, always provide a refinement request message for Slack in this format:

Text:

REFINEMENT REQUEST | <ISSUE-KEY> | <Summary> | @bjpres @schohn

Link:

https://opensearch.atlassian.net/browse/<ISSUE-KEY>

This allows the user to paste the text into Slack, then paste the link separately so Slack auto-links it.