zhongwei/gh-yebot-rad-cc-plugins-plugins-jira-cli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-yebot-rad-cc-plugins-plu…/commands/jira-issue-workflow.md
Zhongwei Li 63eb8220c7 Initial commit
2025-11-30 09:08:00 +08:00

13 KiB
Raw Permalink Blame History

Jira Issue Workflow Command

Complete issue lifecycle management from creation to completion using jira-cli.

Instructions

Guide users through the entire issue lifecycle, from creation to resolution, using jira-cli commands.

Issue Lifecycle Stages

Creation → Assignment → In Progress → Review → Testing → Done → Closed

Each stage has specific actions and best practices.

Stage 1: Issue Creation

Creating a New Issue

Interactive creation (easiest):

jira issue create

This prompts for:

  • Issue type (Bug, Story, Task, etc.)
  • Summary
  • Description
  • Priority
  • Assignee
  • Labels
  • Components

Command-line creation (for automation):

jira issue create \
  --type Bug \
  --priority High \
  --summary "Login page returns 500 error" \
  --body "Detailed description of the issue" \
  --assignee user@example.com \
  --label backend,urgent \
  --component Authentication

Quick creation:

jira issue create --type Task --summary "Update dependencies" --priority Medium

Best Practices for Issue Creation

  1. Clear, concise summary - Describes what, not how

    • ✅ "Login page returns 500 error"
    • ❌ "Fix the code in auth.js"

  2. Detailed description - Include:

    • Steps to reproduce (for bugs)
    • Acceptance criteria (for stories)
    • Context and background
    • Links to related resources

  3. Proper classification:

    • Bug: Something broken that worked before
    • Story: New feature or functionality
    • Task: Work item that's not a bug or feature
    • Epic: Large body of work spanning multiple sprints

  4. Set appropriate priority:

    • Critical: System down, blocking all work
    • High: Major feature broken, affects many users
    • Medium: Important but has workaround
    • Low: Nice to have, minimal impact

Issue Creation Patterns

Bug report with template:

jira issue create --type Bug --summary "API endpoint /users returns 404" --body "
## Steps to Reproduce
1. Navigate to application
2. Click on Users section
3. Observe 404 error

## Expected Behavior
Should display list of users

## Actual Behavior
Returns 404 Not Found

## Environment
- Browser: Chrome 120
- OS: macOS 14
- Version: 2.1.0

## Additional Context
Started happening after deployment v2.1.0
Error logs show: 'Route not found'
"

Story with acceptance criteria:

jira issue create --type Story --summary "Add dark mode toggle" --body "
## User Story
As a user, I want to toggle dark mode so that I can reduce eye strain at night.

## Acceptance Criteria
- [ ] Toggle button in settings menu
- [ ] Persists preference across sessions
- [ ] Applies to all pages
- [ ] Smooth transition animation
- [ ] Respects system preferences by default

## Design
Link to Figma: https://figma.com/design/123
"

Stage 2: Issue Assignment

Assigning Issues

Assign to specific user:

jira issue assign PROJ-123 user@example.com

Assign to self:

jira issue assign PROJ-123 @me

Unassign issue:

jira issue assign PROJ-123 x

When to Assign

  • During sprint planning - Assign stories to team members
  • When starting work - Assign to yourself before moving to "In Progress"
  • For review - Reassign to reviewer
  • When blocked - May unassign and add back to backlog

Finding Unassigned Issues

jira issue list --assignee EMPTY --status "To Do" --plain

Stage 3: Moving to In Progress

Transition Issue to In Progress

Interactive transition:

jira issue move PROJ-123

Select "In Progress" from the menu.

Direct transition:

jira issue move PROJ-123 "In Progress"

With comment:

jira issue move PROJ-123 "In Progress" --comment "Starting work on this issue"

Before Moving to In Progress

  1. Ensure assignment - Issue should be assigned to you
  2. Understand requirements - Read description and acceptance criteria
  3. Check dependencies - Any blocking issues?
  4. Estimate work - Add story points if needed

Viewing Issue Details

jira issue view PROJ-123 --plain

Check:

  • Description and acceptance criteria
  • Comments and discussion
  • Linked issues
  • Attachments
  • Custom fields

Stage 4: During Development

Updating Issue Status

Keep issue updated as work progresses:

Add comments:

jira issue comment PROJ-123 "Implemented authentication logic, now working on UI"

Update fields:

jira issue edit PROJ-123 --priority High
jira issue edit PROJ-123 --label "needs-review"

Linking Related Issues

Link to blocking issue:

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

Link to related issue:

jira issue link PROJ-123 PROJ-124 "relates to"

Add web link:

jira issue link PROJ-123 https://docs.example.com/feature --type web

Common Link Types

  • blocks / is blocked by
  • relates to
  • duplicates / is duplicated by
  • causes / is caused by
  • clones / is cloned by

Tracking Time (if enabled)

Log work on issue:

jira issue worklog add PROJ-123 2h "Implemented authentication"

Stage 5: Moving to Review

Transition to Review

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

Review Checklist Before Transitioning

  • Code complete and tested locally
  • Unit tests written and passing
  • Documentation updated
  • Pull request created
  • PR link added to issue
  • Reviewers assigned

Integration with Pull Requests

Best practice: Link PR to issue

In PR description:

Fixes PROJ-123

## Changes
- Added authentication logic
- Updated user model
- Added tests

Or in commit messages:

git commit -m "PROJ-123: Add user authentication

Implemented OAuth2 authentication flow.
See PROJ-123 for requirements."

Stage 6: Testing and QA

If Issue Fails Review

Move back to In Progress:

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

Address feedback then move back to Review

Moving to Testing

jira issue move PROJ-123 "Testing" --comment "Deployed to staging: https://staging.example.com"

QA Checklist

  • Meets acceptance criteria
  • No regression in existing features
  • Works in all supported environments
  • Performance is acceptable
  • Security best practices followed

Stage 7: Completion

Moving to Done

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

Verification Before Closing

  • All acceptance criteria satisfied
  • Tested and approved
  • Documented (if needed)
  • Deployed (for features/bugs)
  • Stakeholders notified

Adding Resolution

Some workflows require setting resolution:

jira issue move PROJ-123 "Closed" --resolution "Fixed"

Common resolutions:

  • Fixed - Bug fixed or feature completed
  • Won't Fix - Decision not to address
  • Duplicate - Same as another issue
  • Cannot Reproduce - Bug not reproducible
  • Done - Task completed

Stage 8: Closure and Retrospective

Closing Issue

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

Post-Closure Activities

  1. Verify in production - Ensure fix/feature works
  2. Update documentation - User docs, wiki, etc.
  3. Notify stakeholders - Let relevant parties know
  4. Link related issues - If this resolves others
  5. Add retrospective notes - What went well, what didn't

Common Workflows

Bug Fix Workflow

# 1. Create bug
jira issue create --type Bug --summary "..." --priority High

# 2. Assign to self and start
jira issue assign PROJ-123 @me
jira issue move PROJ-123 "In Progress"

# 3. Fix and create PR
# ... develop fix ...
git commit -m "PROJ-123: Fix login error"

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

# 5. After PR approval, merge and test
# ... merge PR ...

# 6. Move to testing
jira issue move PROJ-123 "Testing" --comment "Deployed to staging"

# 7. After QA approval
jira issue move PROJ-123 "Done" --comment "Verified on staging"

# 8. After production deployment
jira issue move PROJ-123 "Closed" --comment "Deployed to production in release v2.1.1"

Feature Development Workflow

# 1. Create story
jira issue create --type Story --summary "Add dark mode toggle" --body "..."

# 2. Break down into subtasks (if needed)
jira issue create --type Subtask --parent PROJ-123 --summary "Create dark mode CSS"
jira issue create --type Subtask --parent PROJ-123 --summary "Add toggle component"
jira issue create --type Subtask --parent PROJ-123 --summary "Persist user preference"

