meain/dotfiles/jira

Jira Issue Management

Use the jira CLI to look up, create, edit, transition, assign, comment on, and link Jira issues.

When to Use

• The user mentions a Jira issue key (e.g., DP-123)
• The user asks to look up, check, or get details on a Jira ticket
• The user wants to list or search for issues in a project
• The user wants to create, edit, transition, assign, comment on, or link issues
• The user needs context from a Jira issue to inform their work

Instructions

Phase 1: Identify the Request

Determine which operation the user needs:

Phase 2A: View / Search (read operations)

Viewing a single issue

jira issue view ISSUE-KEY --plain

To include recent comments:

jira issue view ISSUE-KEY --plain --comments 5

To get full raw JSON data for deeper inspection:

jira issue view ISSUE-KEY --raw

Listing/searching issues

# List issues in the default project
jira issue list --plain --no-truncate
 
# Filter by status
jira issue list --plain -s "In Progress"
 
# Filter by assignee (use "me" for current user)
jira issue list --plain -a "user@example.com"
 
# Filter by type and status
jira issue list --plain -t Bug -s "To Do"
 
# Filter by priority
jira issue list --plain -y High
 
# Filter by label
jira issue list --plain -l backend
 
# Search by text
jira issue list "search query" --plain
 
# Combine filters
jira issue list --plain -s "In Progress" -a "me" -y High
 
# Use raw JQL for complex queries
jira issue list --plain -q "assignee = currentUser() AND status = 'In Progress'"
 
# Specify a different project
jira issue list --plain -p PROJECT_KEY
 
# Limit results
jira issue list --plain --paginate 20

Phase 2B: Create (write operation)

Always use --no-input to avoid interactive prompts.

# Basic creation (always specify Story type)
jira issue create -tStory -s "Summary here" -b "Description here" --no-input
 
# Other issue types when explicitly needed
jira issue create -tBug -s "Bug title" -yHigh -lbug -lurgent -a "user@example.com" -b "Bug description" --no-input
jira issue create -tTask -s "Task title" -b "Description here" --no-input
 
# Create under a parent (epic or parent issue)
jira issue create -tStory -P EPIC-KEY -s "Story title" -b "Description" --no-input
 
# Create subtask under a parent
jira issue create -tSubtask -P PARENT-KEY -s "Subtask title" -b "Details" --no-input
 
# In a specific project
jira issue create -p PROJECT -tStory -s "Story title" -b "As a user..." --no-input
 
# With story points (field name is story-point-estimate; works on create)
jira issue create -tStory -s "Story" --custom story-point-estimate=3 --no-input
 
# Pipe description from stdin for long bodies
timeout 60 jira issue create -tStory -s "Summary" --no-input < /tmp/body.md

Pass multi-line descriptions via stdin, not -b "$(cat ...)" — the -b form has hung indefinitely without creating the issue. Wrap create in timeout 60 and, if it times out, check whether the issue was created before retrying.

To create directly into a sprint, get the ID from jira sprint list --state active --plain, then jira sprint add <SPRINT_ID> <KEY> after creation.

Important: When creating or editing issue descriptions:

• Keep descriptions short — never more than 5 lines. Say what's needed and stop; do not pad with background or restated context.
• Use a diagram when it explains the change better than prose (e.g. an ASCII flow, sequence, or before/after). A small diagram often replaces several lines of text.
• Use markdown format for descriptions
• Start with a descriptive paragraph, not section headings like "Context" or "Background"
• Structure content naturally with markdown formatting (lists, code blocks, etc.)
• Always explicitly specify `-tStory` when creating issues unless told to use a different type

Issue types: Task, Bug, Story, Epic, Subtask

Parent/Epic linking: Use -P EPIC-KEY to set the parent (epic) on create. Do NOT use -l (label) for this — -l adds labels, -P sets the parent.

Labels — reuse, don't invent: Never create a new label unless the user explicitly asks for a new one. Before adding a label (on create or edit), check it already exists:

# Search existing labels by substring (paginated, org-wide)
curl -s -u "abin.simon@veeam.com:$JIRA_API_TOKEN" \
  "https://veeam-vdc.atlassian.net/rest/api/3/label?maxResults=50" | jq '.values[]' | grep -i "search-term"

If no close match exists, ask the user whether to use a similar existing label or confirm they want a brand-new one.

Phase 2C: Edit (write operation)

Always use --no-input to avoid interactive prompts.

# Edit summary
jira issue edit ISSUE-KEY -s "New summary" --no-input
 
# Edit description
jira issue edit ISSUE-KEY -b "New description" --no-input
 
# Change priority
jira issue edit ISSUE-KEY -y High --no-input
 
