managing-jira-issues

Jira Integration Skill

Purpose: Issue management for Jira Cloud using the jira CLI with JSON output optimized for LLM agents.

Tool: jira CLI (installed globally via npm link from ~/utils/atlassian)

---

Table of Contents

1. Prerequisites
2. Decision Tree
3. Quick Command Reference
4. Pattern Recognition - Auto-Invocation
5. Workflow Examples
6. Error Handling
7. JSON Output Handling
8. Comparison: Quick Read vs Fetch
9. Version History

---

Prerequisites

Verify Installation

# Check CLI installed
jira --version  # Expects: 1.0.0

Authentication

Config location: ~/utils/atlassian/.env

ATLASSIAN_CLOUD_ID=your-cloud-id
ATLASSIAN_AUTH_TOKEN=email@domain.com:API_TOKEN
ATLASSIAN_SITE_URL=https://your-site.atlassian.net

Get API token from: https://id.atlassian.com/manage-profile/security/api-tokens

---

Decision Tree

Issue Operations

User wants to...
├── View issue details
│   └── jira issues read <ISSUE-KEY>
├── List recent issues
│   └── jira issues list [--limit N] [--project KEY]
├── Search issues
│   └── jira issues search "query" [--project KEY]
├── Create new issue
│   └── jira issues create "Title" --project KEY [options]
├── Update existing issue
│   └── jira issues update <ISSUE-KEY> [--status|--assignee|--priority]
├── Fetch complete hierarchy
│   └── jira issues fetch <ISSUE-KEY> --output ./spec
└── Get available transitions
    └── jira issues transitions <ISSUE-KEY>

Metadata Operations

User wants to...
├── List projects
│   └── jira projects list
└── List users
    └── jira users list [--query NAME]

Comments

├── Add comment
│   └── jira comments create <ISSUE-KEY> --body "Comment text"
└── List comments
    └── jira comments list <ISSUE-KEY>

---

Quick Command Reference

Issues CRUD

Operation	Command	Example
Read	jira issues read <KEY>	jira issues read VA-2228
List	jira issues list	jira issues list --limit 10 --project VA
Search	jira issues search "query"	jira issues search "auth bug"
Create	jira issues create "Title"	jira issues create "Fix login" --project VA --type Bug
Update	jira issues update <KEY>	jira issues update VA-123 --status "In Review"
Fetch	jira issues fetch <KEY>	jira issues fetch VA-123 --output ./spec

Create Issue Options

jira issues create "Title" \
  --project VA \
  --type Story \
  --description "Detailed description" \
  --assignee "account-id" \
  --priority High \
  --labels "Bug,Critical" \
  --parent VA-100

Issue types: Epic, Story, Task, Bug, Sub-task Priority values: Highest, High, Medium, Low, Lowest

Update Issue Options

jira issues update VA-123 \
  --status "In Review" \
  --assignee "account-id" \
  --priority High \
  --labels "Bug,P1" \
  --summary "New title"

Fetch (Comprehensive Hierarchy)

# Fetch epic with ALL children + linked Confluence pages
jira issues fetch VA-2522 --output ./spec

# Output structure:
# ./spec/
# ├── jira/
# │   ├── VA-2522.json
# │   ├── VA-2522.md
# │   ├── VA-2228.json  (child)
# │   └── ...
# ├── confluence/
# │   ├── 12345678.json
# │   └── ...
# └── summary.json

When to use fetch:

• Implementing a feature from Jira epic/story
• Need complete requirements with all children
• Building offline reference materials
• Want all linked Confluence pages automatically

Metadata Queries

# Projects
jira projects list

# Users
jira users list
jira users list --query "john"

Comments

# Add comment
jira comments create VA-123 --body "This is a comment"

# List comments
jira comments list VA-123

---

Pattern Recognition - Auto-Invocation

High Confidence Triggers (invoke immediately)

Issue Operations:
  - "Create a Jira issue for..."
  - "Open a ticket in Jira..."
  - "Log this as a Jira bug..."
  - "Check Jira issue VA-123"
  - "What's the status of VA-123?"
  - "Update VA-123 to..."
  - "Move VA-123 to In Review"
  - "Assign VA-123 to..."
  - "Search Jira for..."
  - "Find issues about..."

Fetch Operations (comprehensive):
  - "Fetch VA-2228"
  - "Pull down VA-2522"
  - "Get complete data for VA-2228"
  - "Implement from VA-2228"
  - "Get requirements for VA-2228"

Metadata:
  - "List Jira projects"
  - "Who can I assign this to?"

Issue ID Detection

# Jira issue ID pattern
[A-Z]{2,10}-\d+

# Examples: VA-123, DEV-456, BACKEND-789

---

Workflow Examples

Create Issue from Bug Report

User: "Create a Jira issue for the login timeout bug"

Steps:
  1. Parse request: title=login timeout bug
  2. Execute: jira issues create "Login timeout bug" --project VA --type Bug
  3. Return: Issue key and details from JSON

Check Issue Status

User: "What's the status of VA-123?"

Steps:
  1. Parse issue ID: VA-123
  2. Execute: jira issues read VA-123
  3. Return: Issue title, state, assignee, priority from JSON

Update Issue State

User: "Move VA-123 to In Review and assign to John"

Steps:
  1. Get users: jira users list --query john
  2. Find John's account ID from JSON
  3. Update: jira issues update VA-123 --status "In Review" --assignee john-account-id

Implement from Jira Epic

User: "Implement VA-2522"

Steps:
  1. Check if reference exists: ls ./spec/jira/VA-2522.json
  2. If not: jira issues fetch VA-2522 --output ./spec
  3. Read requirements from ./spec/jira/*.md
  4. Begin implementation
  5. Update progress: jira issues update VA-2228 --status "In Progress"

---

Error Handling

Error	Cause	Resolution
command not found: jira	CLI not installed	cd ~/utils/atlassian && npm link
Missing ATLASSIAN_AUTH_TOKEN	No credentials	Configure ~/utils/atlassian/.env
Authentication failed	Invalid token	Regenerate API token
Resource not found	Invalid issue key	Verify issue exists
Status not available	Invalid transition	Run jira issues transitions VA-123 to see options
Rate limited	Too many requests	CLI auto-retries with backoff

---

JSON Output Handling

All commands output JSON. Parse with jq:

# Get issue title
jira issues read VA-123 | jq -r '.summary'

# Get issue status
jira issues read VA-123 | jq -r '.status'

# List issue keys and titles
jira issues list --limit 10 | jq -r '.[] | "\(.key): \(.summary)"'

# Get created issue key
jira issues create "Title" --project VA | jq -r '.key'

---

Comparison: Quick Read vs Fetch

Need	Use read	Use fetch
Quick status check	Yes	No
Get single issue	Yes	Overkill
Get issue + ALL children	No	Yes
Get linked Confluence	No	Yes (automatic)
Offline reference	No	Yes
Implementation context	No	Yes
Real-time current data	Yes	Snapshot

---

Version History

• v1.0 (2025-12-29): CLI-first architecture replacing MCP-based approach
  • Full CRUD operations via jira CLI
  • Comprehensive fetch with hierarchy traversal
  • JSON output for LLM parsing
  • Mirrors Linear skill pattern