# 3. Work through each subtask
jira issue move PROJ-124 "In Progress"
# ... develop ...
jira issue move PROJ-124 "Done"

# 4. When all subtasks done, complete parent story
jira issue move PROJ-123 "Done"

Blocked Issue Workflow

# 1. Working on issue, discover blocker
jira issue move PROJ-123 "Blocked" --comment "Blocked by API issue PROJ-100"

# 2. Link to blocking issue
jira issue link PROJ-123 PROJ-100 "is blocked by"

# 3. When blocker resolved
jira issue move PROJ-123 "In Progress" --comment "Blocker resolved, resuming work"

Bulk Operations

Moving Multiple Issues

For sprint planning or cleanup:

# Get list of issues
jira issue list --status "To Do" --plain

# Move them (one at a time or use script)
jira issue move PROJ-123 "Backlog"
jira issue move PROJ-124 "Backlog"
jira issue move PROJ-125 "Backlog"

Batch Assignment

# Assign multiple issues to team member
jira issue assign PROJ-123 developer@example.com
jira issue assign PROJ-124 developer@example.com
jira issue assign PROJ-125 developer@example.com

Viewing Workflow States

Available Transitions

To see available transitions for an issue:

jira issue move PROJ-123

This shows all possible next states based on current state and workflow configuration.

Issue History

View all changes to an issue:

jira issue view PROJ-123 --plain

Scroll to history section to see all transitions, edits, and comments.

Best Practices

  1. Update issues regularly - Keep status current
  2. Add meaningful comments - Explain changes and decisions
  3. Link related work - Connect PRs, issues, and documentation
  4. Follow workflow - Don't skip states
  5. Use appropriate transitions - Don't move directly from "To Do" to "Done"
  6. Maintain traceability - Always reference issue keys in commits/PRs
  7. Close issues promptly - Don't leave completed work open
  8. Add resolution when closing - Document why/how resolved

Automation Integration

Git Hooks

Add to .git/hooks/commit-msg:

#!/bin/bash
commit_msg_file=$1
commit_msg=$(cat "$commit_msg_file")

# Check if commit message contains issue key
if ! echo "$commit_msg" | grep -qE "PROJ-[0-9]+"; then
  echo "ERROR: Commit message must reference a Jira issue (e.g., PROJ-123)"
  exit 1
fi

CI/CD Integration

In your CI/CD pipeline:

# Extract issue key from branch or commit
ISSUE_KEY=$(git branch --show-current | grep -oE "PROJ-[0-9]+")

# Add deployment comment
jira issue comment "$ISSUE_KEY" "Deployed to staging by CI/CD pipeline #${BUILD_NUMBER}"

# Optionally transition
jira issue move "$ISSUE_KEY" "Testing" --comment "Automated deployment to staging"

Definition of Done

  • Understand the complete issue lifecycle
  • Can create issues with proper details
  • Can assign issues to self and others
  • Can transition issues through workflow states
  • Can add comments and updates to issues
  • Can link related issues and PRs
  • Can close issues with appropriate resolution
  • Understand when to use each workflow state
  • Know how to handle blocked or problematic issues
  • Can integrate Jira updates with development workflow

Troubleshooting

Issue won't transition:

  • Check if you have required fields filled
  • Verify you have permission for that transition
  • Some transitions require specific roles
  • Try interactive mode to see available options

Can't find issue:

  • Verify issue key is correct (PROJ-123)
  • Check if you have access to that project
  • Ensure issue hasn't been deleted

Workflow differs from docs:

  • Workflows are customizable per project
  • Run jira issue move PROJ-123 to see your project's workflow
  • Contact Jira admin for workflow documentation

Next Steps

  • Use /jira-sprint-planning for sprint management
  • Use jira-query-builder agent for finding issues
  • Integrate with git workflows and CI/CD
  • Set up automation for common transitions
  • Create templates for different issue types
Reference in New Issue View Git Blame Copy Permalink