netresearch/jira-skill / skills/jira-communication
jira-communication
FlaggedUse when handling Jira issues, sprints, boards, links, fields, worklogs, attachments, or users, or on any Jira intent without a key ("create/find a ticket", "pick a project"). Auto-triggers on Jira URLs and issue keys (PROJ-123). Also use when MCP Atlassian tools fail or are unavailable for Jira Server/DC.
references/jql-quick-reference.md
View on GitHub<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
# JQL Quick Reference
## When to load
Load this reference whenever a JQL query goes beyond the inline SKILL.md examples — any use of `AND`/`OR` combinators, historical operators (`WAS`, `CHANGED`), functions (`currentUser()`, `startOfWeek()`), or unfamiliar field names.
Common JQL patterns for `jira-search.py query "<JQL>"`.
## Sorting (`ORDER BY`)
Two equivalent forms — pick one, never both (the script rejects mixing them):
```bash
# Embedded in the JQL string
jira-search query "project = PROJ AND status = Open ORDER BY updated DESC"
# Via the --order-by flag (repeatable for multi-key sorts)
jira-search query "project = PROJ AND status = Open" --order-by "updated DESC"
jira-search query "project = PROJ" \
--order-by "priority DESC" --order-by "created ASC"
```
Both forms support the same sort keys (any indexed Jira field) and the
same `ASC` / `DESC` direction modifiers. The flag form is friendlier when
JQL is composed programmatically and the base query should stay untouched.
## Operators
### Comparison
| Operator | Example | Notes |
|----------|---------|-------|
| `=` | `status = "In Progress"` | Exact match |
| `!=` | `status != Done` | Not equal |
| `>` | `votes > 4` | Greater than (dates, versions, numbers) |
| `>=` | `duedate >= "2024-01-01"` | Greater than or equal |
| `<` | `priority < High` | Less than |
| `<=` | `updated <= -4w` | Less than or equal |
### Text Search
| Operator | Example | Notes |
|----------|---------|-------|
| `~` | `summary ~ "login"` | Contains (fuzzy match) |
| `!~` | `summary !~ "test"` | Does not contain |
### List & Null
| Operator | Example | Notes |
|----------|---------|-------|
| `IN` | `status IN (Open, "In Progress")` | Multiple values |
| `NOT IN` | `priority NOT IN (Low, Lowest)` | Exclude values |
| `IS EMPTY` | `assignee IS EMPTY` | Field has no value |
| `IS NOT EMPTY` | `fixVersion IS NOT EMPTY` | Field has value |
### Historical
| Operator | Example | Notes |
|----------|---------|-------|
| `WAS` | `assignee WAS "john"` | Previous value |
| `WAS IN` | `status WAS IN (Open, "To Do")` | Previous in list |
| `WAS NOT` | `status WAS NOT Done` | Was never value |
| `CHANGED` | `status CHANGED` | Value was modified |
`CHANGED` supports predicates: `FROM`, `TO`, `BY`, `DURING`, `BEFORE`, `AFTER`, `ON`
```jql
status CHANGED FROM "Open" TO "In Progress" BY currentUser() AFTER -7d
```
## Functions
### User Functions
| Function | Description |
|----------|-------------|
| `currentUser()` | Logged-in user |
| `membersOf("group")` | Members of a group |
### Date Functions
| Function | Description |
|----------|-------------|
| `now()` | Current timestamp |
| `startOfDay()` | Midnight today |
| `startOfWeek()` | Start of current week |
| `startOfMonth()` | First of current month |
| `startOfYear()` | January 1st current year |
| `endOfDay()` | End of today (23:59:59) |
| `endOfWeek()` | End of current week |
| `endOfMonth()` | Last day of current month |
| `endOfYear()` | December 31st current year |
Date offsets: `startOfDay(-1)` = yesterday, `startOfWeek(1)` = next week
### Relative Dates
| Format | Example | Description |
|--------|---------|-------------|
| `-Nd` | `-7d` | N days ago |
| `-Nw` | `-2w` | N weeks ago |
| `-Nm` | `-1m` | N months ago |
| `"YYYY-MM-DD"` | `"2024-01-15"` | Specific date |
### Sprint Functions
| Function | Description |
|----------|-------------|
| `openSprints()` | Active sprints |
| `closedSprints()` | Completed sprints |
| `futureSprints()` | Planned sprints |
### Version Functions
| Function | Description |
|----------|-------------|
| `releasedVersions()` | Released versions |
| `unreleasedVersions()` | Unreleased versions |
| `latestReleasedVersion()` | Most recent release |
## Common Queries
### By Assignment
```jql
assignee = currentUser()
assignee = "john.doe"
assignee IS EMPTY
assignee IN membersOf("developers")
```
### By Status
```jql
status = "In Progress"
status IN (Open, "To Do", "In Progress")
status != Done
status WAS "Open"
status CHANGED FROM "Open" TO "In Progress"
```
### By Date
```jql
created >= -7d
updated >= startOfWeek()
due <= endOfMonth()
resolved >= "2024-01-01"
created >= startOfMonth(-1) AND created < startOfMonth()
```
### By Sprint
```jql
sprint IN openSprints()
sprint IN closedSprints()
sprint = "Sprint 42"
sprint IS EMPTY
```
### By Text
```jql
text ~ "error message"
summary ~ "login bug"
description ~ "timeout"
comment ~ "workaround"
```
## Combining Conditions
```jql
project = PROJ AND status = Open
priority = High OR priority = Highest
project = PROJ AND (status = Open OR status = "In Progress") AND assignee = currentUser()
NOT status = Done
project = PROJ ORDER BY priority DESC, created ASC
```
## Keywords
| Keyword | Usage |
|---------|-------|
| `AND` | Both conditions must match |
| `OR` | Either condition matches |
| `NOT` | Negate a condition |
| `EMPTY` | Alias for null/no value |
| `NULL` | Alias for empty/no value |
| `ORDER BY` | Sort results (`ASC` or `DESC`) |
## Quoting Rules
**Must quote values containing:**
- Spaces: `project = "My Project"`
- Special characters: `summary ~ "error@host"`
- Reserved words used as values: `labels = "AND"`
**No quotes needed for:**
- Single words: `status = Open`
- Project keys: `project = PROJ`
- Function calls: `assignee = currentUser()`
## Cloud vs Server/DC Differences
- **User references**: Cloud uses `accountId` (e.g. `assignee = "5b10ac8d82e05b22cc7d4ef5"`), Server/DC uses `username` (e.g. `assignee = "john.doe"`). The `currentUser()` function works on both.
- Functions like `currentUser()`, `membersOf()`, date functions, and sprint functions work on both platforms.
## Sources
**Cloud:**
- [JQL Operators](https://support.atlassian.com/jira-software-cloud/docs/jql-operators/)
- [JQL Functions](https://support.atlassian.com/jira-software-cloud/docs/jql-functions/)
- [JQL Keywords](https://support.atlassian.com/jira-software-cloud/docs/jql-keywords/)
**Server/Data Center:**
- [JQL Operators (Server/DC)](https://confluence.atlassian.com/jirasoftwareserver/advanced-searching-operators-reference-939938753.html)
- [JQL Functions (Server/DC)](https://confluence.atlassian.com/jirasoftwareserver/advanced-searching-functions-reference-939938746.html)
- [JQL Keywords (Server/DC)](https://confluence.atlassian.com/jirasoftwareserver/advanced-searching-keywords-reference-939938757.html)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |