Initial commit

2025-11-30 09:08:00 +08:00
commit 63eb8220c7
11 changed files with 3971 additions and 0 deletions
--- a/skills/jira-jql-patterns/SKILL.md
+++ b/skills/jira-jql-patterns/SKILL.md
@@ -0,0 +1,668 @@
+# JQL Patterns Skill
+
+Master JQL (Jira Query Language) query construction for advanced issue filtering and reporting.
+
+## Overview
+
+JQL is Jira's powerful query language for finding issues. This skill provides patterns and templates for constructing effective queries using jira-cli.
+
+## Basic JQL Structure
+
+```
+field operator value [AND|OR field operator value]
+```
+
+## Essential Field Reference
+
+### Issue Fields
+
+| Field | Type | Example |
+|-------|------|---------|
+| `project` | Text | `project = PROJ` |
+| `key` | Text | `key = PROJ-123` |
+| `summary` | Text | `summary ~ "login"` |
+| `description` | Text | `description ~ "error"` |
+| `status` | Text | `status = "In Progress"` |
+| `priority` | Text | `priority IN (High, Critical)` |
+| `type` | Text | `type = Bug` |
+| `labels` | List | `labels = urgent` |
+| `component` | Text | `component = Backend` |
+| `fixVersion` | Version | `fixVersion = "1.0"` |
+| `resolution` | Text | `resolution = Fixed` |
+
+### People Fields
+
+| Field | Type | Example |
+|-------|------|---------|
+| `assignee` | User | `assignee = currentUser()` |
+| `reporter` | User | `reporter = "user@example.com"` |
+| `creator` | User | `creator = currentUser()` |
+| `watcher` | User | `watcher = currentUser()` |
+
+### Date Fields
+
+| Field | Type | Example |
+|-------|------|---------|
+| `created` | Date | `created >= -7d` |
+| `updated` | Date | `updated >= startOfWeek()` |
+| `resolved` | Date | `resolved >= "2024-01-01"` |
+| `duedate` | Date | `duedate <= now()` |
+
+### Agile Fields
+
+| Field | Type | Example |
+|-------|------|---------|
+| `sprint` | Sprint | `sprint = 123` |
+| `"Epic Link"` | Epic | `"Epic Link" = PROJ-100` |
+| `"Story Points"` | Number | `"Story Points" > 5` |
+
+## Operators Reference
+
+### Equality
+
+- `=` - Equals
+- `!=` - Not equals
+- `IN` - In list
+- `NOT IN` - Not in list
+
+### Comparison
+
+- `>` - Greater than
+- `>=` - Greater than or equal
+- `<` - Less than
+- `<=` - Less than or equal
+
+### Text Search
+
+- `~` - Contains (case-insensitive)
+- `!~` - Does not contain
+- `IS` - For checking null/empty
+- `IS NOT` - For checking not null/empty
+
+### Special
+
+- `IS EMPTY` - Field has no value
+- `IS NOT EMPTY` - Field has value
+- `WAS` - Historical value
+- `CHANGED` - Field was changed
+
+## JQL Functions
+
+### User Functions
+
+```jql
+assignee = currentUser()
+reporter = currentUser()
+watcher = currentUser()
+assignee IN membersOf("developers")
+```
+
+### Date Functions
+
+```jql
+created >= startOfDay()
+created <= endOfDay()
+created >= startOfWeek()
+created >= startOfMonth()
+created >= startOfYear()
+
+updated >= startOfDay(-7)  # 7 days ago
+duedate <= endOfWeek(1)     # End of next week
+```
+
+### Sprint Functions
+
+```jql
+sprint IN openSprints()
+sprint IN closedSprints()
+sprint IN futureSprints()
+```
+
+## Common Query Patterns
+
+### My Work Queries
+
+**Current work:**
+```jql
+assignee = currentUser() AND status NOT IN (Done, Closed)
+```
+
+**Recently completed:**
+```jql
+assignee = currentUser() AND status = Done AND resolved >= -7d
+```
+
+**Reported by me:**
+```jql
+reporter = currentUser() AND status NOT IN (Done, Closed)
+```
+
+**Watching:**
+```jql
+watcher = currentUser() AND status NOT IN (Done, Closed)
+```
+
+### Priority Queries
+
+**Critical and high priority open:**
+```jql
+priority IN (Critical, High) AND status NOT IN (Done, Closed, Resolved)
+```
+
+**Urgent bugs:**
+```jql
+type = Bug AND priority = Critical AND status NOT IN (Done, Closed)
+```
+
+**Prioritized backlog:**
+```jql
+status = "To Do" AND priority IN (High, Medium) ORDER BY priority DESC
+```
+
+### Time-Based Queries
+
+**Created today:**
+```jql
+created >= startOfDay()
+```
+
+**Updated this week:**
+```jql
+updated >= startOfWeek()
+```
+
+**Created in last 30 days:**
+```jql
+created >= -30d
+```
+
+**Overdue issues:**
+```jql
+duedate < now() AND status NOT IN (Done, Closed)
+```
+
+**Due this week:**
+```jql
+duedate >= startOfWeek() AND duedate <= endOfWeek()
+```
+
+**Stale issues (not updated in 90 days):**
+```jql
+updated <= -90d AND status NOT IN (Done, Closed)
+```
+
+### Team Queries
+
+**Unassigned issues:**
+```jql
+assignee IS EMPTY AND status = "To Do"
+```
+
+**Team workload:**
+```jql
+assignee IN (user1@example.com, user2@example.com) AND status IN ("In Progress", "To Do")
+```
+
+**Blocked issues:**
+```jql
+status = Blocked OR labels = blocked
+```
+
+**Issues needing review:**
+```jql
+status = "In Review" AND assignee IS NOT EMPTY
+```
+
+### Sprint Queries
+
+**Current sprint:**
+```jql
+sprint IN openSprints()
+```
+
+**Current sprint for project:**
+```jql
+project = PROJ AND sprint IN openSprints()
+```
+
+**Specific sprint:**
+```jql
+sprint = 123
+```
+
+**Issues without sprint:**
+```jql
+type IN (Story, Bug, Task) AND sprint IS EMPTY
+```
+
+**Incomplete sprint items:**
+```jql
+sprint = 123 AND status NOT IN (Done, Closed)
+```
+
+### Epic Queries
+
+**All issues in epic:**
+```jql
+"Epic Link" = PROJ-100
+```
+
+**Completed epic issues:**
+```jql
+"Epic Link" = PROJ-100 AND status = Done
+```
+
+**Issues without epic:**
+```jql
+type = Story AND "Epic Link" IS EMPTY
+```
+
+### Bug Tracking Queries
+
+**Open bugs:**
+```jql
+type = Bug AND status NOT IN (Done, Closed, "Won't Fix")
+```
+
+**Critical production bugs:**
+```jql
+type = Bug AND priority = Critical AND labels = production AND status NOT IN (Done, Closed)
+```
+
+**Bugs by component:**
+```jql
+type = Bug AND component = Backend AND status NOT IN (Done, Closed)
+```
+
+**Recently fixed bugs:**
+```jql
+type = Bug AND status = Done AND resolved >= -7d
+```
+
+**Regression bugs:**
+```jql
+type = Bug AND labels = regression AND status NOT IN (Done, Closed)
+```
+
+### Story Queries
+
+**Ready for development:**
+```jql
+type = Story AND status = "To Do" AND "Story Points" IS NOT EMPTY
+```
+
+**Unestimated stories:**
+```jql
+type = Story AND "Story Points" IS EMPTY AND status = "To Do"
+```
+
+**Large stories (need breakdown):**
+```jql
+type = Story AND "Story Points" >= 13
+```
+
+### Component Queries
+
+**Frontend issues:**
+```jql
+component = Frontend AND status NOT IN (Done, Closed)
+```
+
+**Backend bugs:**
+```jql
+component = Backend AND type = Bug AND status NOT IN (Done, Closed)
+```
+
+**Issues without component:**
+```jql
+component IS EMPTY AND type IN (Story, Bug, Task)
+```
+
+### Label Queries
+
+**Technical debt:**
+```jql
+labels = tech-debt AND status NOT IN (Done, Closed)
+```
+
+**Multiple labels:**
+```jql
+labels IN (urgent, critical) AND status NOT IN (Done, Closed)
+```
+
+**Issues without labels:**
+```jql
+labels IS EMPTY AND type IN (Story, Bug)
+```
+
+## Advanced Patterns
+
+### Complex Logic with Parentheses
+
+```jql
+project = PROJ AND
+(priority = Critical OR labels = urgent) AND
+status NOT IN (Done, Closed)
+ORDER BY created DESC
+```
+
+### Historical Queries
+
+**Issues that were in progress:**
+```jql
+status WAS "In Progress" DURING (-7d, now())
+```
+
+**Issues that changed priority:**
+```jql
+priority CHANGED DURING (-30d, now())
+```
+
+**Issues moved to done this week:**
+```jql
+status CHANGED TO Done DURING (startOfWeek(), now())
+```
+
+### Negative Queries
+
+**Not assigned to specific team:**
+```jql
+assignee NOT IN membersOf("qa-team")
+```
+
+**Exclude certain statuses:**
+```jql
+status NOT IN (Done, Closed, "Won't Fix", Duplicate)
+```
+
+**Not labeled:**
+```jql
+labels IS EMPTY
+```
+
+### Multi-Project Queries
+
+**Across projects:**
+```jql
+project IN (PROJ1, PROJ2, PROJ3) AND assignee = currentUser()
+```
+
+**All projects bugs:**
+```jql
+type = Bug AND priority = Critical AND status NOT IN (Done, Closed)
+```
+
+## Sorting Patterns
+
+### Single Sort
+
+```jql
+ORDER BY priority DESC
+ORDER BY created ASC
+ORDER BY updated DESC
+ORDER BY duedate ASC
+```
+
+### Multiple Sort
+
+```jql
+ORDER BY priority DESC, created ASC
+ORDER BY status ASC, priority DESC, updated DESC
+ORDER BY duedate ASC, priority DESC
+```
+
+## Using with jira-cli
+
+### Basic Query
+
+```bash
+jira issue list --jql "assignee = currentUser() AND status = 'In Progress'"
+```
+
+### Multi-line for Readability
+
+```bash
+jira issue list --jql "\
+  project = PROJ AND \
+  status IN ('In Progress', 'In Review') AND \
+  assignee = currentUser() AND \
+  created >= -7d \
+  ORDER BY priority DESC"
+```
+
+### With Output Formats
+
+```bash
+# Human readable
+jira issue list --jql "..." --plain
+
+# JSON for parsing
+jira issue list --jql "..." --raw
+
+# CSV for export
+jira issue list --jql "..." --csv
+```
+
+## Report Patterns
+
+### Sprint Velocity
+
+```jql
+sprint = 123 AND status = Done
+```
+
+Sum story points from results.
+
+### Bug Trend
+
+```jql
+type = Bug AND created >= -30d
+```
+
+```jql
+type = Bug AND resolved >= -30d
+```
+
+Compare created vs resolved.
+
+### Team Performance
+
+```jql
+assignee IN membersOf("dev-team") AND
+status = Done AND
+resolved >= startOfWeek()
+```
+
+### Epic Progress
+
+```jql
+"Epic Link" = PROJ-100
+```
+
+```jql
+"Epic Link" = PROJ-100 AND status = Done
+```
+
+Calculate percentage complete.
+
+### Technical Debt Tracking
+
+```jql
+labels = tech-debt AND
+status NOT IN (Done, Closed) AND
+created <= -90d
+ORDER BY priority DESC, created ASC
+```
+
+## Query Optimization Tips
+
+### 1. Narrow by Project First
+
+❌ Slow:
+```jql
+status = "In Progress"
+```
+
+✅ Fast:
+```jql
+project = PROJ AND status = "In Progress"
+```
+
+### 2. Use Specific Operators
+
+❌ Slow:
+```jql
+summary ~ ".*login.*"
+```
+
+✅ Fast:
+```jql
+summary ~ "login"
+```
+
+### 3. Limit Results
+
+```bash
+jira issue list --jql "..." --limit 100
+```
+
+### 4. Use IS EMPTY Instead of Negation
+
+❌ Slower:
+```jql
+assignee != null
+```
+
+✅ Faster:
+```jql
+assignee IS NOT EMPTY
+```
+
+## Common Mistakes
+
+### Mistake 1: Missing Quotes
+
+❌ Wrong:
+```jql
+status = In Progress
+```
+
+✅ Correct:
+```jql
+status = "In Progress"
+```
+
+### Mistake 2: Wrong Function
+
+❌ Wrong:
+```jql
+assignee = me
+```
+
+✅ Correct:
+```jql
+assignee = currentUser()
+```
+
+### Mistake 3: Wrong Field Name
+
+❌ Wrong:
+```jql
+epic = PROJ-100
+```
+
+✅ Correct:
+```jql
+"Epic Link" = PROJ-100
+```
+
+### Mistake 4: Wrong Date Format
+
+❌ Wrong:
+```jql
+created > 7d
+```
+
+✅ Correct:
+```jql
+created >= -7d
+```
+
+## Debugging Queries
+
+### Step 1: Simplify
+
+Start with basic query:
+```jql
+project = PROJ
+```
+
+### Step 2: Add Conditions Incrementally
+
+```jql
+project = PROJ AND status = "In Progress"
+```
+
+```jql
+project = PROJ AND status = "In Progress" AND assignee = currentUser()
+```
+
+### Step 3: Test Each Addition
+
+Run query after each change to identify issues.
+
+### Step 4: Check Field Names
+
+Verify custom field names in Jira UI.
+
+### Step 5: Use --debug
+
+```bash
+jira issue list --jql "..." --debug
+```
+
+## Saving Common Queries
+
+### Shell Aliases
+
+```bash
+alias jira-my-work='jira issue list --jql "assignee = currentUser() AND status NOT IN (Done, Closed)" --plain'
+alias jira-urgent='jira issue list --jql "priority IN (Critical, High) AND status NOT IN (Done, Closed)" --plain'
+alias jira-sprint='jira issue list --jql "sprint IN openSprints()" --plain'
+```
+
+### Script Functions
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+jira-find() {
+  local query="$1"
+  jira issue list --jql "summary ~ \"$query\" OR description ~ \"$query\"" --plain
+}
+
+jira-my-bugs() {
+  jira issue list --jql "assignee = currentUser() AND type = Bug AND status NOT IN (Done, Closed)" --plain
+}
+
+jira-overdue() {
+  jira issue list --jql "duedate < now() AND status NOT IN (Done, Closed)" --plain
+}
+```
+
+## When to Use This Skill
+
+- User needs complex issue filtering
+- Generating reports or metrics
+- Finding issues across projects
+- Historical queries
+- Performance optimization needed
+- Combining multiple criteria
+
+## Next Steps
+
+After mastering JQL:
+1. Create saved queries for common needs
+2. Integrate queries into automation scripts
+3. Build dashboards based on queries
+4. Share query templates with team
+5. Document organization-specific patterns
--- a/skills/jira-workflow-transitions/SKILL.md
+++ b/skills/jira-workflow-transitions/SKILL.md
@@ -0,0 +1,636 @@
+# 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 original state:
+```bash
+jira issue move PROJ-123 "In Progress" --comment "Reopening to address regression"
+```
+
+### Moving Between Sprints
+
+```bash
+# 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
+
+```bash
+# 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:
+```bash
+# 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:**
+```bash
+#!/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:**
+```bash
+#!/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:**
+```bash
+#!/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:**
+```bash
+#!/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
+   ```bash
+   jira issue view PROJ-123 --plain
+   ```
+
+2. View available transitions
+   ```bash
+   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:**
+```bash
+# 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
+   ```bash
+   jira issue view PROJ-123 --plain
+   ```
+
+2. Add comment explaining situation
+   ```bash
+   jira issue comment PROJ-123 "Stuck waiting for X. Escalating to Y."
+   ```
+
+3. Link blocking issues
+   ```bash
+   jira issue link PROJ-123 PROJ-100 "is blocked by"
+   ```
+
+4. Move to Blocked status
+   ```bash
+   jira issue move PROJ-123 "Blocked" --comment "Cannot proceed due to X"
+   ```
+
+### Accidental Transition
+
+**Problem:** Moved to wrong status
+
+**Solution:**
+```bash
+# 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":
+```bash
+# 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":
+```bash
+# All resolved issues
+jira issue list --jql "resolved >= startOfMonth()" --raw
+```
+
+Calculate: `resolved_date - created_date`
+
+### Status Distribution
+
+```bash
+# 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
+
+```bash
+# 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:**
+   ```bash
+   jira issue view PROJ-123 --plain
+   ```
+
+2. **See available transitions:**
+   ```bash
+   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