gh-yebot-rad-cc-plugins-plugins-jira-cli/skills/jira-workflow-transitions/SKILL.md

Jira Workflow Transitions Skill

Understanding and navigating Jira workflow states and transitions using jira-cli.

Overview

Jira workflows define how issues move through different states from creation to completion. This skill helps you understand workflow concepts and effectively transition issues using jira-cli.

Workflow Fundamentals

What is a Workflow?

A workflow is a set of statuses and transitions that an issue moves through during its lifecycle.

Status: Current state of an issue (e.g., "To Do", "In Progress", "Done")

Transition: Action that moves an issue from one status to another (e.g., "Start Progress", "Resolve")

Common Workflow Types

1. Basic Workflow

To Do → In Progress → Done

2. Scrum Workflow

Backlog → To Do → In Progress → In Review → Done → Closed

3. Complex Workflow

Open → In Progress → In Review → Testing → Blocked
                                         ↓
                                        Done → Closed

Standard Workflow States

Initial States

Backlog

• Issues that might be worked on in future
• Not yet committed to a sprint
• May need grooming

To Do

• Ready to be worked on
• Accepted into sprint or ready for picking up
• All requirements clear

Open

• Newly created issue
• Needs triage or assignment
• May need more information

Active Work States

In Progress

• Actively being worked on
• Assigned to someone
• Development underway

In Review

• Code/work completed
• Awaiting peer review or approval
• Pull request open

Testing / QA

• Under quality assurance testing
• Verification of acceptance criteria
• May be on staging environment

Blocked States

Blocked

• Cannot proceed
• Waiting on external dependency
• Requires resolution of blocker

Waiting for Info

• Need clarification or additional details
• Awaiting stakeholder input
• Cannot proceed without information

Completion States

Done

• Work completed
• Accepted by product owner
• Meets Definition of Done

Closed

• Fully resolved and closed
• No further action needed
• Archived state

Resolved

• Issue addressed
• May need verification
• Intermediate completion state

Rejection States

Won't Fix

• Decision not to address
• Out of scope
• Not a priority

Duplicate

• Same as another issue
• Linked to original issue
• Closed as duplicate

Cannot Reproduce

• Bug cannot be reproduced
• Insufficient information
• May reopen if new info emerges

Transitioning Issues

Basic Transition

jira issue move PROJ-123

This opens an interactive menu showing available transitions.

Direct Transition

jira issue move PROJ-123 "In Progress"

Moves directly to specified state if transition is available.

Transition with Comment

jira issue move PROJ-123 "Done" --comment "Completed feature implementation. Ready for deployment."

Always add comments to provide context about the transition.

Checking Available Transitions

jira issue view PROJ-123 --plain

Shows current status and available next states.

Common Transition Patterns

Starting Work

From To Do to In Progress:

# 1. Assign to yourself
jira issue assign PROJ-123 @me

# 2. Move to In Progress
jira issue move PROJ-123 "In Progress" --comment "Starting work on authentication feature"

Submitting for Review

From In Progress to In Review:

jira issue move PROJ-123 "In Review" --comment "PR created: https://github.com/company/repo/pull/456"

Handling Review Feedback

From In Review back to In Progress:

jira issue move PROJ-123 "In Progress" --comment "Addressing review feedback: refactoring auth logic"

Completing Work

From In Review to Done:

jira issue move PROJ-123 "Done" --comment "PR merged. All acceptance criteria met."

Handling Blockers

From In Progress to Blocked:

jira issue move PROJ-123 "Blocked" --comment "Waiting for API spec from backend team"
jira issue link PROJ-123 PROJ-100 "is blocked by"

From Blocked back to In Progress:

jira issue move PROJ-123 "In Progress" --comment "Blocker resolved. Resuming work."

Closing Issues

From Done to Closed:

jira issue move PROJ-123 "Closed" --comment "Verified in production. No issues reported."

Rejecting Issues

Won't Fix:

jira issue move PROJ-123 "Closed" --resolution "Won't Fix" --comment "Decision: Out of scope for current roadmap"

Duplicate:

jira issue link PROJ-123 PROJ-100 "duplicates"
jira issue move PROJ-123 "Closed" --resolution "Duplicate" --comment "Duplicate of PROJ-100"

Cannot Reproduce:

