claude-skills-reference/project-management/jira-expert/references/WORKFLOWS.md

Jira Workflows Reference

Comprehensive guide to Jira workflow design, transitions, conditions, validators, and post-functions.

Default Workflows

Simplified Workflow

Open → In Progress → Done

Software Development Workflow

Backlog → Selected for Development → In Progress → In Review → Done
         ↑___________________________|  (reopen)

Bug Tracking Workflow

Open → In Progress → Fixed → Verified → Closed
  ↑                    |        |
  |____Reopened________|________|

Custom Workflow Design

Design Principles

1. Mirror your actual process — don't force teams into artificial states
2. Minimize statuses — each status must represent a distinct work state where the item waits for a different action
3. Clear ownership — every status should have an obvious responsible party
4. Allow rework — always provide paths back for rejected/reopened items
5. Separate "waiting" from "working" — distinguish "In Review" (waiting) from "Reviewing" (actively working)

Status Categories

Jira maps every status to one of four categories that drive board columns and JQL:

Category	Meaning	JQL	Examples
To Do	Not started	statusCategory = "To Do"	Backlog, Open, New
In Progress	Active work	statusCategory = "In Progress"	In Progress, In Review, Testing
Done	Completed	statusCategory = Done	Done, Closed, Released
Undefined	Legacy/unused	—	Avoid using

Recommended Statuses by Team Type

Engineering Team:

Backlog → Ready → In Progress → Code Review → QA → Done

Support Team:

New → Triaged → In Progress → Waiting on Customer → Resolved → Closed

Design Team:

Backlog → Research → Design → Review → Approved → Handoff

Transitions

Transition Properties

Property	Description
Name	Display name on the button (e.g., "Start Work")
Screen	Form shown during transition (optional)
Conditions	Who can trigger this transition
Validators	Rules that must pass before transition executes
Post-functions	Actions executed after transition completes

Common Transition Patterns

Start Work:

Trigger: "Start Work" button
Condition: Assignee only
Validator: Issue must have assignee
Post-function: Set "In Progress" resolution to None

Submit for Review:

Trigger: "Submit for Review" button
Condition: Assignee or project admin
Validator: All sub-tasks must be Done
Post-function: Add comment "Submitted for review by {user}"

Approve:

Trigger: "Approve" button
Condition: Must be in "Reviewers" group
Validator: Must add comment
Post-function: Set resolution to "Done", fire event

Conditions

Built-in Conditions

Condition	Use When
Only Assignee	Only assigned user can transition
Only Reporter	Only creator can transition
Permission Condition	User must have specific permission
Group Condition	User must be in specified group
Sub-Task Blocking	All sub-tasks must be resolved
Previous Status	Issue must have been in a specific status
User Is In Role	User must have project role (Developer, Admin)

Combining Conditions

• AND logic: Add multiple conditions to one transition — ALL must pass
• OR logic: Create parallel transitions with different conditions

Validators

Built-in Validators

Validator	Checks
Required Field	Specific field must be populated
Field Has Been Modified	Field must change during transition
Regular Expression	Field must match regex pattern
Permission Validator	User must have permission
Previous Status Validator	Issue was in a required status

Common Validator Patterns

# Require comment on rejection
Validator: Comment Required
When: Transition = "Reject"

# Require fix version before release
Validator: Required Field = "Fix Version/s"
When: Transition = "Release"

# Require time logged before closing
Validator: Field Required = "Time Spent" (must be > 0)
When: Transition = "Close"

Post-Functions

Built-in Post-Functions

Post-Function	Action
Set Field Value	Assign a value to any field
Update Issue Field	Change assignee, priority, etc.
Create Comment	Add automated comment
Fire Event	Trigger notification event
Assign to Lead	Assign to project lead
Assign to Reporter	Assign back to creator
Clear Field	Remove field value
Copy Value	Copy field from parent/linked issue

Post-Function Execution Order

Post-functions execute in defined order. Standard sequence:

1. Set issue status (automatic, always first)
2. Add comment (if configured)
3. Update fields
4. Generate change history (automatic, always last)
5. Fire event (triggers notifications)

Important: "Generate change history" and "Fire event" must always be last — reorder if you add custom post-functions.

Workflow Schemes

What They Do

• Map issue types to workflows within a project
• One workflow scheme per project
• Different issue types can use different workflows

Configuration Pattern

Project: MYPROJ
Workflow Scheme: "Engineering Workflow Scheme"

  Bug         → Bug Tracking Workflow
  Story       → Development Workflow
  Task        → Simple Workflow
  Epic        → Epic Workflow
  Sub-task    → Sub-task Workflow (inherits parent transitions)

Best Practices

1. Start simple, add complexity only when needed — a 5-status workflow beats a 15-status one
2. Name transitions as actions — "Start Work" not "In Progress" (the status is "In Progress", the action is "Start Work")
3. Use screens sparingly — only show a screen when you need data from the user during transition
4. Test with real users — workflows that look good on paper may confuse the team
5. Document your workflow — add descriptions to statuses and transitions
6. Use global transitions carefully — a "Cancel" transition from any status is convenient but can bypass important gates
7. Audit quarterly — remove statuses with <5% usage