jira-jql

What this skill does

# JIRA JQL Translation Skill

When users search JIRA with natural language queries, use this skill to generate appropriate JQL (JIRA Query Language) queries that are syntactically correct, semantically meaningful, and performant.

## Core Translation Principles

1. **Understand Intent**: Interpret what the user wants to find
2. **Apply Smart Defaults**: Use fuzzy matching and expansions for common patterns
3. **Prioritize Performance**: Always include project filters when possible
4. **Be Transparent**: Generate clear, readable JQL that users can learn from
5. **Add Context**: Include sensible ORDER BY clauses for immediate usefulness

---

## Translation Patterns

### Fuzzy Status Matching

Users rarely know exact status names. Apply intelligent fuzzy matching:

**"open" / "opened" / "active" / "not done":**
```jql
status IN (Open, 'To Do', 'In Progress', 'Refinement In Progress', New, Blocked)
```

**"closed" / "done" / "finished" / "completed":**
```jql
status IN (Closed, Done, Resolved, 'Refinement Complete')
```

**"in progress" / "working on" / "active development":**
```jql
status IN ('In Progress', 'Code Review', Testing, 'Refinement In Progress')
```

**"blocked" / "stuck" / "waiting":**
```jql
status IN (Blocked, Waiting, 'Pending Review', 'Pending Approval')
```

**"needs review" / "ready for review":**
```jql
status IN ('Code Review', 'Pending Review', 'Ready for QA')
```

### Release/Version Queries

Teams use both fixVersion field AND labels inconsistently. **Always check both automatically**:

**"release-3.2" / "version 3.2" / "3.2 release":**
```jql
(fixVersion = 'release-3.2' OR labels = 'release-3.2')
```

**"targeted to X" / "planned for X":**
```jql
(fixVersion = 'X' OR labels = 'X')
```

**Pattern**: Always use OR to check both fixVersion and labels for any version/release query.

### Link Following

**"linked to RHAISTRAT-123" / "related to RHAI-456":**
```jql
issue IN linkedIssues(RHAISTRAT-123)
```

**"blocks RHAIENG-789" / "blocking KEY":**
```jql
issue IN linkedIssues(RHAIENG-789, "blocks")
```

**"blocked by KEY":**
```jql
issue IN linkedIssues(KEY, "is blocked by")
```

**"depends on KEY":**
```jql
issue IN linkedIssues(KEY, "depends on")
```

**Common link types**: Relates, Blocks, Clones, Duplicates, Causes, Depends on

### Ownership Queries

**"my issues" / "assigned to me" / "mine":**
```jql
assignee = currentUser()
```

**"created by me" / "I created" / "I reported":**
```jql
reporter = currentUser()
```

**"unassigned" / "no assignee" / "needs owner":**
```jql
assignee IS EMPTY
```

**"assigned to john" / "john's issues":**
```jql
assignee = john
```

**Note**: Usernames in JIRA are typically lowercase, without spaces.

### Priority Queries

**"high priority" / "urgent" / "critical":**
```jql
priority IN (Highest, High, Critical)
```

**"low priority":**
```jql
priority IN (Lowest, Low)
```

**"medium priority" / "normal":**
```jql
priority = Medium
```

### Issue Type Queries

**"bugs" / "defects":**
```jql
issuetype = Bug
```

**"features" / "stories" / "user stories":**
```jql
issuetype IN (Feature, Story, 'User Story')
```

**"tasks" / "chores":**
```jql
issuetype = Task
```

**"epics":**
```jql
issuetype = Epic
```

**"subtasks" / "sub-tasks":**
```jql
issuetype IN subTaskIssueTypes()
```

### Date/Time Queries

**"last week" / "past week" / "this week":**
```jql
updated >= -7d
```

**"yesterday" / "last 24 hours":**
```jql
updated >= -1d
```

**"last month":**
```jql
updated >= -30d
```

**"today" / "updated today":**
```jql
updated >= startOfDay()
```

**"created this month":**
```jql
created >= startOfMonth()
```

**"overdue":**
```jql
due < now() AND resolution = Unresolved
```

### Sprint Queries

**"current sprint" / "active sprint":**
```jql
sprint IN openSprints()
```

**"no sprint" / "backlog" / "not in any sprint":**
```jql
sprint IS EMPTY
```

**"sprint 25" / "sprint X":**
```jql
sprint = X
```

### Team/Group Queries

**"assigned to the QA team" / "QA's issues":**
```jql
assignee IN membersOf("qa") OR assignee IN membersOf("quality-assurance")
```

**"created by the dev team":**
```jql
reporter IN membersOf("developers")
```

### Label Queries

**"labeled X" / "tagged X" / "with label X":**
```jql
labels = X
```

**"requires architecture review":**
```jql
labels = requires_architecture_review
```

**Note**: Labels are typically lowercase with underscores or hyphens.

### Resolution Queries

**"unresolved" / "not done" / "still open":**
```jql
resolution = Unresolved
```

**"resolved" / "fixed":**
```jql
resolution IS NOT EMPTY
```

---

## JQL Syntax Reference

### Operators

| Operator | Usage | Example |
|----------|-------|---------|
| `=` | Equals (exact match) | `status = Open` |
| `!=` | Not equals | `priority != Low` |
| `>` | Greater than | `votes > 10` |
| `>=` | Greater or equal | `created >= -7d` |
| `<` | Less than | `votes < 5` |
| `<=` | Less or equal | `duedate <= now()` |
| `IN` | Matches any value in list | `status IN (Open, 'In Progress')` |
| `NOT IN` | Excludes all values in list | `status NOT IN (Closed, Done)` |
| `~` | Contains (text search) | `summary ~ "authentication"` |
| `!~` | Does not contain | `summary !~ "deprecated"` |
| `IS EMPTY` | Field has no value | `assignee IS EMPTY` |
| `IS NOT EMPTY` | Field has a value | `labels IS NOT EMPTY` |
| `IS NULL` | Same as IS EMPTY | `fixVersion IS NULL` |
| `IS NOT NULL` | Same as IS NOT EMPTY | `component IS NOT NULL` |
| `WAS` | Had value in the past | `status WAS 'In Progress'` |
| `WAS IN` | Was any of values | `status WAS IN (Open, New)` |
| `WAS NOT` | Was not value | `assignee WAS NOT john` |
| `CHANGED` | Field value changed | `priority CHANGED` |

### Functions

| Function | Description | Example |
|----------|-------------|---------|
| `currentUser()` | Currently logged-in user | `assignee = currentUser()` |
| `linkedIssues(key)` | All issues linked to key | `issue IN linkedIssues(RHAI-123)` |
| `linkedIssues(key, linkType)` | Issues with specific link type | `issue IN linkedIssues(RHAI-123, "blocks")` |
| `membersOf(group)` | Users in a group | `assignee IN membersOf("developers")` |
| `now()` | Current date/time | `created > now(-1h)` |
| `startOfDay([offset])` | Start of today (or offset) | `created >= startOfDay()` |
| `endOfDay([offset])` | End of today (or offset) | `due <= endOfDay()` |
| `startOfWeek([offset])` | Start of week | `created >= startOfWeek()` |
| `endOfWeek([offset])` | End of week | `due <= endOfWeek()` |
| `startOfMonth([offset])` | Start of month | `created >= startOfMonth()` |
| `endOfMonth([offset])` | End of month | `due <= endOfMonth()` |
| `startOfYear([offset])` | Start of year | `created >= startOfYear()` |
| `endOfYear([offset])` | End of year | `resolved <= endOfYear()` |
| `openSprints()` | All active sprints | `sprint IN openSprints()` |
| `closedSprints()` | All completed sprints | `sprint IN closedSprints()` |
| `futureSprints()` | All future sprints | `sprint IN futureSprints()` |
| `subTaskIssueTypes()` | All subtask types | `issuetype IN subTaskIssueTypes()` |
| `issueHistory()` | Search issue history | Advanced usage |

**Time offset examples**:
- `now(-1h)` - 1 hour ago
- `startOfDay(-7)` - Start of day 7 days ago
- `startOfMonth(1)` - Start of next month

### Fields

| Field | Description | Example Values |
|-------|-------------|----------------|
| `project` | Project key | RHAISTRAT, RHAIENG, RHAIRFE |
| `summary` | Issue title | "Add authentication support" |
| `description` | Issue description | Free text |
| `issuetype` | Type of issue | Bug, Feature, Story, Task, Epic |
| `status` | Current status | Open, 'In Progress', Done, Closed |
| `priority` | Priority level | Highest, High, Medium, Low, Lowest |
| `assignee` | Assigned user | jdoe, currentUser() |
| `reporter` | Created by | jsmith, currentUser() |
| `created` | Creation date | "2025-01-15", -7d |
| `updated` | Last updated | -1d, startOfDay() |
| `resolved` | Resolution date | -30d, now() |
| `due` | Due date |