jira issue move PROJ-123 "Closed" --resolution "Cannot Reproduce" --comment "Unable to reproduce. Please reopen with more details if issue persists."

Workflow Best Practices

1. Always Add Comments

❌ Bad:

jira issue move PROJ-123 "In Progress"

✅ Good:

jira issue move PROJ-123 "In Progress" --comment "Starting with database schema design"

2. Update Before Transitioning

# Update fields first
jira issue edit PROJ-123 --priority High
jira issue assign PROJ-123 @me

# Then transition
jira issue move PROJ-123 "In Progress"

3. Link Related Work

# When moving to review, link PR
jira issue move PROJ-123 "In Review" --comment "PR: https://github.com/company/repo/pull/456"

# When blocking, link blocker
jira issue move PROJ-123 "Blocked"
jira issue link PROJ-123 PROJ-100 "is blocked by"

4. Don't Skip States

❌ Bad (skipping review):

jira issue move PROJ-123 "Done"  # Directly from In Progress

✅ Good (following workflow):

jira issue move PROJ-123 "In Review"  # From In Progress
# ... review happens ...
jira issue move PROJ-123 "Done"       # From In Review

5. Verify Before Completion

Before moving to Done:

# Review issue details
jira issue view PROJ-123 --plain

# Check acceptance criteria met
# Verify tests passing
# Confirm deployment successful

# Then complete
jira issue move PROJ-123 "Done" --comment "All acceptance criteria met. Deployed to production."

Workflow States by Issue Type

Bug Workflow

Open → In Progress → In Review → Testing → Fixed → Closed
                              ↓
                            Cannot Reproduce
                            Won't Fix

Key transitions:

# Start fix
jira issue move BUG-123 "In Progress" --comment "Investigating root cause"

# Submit fix
jira issue move BUG-123 "In Review" --comment "Fix PR: ..."

# After QA
jira issue move BUG-123 "Fixed" --comment "Verified on staging"

# After deployment
jira issue move BUG-123 "Closed" --comment "Fix deployed to production"

Story Workflow

Backlog → To Do → In Progress → In Review → Done → Closed

Key transitions:

# Sprint planning
jira issue move STORY-123 "To Do" --comment "Added to Sprint 42"

# Start development
jira issue move STORY-123 "In Progress"

# Code review
jira issue move STORY-123 "In Review" --comment "PR: ..."

# Accept story
jira issue move STORY-123 "Done" --comment "Demo approved by PO"

Task Workflow

To Do → In Progress → Done

Key transitions:

# Simple workflow
jira issue move TASK-123 "In Progress"
# ... work ...
jira issue move TASK-123 "Done"

Epic Workflow

To Do → In Progress → Done → Closed

Epics transition when child stories complete:

# Start epic when first story starts
jira issue move EPIC-100 "In Progress"

# Complete epic when all stories done
jira issue move EPIC-100 "Done" --comment "All stories completed. Feature fully implemented."

Handling Special Cases

Reopening Issues

Reopen a closed issue:

jira issue move PROJ-123 "Reopened" --comment "Bug has reoccurred. New reproduction steps: ..."

Or back to original state:

jira issue move PROJ-123 "In Progress" --comment "Reopening to address regression"

Moving Between Sprints

# Issue incomplete at sprint end
jira issue move PROJ-123 "To Do" --comment "Moving to Sprint 43 due to blocker"
jira sprint add <NEXT_SPRINT_ID> PROJ-123

Escalating Priority

# Change priority
jira issue edit PROJ-123 --priority Critical

# Add urgency label
jira issue edit PROJ-123 --label urgent

# Move up in workflow if needed
jira issue move PROJ-123 "In Progress" --comment "Escalated to critical. Addressing immediately."

Split Issues

When an issue is too large:

# Create new issues
jira issue create --type Story --summary "Part 1: ..." --parent PROJ-123
jira issue create --type Story --summary "Part 2: ..." --parent PROJ-123

# Close original or mark as epic
jira issue edit PROJ-123 --type Epic

Workflow Automation

Git Integration

Pre-commit hook:

#!/bin/bash
# Ensure commits reference Jira issue
if ! git log -1 --pretty=%B | grep -qE "PROJ-[0-9]+"; then
  echo "ERROR: Commit must reference Jira issue"
  exit 1
fi

Post-merge hook:

#!/bin/bash
# Auto-transition after merge
ISSUE_KEY=$(git log -1 --pretty=%B | grep -oE "PROJ-[0-9]+")
if [ -n "$ISSUE_KEY" ]; then
  jira issue move "$ISSUE_KEY" "Testing" --comment "Merged to main. Ready for QA."
fi

CI/CD Integration

On deployment:

#!/bin/bash
# Extract issue keys from commits since last deploy
ISSUES=$(git log --pretty=%B $LAST_TAG..HEAD | grep -oE "PROJ-[0-9]+" | sort -u)

# Transition each issue
for issue in $ISSUES; do
  jira issue move "$issue" "Testing" --comment "Deployed to staging by CI/CD pipeline"
done

Scheduled Status Updates

Daily reminder script:

#!/bin/bash
# Find stale "In Progress" issues
jira issue list --jql "\
  status = 'In Progress' AND \
  updated <= -3d AND \
  assignee = currentUser() \
" --plain

echo "Reminder: Update status on above issues"

Troubleshooting Transitions

Issue Won't Transition

Problem: Transition not available

Solutions:

1. Check current status

   jira issue view PROJ-123 --plain
   

2. View available transitions

   jira issue move PROJ-123  # Interactive mode shows options
   

3. Check required fields

   • Some transitions require fields to be filled
   • Use interactive mode to see requirements

4. Verify permissions

   • You may not have permission for certain transitions
   • Contact Jira admin if needed

Missing Transition

Problem: Expected transition not showing

Possible causes:

• Workflow doesn't include that transition
• Conditional transition based on field values
• Permission restrictions
• Issue type has different workflow

Solution:

# Check what transitions are available
jira issue move PROJ-123

# Ask admin about workflow configuration

Stuck in Status

Problem: Issue stuck in a status

Solutions:

1. Check for blockers

   jira issue view PROJ-123 --plain
   

2. Add comment explaining situation

   jira issue comment PROJ-123 "Stuck waiting for X. Escalating to Y."
   

3. Link blocking issues

   jira issue link PROJ-123 PROJ-100 "is blocked by"
   

4. Move to Blocked status

   jira issue move PROJ-123 "Blocked" --comment "Cannot proceed due to X"
   

Accidental Transition

Problem: Moved to wrong status

Solution:

# Move back to correct status
jira issue move PROJ-123 "In Progress" --comment "Moved back to In Progress. Was accidentally marked as Done."

Workflow Metrics

Cycle Time

Time from "In Progress" to "Done":

# Issues completed this week
jira issue list --jql "\
  status = Done AND \
  resolved >= startOfWeek() \
" --raw

Calculate: resolved_date - in_progress_date

Lead Time

Time from "To Do" to "Done":

# All resolved issues
jira issue list --jql "resolved >= startOfMonth()" --raw

Calculate: resolved_date - created_date

Status Distribution

# Count issues by status
jira issue list --status "In Progress" --raw | grep -c key
jira issue list --status "In Review" --raw | grep -c key
jira issue list --status "Done" --raw | grep -c key

Blocked Issue Tracking

# Currently blocked
jira issue list --status Blocked --plain

# How long blocked
jira issue list --jql "status = Blocked" --raw

Custom Workflows

Organizations often customize workflows. To understand your workflow:

1. View current issue state:

   jira issue view PROJ-123 --plain
   

2. See available transitions:

   jira issue move PROJ-123  # Interactive mode
   

3. Check workflow diagram:

   • Ask Jira admin for workflow documentation
   • Or view in Jira UI: Project Settings → Workflows

4. Document for team: Create a workflow guide specific to your project

When to Use This Skill

• Learning Jira workflow concepts
• Transitioning issues appropriately
• Handling blocked or stuck issues
• Integrating workflows with git/CI/CD
• Troubleshooting transition issues
• Understanding team's specific workflow

Best Practices Summary

1. Always add meaningful comments when transitioning
2. Follow the workflow - don't skip states
3. Update issue details before transitioning
4. Link related work (PRs, blockers, etc.)
5. Use appropriate transitions for issue type
6. Verify completion before marking Done
7. Handle blockers explicitly - don't leave hanging
8. Document custom workflows for team reference

Next Steps

• Document your team's specific workflows
• Create scripts for common transition patterns
• Set up automation for workflow events
• Define clear Definition of Done for each state
• Establish team norms around transitions