jira-jql-patterns

What this skill does

# JQL Patterns Skill

Master JQL (Jira Query Language) query construction for advanced issue filtering and reporting.

## Overview

JQL is Jira's powerful query language for finding issues. This skill provides patterns and templates for constructing effective queries using jira-cli.

## Basic JQL Structure

```
field operator value [AND|OR field operator value]
```

## Essential Field Reference

### Issue Fields

| Field | Type | Example |
|-------|------|---------|
| `project` | Text | `project = PROJ` |
| `key` | Text | `key = PROJ-123` |
| `summary` | Text | `summary ~ "login"` |
| `description` | Text | `description ~ "error"` |
| `status` | Text | `status = "In Progress"` |
| `priority` | Text | `priority IN (High, Critical)` |
| `type` | Text | `type = Bug` |
| `labels` | List | `labels = urgent` |
| `component` | Text | `component = Backend` |
| `fixVersion` | Version | `fixVersion = "1.0"` |
| `resolution` | Text | `resolution = Fixed` |

### People Fields

| Field | Type | Example |
|-------|------|---------|
| `assignee` | User | `assignee = currentUser()` |
| `reporter` | User | `reporter = "[email protected]"` |
| `creator` | User | `creator = currentUser()` |
| `watcher` | User | `watcher = currentUser()` |

### Date Fields

| Field | Type | Example |
|-------|------|---------|
| `created` | Date | `created >= -7d` |
| `updated` | Date | `updated >= startOfWeek()` |
| `resolved` | Date | `resolved >= "2024-01-01"` |
| `duedate` | Date | `duedate <= now()` |

### Agile Fields

| Field | Type | Example |
|-------|------|---------|
| `sprint` | Sprint | `sprint = 123` |
| `"Epic Link"` | Epic | `"Epic Link" = PROJ-100` |
| `"Story Points"` | Number | `"Story Points" > 5` |

## Operators Reference

### Equality

- `=` - Equals
- `!=` - Not equals
- `IN` - In list
- `NOT IN` - Not in list

### Comparison

- `>` - Greater than
- `>=` - Greater than or equal
- `<` - Less than
- `<=` - Less than or equal

### Text Search

- `~` - Contains (case-insensitive)
- `!~` - Does not contain
- `IS` - For checking null/empty
- `IS NOT` - For checking not null/empty

### Special

- `IS EMPTY` - Field has no value
- `IS NOT EMPTY` - Field has value
- `WAS` - Historical value
- `CHANGED` - Field was changed

## JQL Functions

### User Functions

```jql
assignee = currentUser()
reporter = currentUser()
watcher = currentUser()
assignee IN membersOf("developers")
```

### Date Functions

```jql
created >= startOfDay()
created <= endOfDay()
created >= startOfWeek()
created >= startOfMonth()
created >= startOfYear()

updated >= startOfDay(-7)  # 7 days ago
duedate <= endOfWeek(1)     # End of next week
```

### Sprint Functions

```jql
sprint IN openSprints()
sprint IN closedSprints()
sprint IN futureSprints()
```

## Common Query Patterns

### My Work Queries

**Current work:**
```jql
assignee = currentUser() AND status NOT IN (Done, Closed)
```

**Recently completed:**
```jql
assignee = currentUser() AND status = Done AND resolved >= -7d
```

**Reported by me:**
```jql
reporter = currentUser() AND status NOT IN (Done, Closed)
```

**Watching:**
```jql
watcher = currentUser() AND status NOT IN (Done, Closed)
```

### Priority Queries

**Critical and high priority open:**
```jql
priority IN (Critical, High) AND status NOT IN (Done, Closed, Resolved)
```

**Urgent bugs:**
```jql
type = Bug AND priority = Critical AND status NOT IN (Done, Closed)
```

**Prioritized backlog:**
```jql
status = "To Do" AND priority IN (High, Medium) ORDER BY priority DESC
```

### Time-Based Queries

**Created today:**
```jql
created >= startOfDay()
```

**Updated this week:**
```jql
updated >= startOfWeek()
```

**Created in last 30 days:**
```jql
created >= -30d
```

**Overdue issues:**
```jql
duedate < now() AND status NOT IN (Done, Closed)
```

**Due this week:**
```jql
duedate >= startOfWeek() AND duedate <= endOfWeek()
```

**Stale issues (not updated in 90 days):**
```jql
updated <= -90d AND status NOT IN (Done, Closed)
```

### Team Queries

**Unassigned issues:**
```jql
assignee IS EMPTY AND status = "To Do"
```

