AgentSkillsCN

Skill

技能

SKILL.md

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

bash
# 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

Rule TypeSection to Edit
Default field values"Issue Creation Defaults"
Required fields"Required Fields for Issue Creation"
Workflow guidance"Workflow Statuses"
Component selection"Components"
Sprint handling"Sprints"

Project Overview

Issue Creation Defaults

When creating issues, apply these defaults unless specified otherwise:

FieldDefault ValueNotes
Issue TypeStoryUse Task only for non-user-facing work
Fix Versionnot-scheduled-for-release (ID: 10021)Required field
PriorityMediumEscalate only when explicitly urgent
SprintCurrent active sprintAsk user if unsure

Examples of Good Prompts → Actions

User SaysI Should Do
"Create a task for X"Create a Story (not Task), ask about sprint
"Add this to the backlog"Set fixVersion to not-scheduled-for-release
"This is urgent"Set priority to High, add to current sprint
"Create under the RFS epic"Set parent field, add RFS component

Story Points

Set story points using jira_update_issue with customfield_10032:

code
{"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

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

Adding Issues to Sprint

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

Issue Types

TypeDescriptionHierarchyWhen to Use
EpicLarge feature or initiative that needs breakdownParent (Level 1)Group of related stories
StoryUser-facing functionality or deliverableStandard (Level 0)Default for new work
BugProblem or error to fixStandard (Level 0)Defects only
TaskSmall, distinct piece of technical workStandard (Level 0)Rarely - prefer Story

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

ComponentDescription
CaptureProxyProxy that captures ES/OS traffic, sends to source cluster and replayer
ReplayerReads from event streamer and sends events to target cluster
RFSReindex from Snapshot - historical data migration
EventStreamerDurable storage between Proxy and Replayer
Meta Data MigrationMigration of index settings, components, aliases, templates

Infrastructure & Tooling

ComponentDescription
Migration ConsoleFacilitates migration workflow
DeploymentIaC and deployment code
IaC Templates and Container ToolsProvision local and cloud environments
Workflow OrchestrationMigration workflow orchestration with Kubernetes
Tests and InfrastructureCI/CD, stress, and longevity testing
Developer ToolingBuild and development tooling

Specialized Components

ComponentDescription
AssessmentIdentifying breaking changes before migration
ValidationCompares results of traffic sent to source and target
FetchTooling for historical migrations
TransformationsData transformation support
Ingestion ServiceSupport for OpenSearch Ingestion
DocumentationStandalone documentation updates
AWS SolutionsAWS-specific solutions
CompleteSolutionEncapsulates the complete solution
GenAIGenAI-related features

Workflow Statuses

code
TRIAGE → Needs Definition → Needs Refinement → To Do → In Progress → Ready for Review → Under Review → Done
                                                  ↓
                                              BLOCKED
                                                  ↓
                                              DROPPED
                                                  ↓
                                             PUBLISHED
StatusCategoryDescription
TRIAGETo DoNew issues awaiting initial review
Needs DefinitionTo DoRequires more detail/scope
Needs RefinementTo DoNeeds technical breakdown
To DoTo DoReady to be worked on
In ProgressIn ProgressActively being worked
BLOCKEDIn ProgressWaiting on external dependency
Ready for ReviewIn ProgressCode complete, awaiting review
Under ReviewIn ProgressBeing reviewed
DoneDoneCompleted
DROPPEDDoneCancelled/not doing
PUBLISHEDDoneReleased/published

Active Versions

Current Development

VersionDescriptionTarget Date
MAv2.2-2025-02-13
MAv2.3-TBD
MAv2.4-TBD
MAv2.5-TBD
MAv2.6-TBD
MAv3.0Autoscaling2025-02-21
MAv3.1-2025-04-30
MAv4.0Migration Console UI2025-08-29
MAv5.0-TBD

Special Versions

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

Labels

LabelUsage
ProxyCaptureProxy-related work
ReplayerReplayer-related work
OrchestrationWorkflow orchestration work
ValidationValidation-related work
TestingTest infrastructure work
oncall-activityOn-call related issues

Priority Levels

PriorityWhen to Use
HighestCritical blockers, production issues
HighImportant for current release
MediumStandard priority (default)
LowNice to have
LowestFuture consideration

Custom Fields

FieldIDUsage
Story Pointscustomfield_10032Effort estimation
Sprintcustomfield_10020Sprint assignment
Epic Linkcustomfield_10014Link to parent Epic
Start datecustomfield_10015Planned start
Target endcustomfield_10023Target completion
GitHub Issue URLcustomfield_10035Link to GitHub
Flaggedcustomfield_10021Impediment flag

Issue Link Types

Link TypeInwardOutward
Blocksis blocked byblocks
Relatesrelates torelates to
Duplicateis duplicated byduplicates
Clonersis cloned byclones

Team Members

NameEmailRole
Andre Kuraitakurait@amazon.comEngineer
Greg Schohn-Engineer
Jugal Chauhan-Engineer
Mikayla Thompson-Engineer
Brian Presley-Lead

User Discovery

Find users via JQL:

sql
project = MIGRATIONS AND assignee IS NOT EMPTY

Or use jira_get_user_profile with display name or email:

code
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:

python
# 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:

code
{"parent": "MIGRATIONS-1234"}

Useful JQL for Discovery

sql
-- 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

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

TypeFormatExample
Epic[Area] High-level capability"Replayer Gradual Migration Support"
Story[Action] [Feature] for [benefit]"Implement Migration Confidence Scoring System"
Task[Action] [specific item]"Add Jenkins test for Serverless Target"
Bug[Component] [symptom/error]"aws-bootstrap --build-images cannot build cross-platform"

Description Templates

Story Template

markdown
[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

markdown
[What needs to be done and why]

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

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

Bug Template

markdown
## 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

markdown
## 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:

markdown
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:

markdown
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

sql
-- 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