jira-workflow-transitions

What this skill does

# 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

```bash
jira issue move PROJ-123
```

This opens an interactive menu showing available transitions.

### Direct Transition

```bash
jira issue move PROJ-123 "In Progress"
```

Moves directly to specified state if transition is available.

### Transition with Comment

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

```bash
jira issue view PROJ-123 --plain
```

Shows current status and available next states.

## Common Transition Patterns

### Starting Work

**From To Do to In Progress:**
```bash
# 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:**
```bash
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:**
```bash
jira issue move PROJ-123 "In Progress" --comment "Addressing review feedback: refactoring auth logic"
```

### Completing Work

**From In Review to Done:**
```bash
jira issue move PROJ-123 "Done" --comment "PR merged. All acceptance criteria met."
```

### Handling Blockers

**From In Progress to Blocked:**
```bash
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:**
```bash
jira issue move PROJ-123 "In Progress" --comment "Blocker resolved. Resuming work."
```

### Closing Issues

**From Done to Closed:**
```bash
jira issue move PROJ-123 "Closed" --comment "Verified in production. No issues reported."
```

### Rejecting Issues

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

**Duplicate:**
```bash
jira issue link PROJ-123 PROJ-100 "duplicates"
jira issue move PROJ-123 "Closed" --resolution "Duplicate" --comment "Duplicate of PROJ-100"
```

**Cannot Reproduce:**
```bash
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:
```bash
jira issue move PROJ-123 "In Progress"
```

✅ Good:
```bash
jira issue move PROJ-123 "In Progress" --comment "Starting with database schema design"
```

### 2. Update Before Transitioning

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

```bash
# 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):
```bash
jira issue move PROJ-123 "Done"  # Directly from In Progress
```

✅ Good (following workflow):
```bash
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:
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
jira issue move PROJ-123 "Reopened" --comment "Bug has reoccurred. New reproduction steps: ..."
```

Or back to ori