**Team workload:**
```jql
assignee IN ([email protected], [email protected]) AND status IN ("In Progress", "To Do")
```

**Blocked issues:**
```jql
status = Blocked OR labels = blocked
```

**Issues needing review:**
```jql
status = "In Review" AND assignee IS NOT EMPTY
```

### Sprint Queries

**Current sprint:**
```jql
sprint IN openSprints()
```

**Current sprint for project:**
```jql
project = PROJ AND sprint IN openSprints()
```

**Specific sprint:**
```jql
sprint = 123
```

**Issues without sprint:**
```jql
type IN (Story, Bug, Task) AND sprint IS EMPTY
```

**Incomplete sprint items:**
```jql
sprint = 123 AND status NOT IN (Done, Closed)
```

### Epic Queries

**All issues in epic:**
```jql
"Epic Link" = PROJ-100
```

**Completed epic issues:**
```jql
"Epic Link" = PROJ-100 AND status = Done
```

**Issues without epic:**
```jql
type = Story AND "Epic Link" IS EMPTY
```

### Bug Tracking Queries

**Open bugs:**
```jql
type = Bug AND status NOT IN (Done, Closed, "Won't Fix")
```

**Critical production bugs:**
```jql
type = Bug AND priority = Critical AND labels = production AND status NOT IN (Done, Closed)
```

**Bugs by component:**
```jql
type = Bug AND component = Backend AND status NOT IN (Done, Closed)
```

**Recently fixed bugs:**
```jql
type = Bug AND status = Done AND resolved >= -7d
```

**Regression bugs:**
```jql
type = Bug AND labels = regression AND status NOT IN (Done, Closed)
```

### Story Queries

**Ready for development:**
```jql
type = Story AND status = "To Do" AND "Story Points" IS NOT EMPTY
```

**Unestimated stories:**
```jql
type = Story AND "Story Points" IS EMPTY AND status = "To Do"
```

**Large stories (need breakdown):**
```jql
type = Story AND "Story Points" >= 13
```

### Component Queries

**Frontend issues:**
```jql
component = Frontend AND status NOT IN (Done, Closed)
```

**Backend bugs:**
```jql
component = Backend AND type = Bug AND status NOT IN (Done, Closed)
```

**Issues without component:**
```jql
component IS EMPTY AND type IN (Story, Bug, Task)
```

### Label Queries

**Technical debt:**
```jql
labels = tech-debt AND status NOT IN (Done, Closed)
```

**Multiple labels:**
```jql
labels IN (urgent, critical) AND status NOT IN (Done, Closed)
```

**Issues without labels:**
```jql
labels IS EMPTY AND type IN (Story, Bug)
```

## Advanced Patterns

### Complex Logic with Parentheses

```jql
project = PROJ AND
(priority = Critical OR labels = urgent) AND
status NOT IN (Done, Closed)
ORDER BY created DESC
```

### Historical Queries

**Issues that were in progress:**
```jql
status WAS "In Progress" DURING (-7d, now())
```

**Issues that changed priority:**
```jql
priority CHANGED DURING (-30d, now())
```

**Issues moved to done this week:**
```jql
status CHANGED TO Done DURING (startOfWeek(), now())
```

### Negative Queries

**Not assigned to specific team:**
```jql
assignee NOT IN membersOf("qa-team")
```

**Exclude certain statuses:**
```jql
status NOT IN (Done, Closed, "Won't Fix", Duplicate)
```

**Not labeled:**
```jql
labels IS EMPTY
```

### Multi-Project Queries

**Across projects:**
```jql
project IN (PROJ1, PROJ2, PROJ3) AND assignee = currentUser()
```

**All projects bugs:**
```jql
type = Bug AND priority = Critical AND status NOT IN (Done, Closed)
```

## Sorting Patterns

### Single Sort

```jql
ORDER BY priority DESC
ORDER BY created ASC
ORDER BY updated DESC
ORDER BY duedate ASC
```

### Multiple Sort

```jql
ORDER BY priority DESC, created ASC
ORDER BY status ASC, priority DESC, updated DESC
ORDER BY duedate ASC, priority DESC
```

## Using with jira-cli

### Basic Query

```bash
jira issue list --jql "assignee = currentUser() AND status = 'In Progress'"
```

### Multi-line for Readability

```bash
jira issue list --jql "\
  project = PROJ AND \
  status IN ('In Progress', 'In Review') AND \
  assignee = currentUser() AND \
  created >= -7d \
  ORDER BY priority DESC"
```

### With Output Formats

```bash
#