jira-integration

What this skill does

# JIRA Integration Patterns

This skill provides comprehensive knowledge about JIRA API usage, JQL query patterns, and best practices for Red Hat AI JIRA integration.

## JQL (JIRA Query Language) Reference

### Basic Syntax

```jql
field operator value [AND|OR field operator value] [ORDER BY field direction]
```

### Common Operators

| Operator | Description | Example |
|----------|-------------|---------|
| = | Equals | `status = "In Progress"` |
| != | Not equals | `status != Closed` |
| IN | Match any value | `project IN (RHAISTRAT, RHOAISTRAT)` |
| NOT IN | Exclude values | `status NOT IN (Closed, Resolved)` |
| ~ | Contains text | `summary ~ "authentication"` |
| !~ | Does not contain | `summary !~ "deprecated"` |
| IS EMPTY | Field is empty | `assignee IS EMPTY` |
| IS NOT EMPTY | Field has value | `sprint IS NOT EMPTY` |
| > < >= <= | Comparison | `created > -7d` |

### Functions

| Function | Description | Example |
|----------|-------------|---------|
| `currentUser()` | Current logged-in user | `assignee = currentUser()` |
| `now()` | Current date/time | `updated > now(-1h)` |
| `startOfDay()` | Start of day | `created >= startOfDay()` |
| `endOfDay()` | End of day | `due <= endOfDay()` |
| `startOfWeek()` | Start of week | `created >= startOfWeek()` |
| `membersOf()` | Group members | `assignee IN membersOf("team-ai")` |

### Date Formats

- `-1d` - 1 day ago
- `-2w` - 2 weeks ago
- `-3M` - 3 months ago
- `-1y` - 1 year ago
- `-30m` - 30 minutes ago
- `2025-01-15` - Specific date

---

## Essential JQL Queries for Red Hat AI

### My Work

**All my assigned issues (unresolved):**
```jql
assignee = currentUser() AND resolution = Unresolved ORDER BY priority DESC, updated DESC
```

**My issues updated today:**
```jql
assignee = currentUser() AND updated >= startOfDay() ORDER BY updated DESC
```

**My overdue issues:**
```jql
assignee = currentUser() AND due < now() AND resolution = Unresolved ORDER BY due ASC
```

### Sprint Queries

**Issues in specific sprint:**
```jql
sprint = "Sprint 25" ORDER BY rank ASC
```

**Issues in current/active sprint:**
```jql
sprint IN openSprints() AND project = RHAISTRAT ORDER BY rank ASC
```

**Issues not in any sprint (backlog):**
```jql
sprint IS EMPTY AND project = RHAISTRAT AND resolution = Unresolved ORDER BY priority DESC
```

### Epic Queries

**All stories/tasks in an epic:**
```jql
parent = RHAISTRAT-123 ORDER BY rank ASC
```

**Epics without children:**
```jql
issuetype = Epic AND issueFunction IN issuesWithoutSubtasks() ORDER BY created DESC
```

**Progress on epic:**
```jql
parent = RHAISTRAT-123 AND status = Done
```

### Project-Specific Queries

**STRAT features needing refinement:**
```jql
project IN (RHAISTRAT, RHOAISTRAT) AND status = "Refinement In Progress" ORDER BY updated ASC
```

**RFEs pending approval:**
```jql
project IN (RHAIRFE, RHELAIRFE, RHOAIRFE) AND status = "Pending Review" ORDER BY created DESC
```

**Engineering issues by component:**
```jql
project = RHAIENG AND component = "Authentication" AND resolution = Unresolved ORDER BY priority DESC
```

### Advanced Queries

**Issues with specific label:**
```jql
labels = requires_architecture_review AND resolution = Unresolved ORDER BY priority DESC
```

**Issues linked to specific issue:**
```jql
issue IN linkedIssues(RHAISTRAT-123) ORDER BY type ASC
```

**Recently commented issues:**
```jql
project = RHAISTRAT AND comment ~ "review" AND updated >= -3d ORDER BY updated DESC
```

**Issues by multiple criteria:**
```jql
project IN (RHAISTRAT, RHOAISTRAT)
AND assignee = currentUser()
AND status IN ("In Progress", "Code Review")
AND sprint IN openSprints()
ORDER BY priority DESC, rank ASC
```

---

## Field Mappings

### Standard Fields

| Field | API Name | Type | Example Value |
|-------|----------|------|---------------|
| Summary | `summary` | String | "Add authentication support" |
| Description | `description` | String (formatted) | "As a user, I want..." |
| Status | `status.name` | String | "In Progress" |
| Priority | `priority.name` | String | "High" |
| Assignee | `assignee.name` | String | "jdoe" |
| Reporter | `reporter.name` | String | "jsmith" |
| Issue Type | `issuetype.name` | String | "Feature" |
| Project | `project.key` | String | "RHAISTRAT" |
| Labels | `labels` | Array | ["documentation", "security"] |
| Components | `components` | Array of objects | [{"name": "UXD"}] |
| Fix Versions | `fixVersions` | Array of objects | [{"name": "1.5.0"}] |

### Custom Fields (Red Hat AI)

| Field | API Name | Type | Notes |
|-------|----------|------|-------|
| Sprint | `customfield_xxxxx` | Sprint object | Find ID via API |
| Story Points | `customfield_xxxxx` | Number | Estimate |
| Epic Link | `customfield_xxxxx` | String | Epic key |
| Feature Owner | `customfield_xxxxx` | User object | STRAT features |
| Delivery Owner | `customfield_xxxxx` | User object | STRAT features |
| Product Documentation Required | `customfield_xxxxx` | Boolean | Yes/No |
| Requires Architecture Review | `customfield_xxxxx` | Boolean | Yes/No |

**Note:** Custom field IDs vary by JIRA instance. Use `/rest/api/2/field` endpoint to discover actual IDs.

---

## Status Transitions

### Standard Workflow

```
New → In Progress → Code Review → Testing → Done
         ↓
      Blocked
         ↓
      In Progress
```

### STRAT Workflow

```
Not Started → Refinement In Progress → Refinement Complete → In Development → Testing → Done
                     ↓
                  Blocked
                     ↓
            Refinement In Progress
```

### Transition Best Practices

1. **Always check available transitions** before attempting:
   ```python
   python jira_client.py get_transitions RHAISTRAT-123
   ```

2. **Use transition IDs, not names** (names can vary):
   ```python
   python jira_client.py transition_issue RHAISTRAT-123 "31"
   ```

3. **Required fields** may vary by transition - check transition metadata

4. **Add comments** when transitioning to provide context

---

## Issue Linking

### Link Types

| Link Type | Meaning | Example |
|-----------|---------|---------|
| Relates | General relation | Feature relates to another feature |
| Blocks | Blocks progress | Bug blocks feature |
| Clones | Copied from | STRAT clones RFE |
| Duplicates | Same issue | Bug duplicates earlier bug |
| Causes | Root cause | Issue causes another issue |
| Depends on | Dependency | Feature depends on infrastructure |

### Linking Patterns

**Link STRAT to RFE:**
```bash
python jira_client.py link_issue RHAISTRAT-123 RHAIRFE-456 "Clones"
```

**Link feature to epic:**
```bash
# Set parent field instead of link
python jira_client.py update_issue RHAISTRAT-123 '{"parent": {"key": "RHAISTRAT-100"}}'
```

**Link blocker:**
```bash
python jira_client.py link_issue RHAISTRAT-123 RHAIENG-789 "Blocks"
```

---

## API Best Practices

### Pagination

For large result sets, use pagination:
```jql
# First page
startAt=0&maxResults=50

# Next page
startAt=50&maxResults=50
```

### Rate Limiting

- Self-hosted JIRA: Typically no rate limits, but be considerate
- Cloud JIRA: Limits vary by plan
- Use caching to reduce API calls (jira has 4-hour default cache)

### Caching Strategy

**When to use cache:**
- ✅ Viewing issue lists
- ✅ Reading issue details
- ✅ JQL queries for display

**When to bypass cache:**
- ❌ After making updates
- ❌ Checking current status before transitions
- ❌ Real-time status monitoring

**Bypass cache:**
```bash
python jira_client.py get_issue RHAISTRAT-123 --no-cache
```

### Error Handling

**Common errors:**
- `401 Unauthorized` - Invalid credentials
- `403 Forbidden` - Insufficient permissions
- `404 Not Found` - Issue doesn't exist
- `400 Bad Request` - Invalid field or value

**Best practices:**
1. Validate issue keys before API calls
2. Check user permissions
3. Validate field values against JIRA schema
4. Handle network errors gracefully

---

## Bulk Operations

### Batch Issue Updates

For multiple issues, iterate and update one at a t