# Add labels (append)
jira issue edit ISSUE-KEY -l newlabel --no-input
 
# Remove a label (prefix with -)
jira issue edit ISSUE-KEY --label -oldlabel --no-input
 
# Change assignee
jira issue edit ISSUE-KEY -a "user@example.com" --no-input
 
# Edit custom fields
jira issue edit ISSUE-KEY --custom story-points=5 --no-input
 
# Combine multiple edits
jira issue edit ISSUE-KEY -s "Updated title" -yHigh -l backend --no-input

Phase 2J: Story Points

On create, --custom story-point-estimate=N works. On jira issue edit, the --custom story-points=N flag does not work in this Jira instance. Story points must be set via the REST API directly using the customfield_10016 field (Story point estimate) and the JIRA_API_TOKEN environment variable:

curl -s -o /dev/null -w "%{http_code}" \
  -X PUT "https://veeam-vdc.atlassian.net/rest/api/3/issue/ISSUE-KEY" \
  -u "abin.simon@veeam.com:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"customfield_10016": N}}'
# 204 = success

When setting story points on multiple issues, loop over them in a single shell command.

Phase 2D: Transition / Move

# Move issue to a new status
jira issue move ISSUE-KEY "In Progress"
jira issue move ISSUE-KEY "Done"
 
# Move with a comment
jira issue move ISSUE-KEY "Done" --comment "Completed in PR #123"
 
# Move and reassign
jira issue move ISSUE-KEY "In Review" -a "reviewer@example.com"

Phase 2E: Assign

# Assign to a user
jira issue assign ISSUE-KEY "user@example.com"
 
# Assign to self
jira issue assign ISSUE-KEY $(jira me)
 
# Unassign
jira issue assign ISSUE-KEY x

Phase 2F: Comment

Always use --no-input to avoid interactive prompts.

# Add a comment
jira issue comment add ISSUE-KEY --no-input "Comment text here"
 
# Multi-line comment
jira issue comment add ISSUE-KEY --no-input $'First line\n\nSecond paragraph'
 
# Internal comment (not visible to external users)
jira issue comment add ISSUE-KEY --no-input "Internal note" --internal

Phase 2G: Link

# Link two issues
jira issue link ISSUE-1 ISSUE-2 "Blocks"
jira issue link ISSUE-1 ISSUE-2 "Duplicate"
 
# Unlink
jira issue unlink ISSUE-1 ISSUE-2

Phase 2H: Sprint & Epic

# List sprints
jira sprint list --plain
 
# Add issues to a sprint
jira sprint add SPRINT_ID ISSUE-KEY
 
# Add issues to an epic
jira epic add EPIC-KEY ISSUE-KEY
 
# Remove from epic
jira epic remove ISSUE-KEY

Phase 2I: Open in Browser

jira open ISSUE-KEY

Phase 3: Present Results

For read operations, summarize clearly:

• Key and Summary: The issue identifier and title
• Status: Current workflow state
• Type: Bug, Story, Task, Epic, etc.
• Priority: The issue priority level
• Assignee: Who is responsible
• Description: What the issue is about (summarize if very long)
• Comments: Recent discussion if relevant

For write operations, confirm what was done:

• State the action taken and the issue key
• Show the new state if relevant (e.g., new status after a move)

When the user needs issue context for coding work, focus on:

• What needs to be done (acceptance criteria, description)
• Any technical details mentioned in comments
• Related issues or blockers

Guidelines

• Always run jira CLI commands with dangerouslyDisableSandbox: true — the sandbox blocks TLS verification for Jira's certificate chain, causing x509 errors
• Always use --plain flag when listing/viewing issues so output is parseable (avoid the interactive TUI)
• Always use --no-input flag on create/edit/comment to avoid interactive prompts
• Use --no-truncate with list commands to show full field contents when details matter
• If the jira CLI is not configured or authentication fails, inform the user and suggest running jira init
• Show before mutating: For write operations (edit, move, assign, comment, link, delete), always show the user exactly what will be changed (field name, old value → new value, or full content for descriptions/comments) and wait for confirmation before executing. Do not skip this even if the instruction seems unambiguous.
• Create requires explicit confirmation: Before creating any new Jira issue, show the full details (type, summary, description, parent, labels, etc.) and ask the user to explicitly confirm. Do not create the issue until they say yes — even if the request seems clear and complete.
• If a project key is ambiguous or missing, ask the user which project to query
• When an issue key is mentioned in a branch name or commit message, offer to look it up
• Summarize long descriptions and comment threads instead of dumping raw output
• The default project is DP (Data Pipelines) — only specify -p when targeting a different project
• Never invent new labels — always check the existing label list first (see Labels note in Phase 2B) and reuse a matching one