Jira Communication

Jira Communication

CLI scripts via uv run, all supporting --help, --json, --quiet, --debug.

Auto-Trigger

On Jira URL or issue key (PROJ-123), pick by intent — each is one call:

Auth issues → jira-setup.py. Anti-pattern: get + comment list on one key — use the matching verb. See references/intent-verbs.md.

Scripts

Under ${CLAUDE_SKILL_DIR}/scripts/{core,workflow,utility}/.

Core: jira-issue.py, jira-search.py, jira-worklog.py, jira-attachment.py, jira-setup.py, jira-validate.py Workflow: jira-create.py, jira-transition.py, jira-comment.py, jira-move.py, jira-sprint.py, jira-board.py, jira-version.py Utility: jira-user.py, jira-fields.py, jira-link.py, jira-weblink.py, jira-worklog-query.py, jira-watchers.py, jira-qa-gather.py

Execution Style

Run directly. Scripts report ✓/✗. Destructive ops: --dry-run. Global flags before subcommand: jira-issue.py --json get PROJ-123.

Basic Usage

uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py get PROJ-123
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-search.py query "assignee = currentUser() AND status != Closed" -n 5 -f key,summary,status
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py update PROJ-123 --assignee me --priority Critical
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py add PROJ-123 "Comment text"
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-transition.py do PROJ-123 "In Progress"
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-worklog.py add PROJ-123 2h --comment "Work done"
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-create.py issue PROJ "Summary" --type Task
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-attachment.py add PROJ-123 screenshot.png

Terminal transitions: always pass --resolution <value> (e.g. Done, Won't do, Duplicate) or the

resolution field stays empty and the ticket appears unresolved. See references/intent-verbs.md.

Related Skills

jira-syntax: For descriptions/comments. Jira uses wiki markup, not Markdown.

References

• references/jql-quick-reference.md, references/jql-cookbook.md — JQL beyond simple filters
• references/multi-profile.md — multiple Jira instances, --profile
• references/troubleshooting.md — auth, SSL, 401, 403, connection
• references/issue-editing.md — --description, --fields-json, reporter, deletes, moves
• references/creation.md — --parent, components, custom fields
• references/comments.md — edit, delete, list, markup lint / --force
• references/worklog.md — --started, date ranges, jira-worklog-query.py
• references/attachments.md — upload, download (cwd-only), inspect
• references/links.md — issue/web links, instance-specific link types
• references/agile.md — sprints, boards, board --name
• references/fields-and-users.md — custom field IDs, users, issue types
• references/watchers.md — watch, subscribe, list watchers
• references/versions.md — fix/affects versions, releases, version CRUD
• references/qa-gather.md — comprehensive audit bundle (siblings, prose URLs)
• references/intent-verbs.md — work / qa / qa-fail / act, exact transition names

Authentication

Cloud: JIRA_URL + JIRA_USERNAME + JIRA_API_TOKEN. Server/DC: JIRA_URL + JIRA_PERSONAL_TOKEN. Config via ~/.env.jira or ~/.jira/profiles.json.

<!-- Managed by agent: keep sections & order; edit content, not structure. Last updated: 2025-12-12 -->

AGENTS.md — jira-communication

Development guide for maintaining and extending the Jira communication scripts.

Overview

Python CLI scripts using uv run. Each script is standalone with PEP 723 inline dependencies.

Setup & environment

Development requires Python 3.10+ and uv. No virtual environment needed - uv run handles dependencies.

Build & tests

# Test a script works
uv run scripts/core/jira-validate.py --help

# Test against real Jira (need ~/.env.jira configured)
uv run scripts/core/jira-validate.py --verbose

Code style & conventions

Script structure:

• Use argparse with subcommands
• Import shared lib: from lib.client import get_jira_client
• PEP 723 header for inline dependencies
• PYTHONPATH manipulation at top (copy from existing scripts)

Output formats: Every script must support --json, --quiet, and default table output via lib/output.py.

Write operations: Destructive operations (delete, move) must include --dry-run flag.

Security & safety

• Never hardcode credentials
• Use lib/config.py for env loading
• Test --dry-run before actual writes

PR/commit checklist

• [ ] Script follows existing structure (copy from similar script)
• [ ] All three output formats work (--json, --quiet, table)
• [ ] --dry-run for any write operation
• [ ] --help is descriptive
• [ ] Update SKILL.md with new script docs

Good vs. bad examples

Adding a new script:

# ✓ Copy structure from existing script
# ✓ Use lib/ imports
# ✓ Support all output formats

# ✗ Write from scratch without looking at patterns
# ✗ Hardcode auth or skip --dry-run

When stuck

• Copy structure from scripts/core/jira-issue.py (good reference)
• Check lib/ for shared utilities
• Run --help on similar scripts

House rules

• Don't read SKILL.md for development - it's user docs
• Test against real Jira before PR

---

Maintaining this file: See root AGENTS.md for convention reference.

Agile — Sprints and Boards

When to load

Load this reference whenever the user wants to list sprints, list boards, move issues between sprints, or identify the active sprint for a board.

Boards

# All boards visible to the authenticated user
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-board.py list

# Filter by project
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-board.py list --project PROJ

# Show only Scrum or Kanban
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-board.py list --type scrum

Sprints

# Sprints for a specific board (positional BOARD_ID)
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-sprint.py list 119

# Filter by state
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-sprint.py list 119 --state active

# The single currently-active sprint for a board
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-sprint.py current 119

# Issues in a sprint (positional SPRINT_ID)
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-sprint.py issues 916

Assigning an issue to a sprint

The Sprint custom field takes the sprint's integer ID (not its name). Resolve the field's id via jira-fields.py search "sprint" on your instance; it's typically customfield_<N>.

# Substitute the real custom-field id from `jira-fields.py search "sprint"`
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py update PROJ-123 \
    --fields-json '{"customfield_SPRINT": 916}'

See issue-editing.md for more on --fields-json, and fields-and-users.md for looking up the sprint custom-field ID on other instances.

Scrum vs Kanban

• Scrum boards own named sprints; issues have a Sprint field with an integer ID.
• Kanban boards have no sprints — the Sprint field is always empty; jira-sprint.py list <KANBAN_BOARD_ID> returns an empty array, not an error.

Attachments — Upload and Download

When to load

Load this reference whenever the user wants to attach a file to an issue, download an attachment, or work with attachment URLs (including any concerns about path traversal, size limits, or SSRF).

Upload

# Simple upload (single file per invocation)
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-attachment.py add PROJ-123 screenshot.png

# Preview (no upload, just show what would be sent)
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-attachment.py add PROJ-123 /tmp/report.pdf --dry-run

# Multiple files — call `add` once per file
for file in a.png b.png c.pdf; do
    uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-attachment.py add PROJ-123 "$file"
done

jira-attachment.py add takes a single FILE_PATH argument (absolute or relative) and only requires that the file exists and is readable. There is no --allow-absolute flag and no cwd-confinement on the upload side — validate paths in the caller if needed.

Download

jira-attachment.py download takes two positional arguments: the attachment URL and the output file path. Find the URL via jira-issue.py get --json (the fields.attachment[].content field carries the download URL).

# Positional: full URL (or /rest/api/2/attachment/content/<id>) + output file
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-attachment.py download \
    "https://jira.example.com/rest/api/2/attachment/content/12345" \
    ./attachments/report.pdf

Download all attachments

To grab every attachment on an issue in one call (no need to harvest URLs first), use download-all. Files are saved under --dir (default cwd) using their original Jira filenames; duplicate names are disambiguated with the attachment id, and a filename that would escape --dir is skipped.

# All attachments into the current directory
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-attachment.py download-all PROJ-123

# Into a specific directory (created if missing, must stay within cwd)
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-attachment.py download-all PROJ-123 --dir ./attachments

# Preview the list without downloading
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-attachment.py download-all PROJ-123 --dry-run

Safety guarantees

• Path traversal: output paths are constrained to the current working directory — the script rejects targets that resolve outside cwd. cd to the target directory before downloading. download-all additionally strips path components from each Jira-supplied filename and constrains it within --dir.

Don't use raw curl

Fetching /secure/attachment/... URLs with plain curl returns the Jira login page, not the file — attachment downloads need the authenticated session handling this script provides. Always use jira-attachment.py download.

Comments — Edit, Delete, List

When to load

Load this reference whenever the user wants to edit or delete an existing comment, list comments, or needs to get a comment ID for any reason.

List and get IDs

# Pretty list (most recent last)
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py list PROJ-123

# JSON list — use this to harvest comment IDs for edit/delete
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py --json list PROJ-123

The JSON output has a top-level comments array; each entry has id, author.displayName, body, and updated.

Edit an existing comment

# Full replacement of the body — edits preserve created timestamp, update the "updated" timestamp
# (issue key, comment ID and text are positional arguments)
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py edit PROJ-123 594276 "Corrected text"

Jira appends an "edited" marker in the UI automatically.

Delete a comment

# Preview
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py delete PROJ-123 594276 --dry-run

# Real delete
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py delete PROJ-123 594276

Deleting someone else's comment requires the Delete All Comments permission.

Multi-line comments

jira-comment.py add takes the body as a positional argument. Pass - to read the body from stdin, which pairs naturally with a HEREDOC or a file:

uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py add PROJ-123 - <<'EOF'
h3. Progress

Deployed to staging, see https://staging.example.com/.
EOF

# Or from a file
cat comment.txt | uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py add PROJ-123 -

Comments use Jira wiki markup — see the jira-syntax skill for formatting.

Markup lint

add and edit lint the body before posting: inline block tags ({code}, {noformat}, {quote}, {panel} are block-level — a tag with other text on the same line opens a block mid-prose) and unbalanced tag counts abort with an error. Escape literal mentions as \{code\}. Override with --force (findings are then printed as warnings).

Issue Creation — Advanced

When to load

Load this reference whenever the user wants to create a sub-task (--parent), set a custom reporter, attach components, or pass custom-field values on create via --fields-json.

Sub-tasks via --parent

# --type auto-resolves to the right sub-task issue type for the parent's project
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-create.py issue PROJ "Fix flaky test" \
    --type Bug --parent PROJ-100

When --parent is provided, jira-create.py resolves the sub-task issue type from the project's issue-type catalog (matching on name, case-insensitive). The parent issue itself is not fetched — resolution is project-scoped: an exact match on the requested type wins, otherwise a substring match against sub-task names (e.g., Task → Sub: Task), otherwise the sole sub-task type if only one exists.

Custom reporter

uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-create.py issue PROJ "User-reported bug" \
    --type Bug --reporter jane.doe

Value is the accountId on Cloud, the username on Server/DC. Resolve via jira-user.py search (see fields-and-users.md).

Components

uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-create.py issue PROJ "Summary" \
    --type Task --components "Backend,API"

Components must already exist on the project.

Custom fields on create

uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-create.py issue PROJ "Summary" \
    --type Task \
    --fields-json '{"customfield_SPRINT": 916, "customfield_EPIC": "PROJ-1940"}'

Sprint ID is an integer, not an array. Epic Link is the epic's issue key as a string.

Combining flags

--fields-json wins over typed flags (--assignee, --priority, --labels, --reporter, --components) when the same field is set in both — the script merges the JSON payload onto the typed-flag payload (fields.update(extra_fields)). Use typed flags for the fields the CLI exposes directly, and reach for --fields-json only for the long tail.

Fields and Users — Reference Data Lookup

When to load

Load this reference whenever the user needs to: look up a custom field ID, list issue types for a project, search for a Jira user, or resolve a username/accountId for use as a reporter, assignee, or watcher value.

Users

# Resolve a specific identifier — prints the canonical record
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-user.py get john.doe

# Free-text search (by display name or email fragment)
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-user.py search "doreen"

# The current authenticated user (what `--assignee me` resolves to)
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-user.py me

Useful when --assignee, --reporter, or --user rejects a value: search returns the canonical username (Server/DC) or accountId (Cloud) the API expects.

`[~mention]` in comments needs the canonical username, not a guess. The mention token resolves on the account's name/key — which can differ from both the display name and the email local-part (renamed accounts are common: e.g. display "Jane Doe", email jane.doe@…, but name=jane.smith after a rename). Guessing from the display name or email silently produces a non-notifying mention. Resolve it first — jira-user.py search "<display name>", or read the name field of an existing comment's author — then write [~<name>]. If someone says "your mention pinged the wrong/no user", this is why. (Jira Cloud uses [~accountId:<accountId>] instead of [~username]; resolve the accountId the same way and use that form.)

Custom fields

# Search field metadata by name fragment
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-fields.py search "sprint"
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-fields.py search "epic"

# Dump all fields as JSON (for grep/jq pipelines)
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-fields.py --json search ""

The key you need for --fields-json is the id (e.g. customfield_<N>) — not the human name.

Issue types per project

uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-fields.py types PROJ

Prints every issue type the project accepts, including sub-task types. Issue type names are case-sensitive on create (jira-create.py --type).

Common custom-field shapes (IDs vary per instance)

Always confirm the id with jira-fields.py search on the target instance — custom-field numbering is not portable.

Intent verbs

jira-issue.py work / qa / qa-fail / act — single-call context bundles for the four common intents.

When to load

Whenever you have a Jira issue key and need more than just meta. Each verb composes the right bundle for one intent. Empirically replaces 3–6 separate calls.

The four verbs

jira-issue.py work    KEY   # description + all comments + attachments + links
jira-issue.py qa      KEY   # description + handover bundle (comments around INTO_QA transition)
jira-issue.py qa-fail KEY   # description + reviewer rejection + implementer scope context
jira-issue.py act     KEY   # meta + available transitions

jira-issue.py get KEY is unchanged — it still prints the full issue (description, attachments, links) by default. Use --fields summary,status,assignee,… for a meta-only lookup.

QA-handover heuristic (qa verb)

The handover comment is not always written after the transition. Empirical sample (10 tickets, 41 transitions): 80% of handover comments come before the transition click.

The verb finds the most recent INTO_QA transition (by classification, see below) and includes:

1. All comments by the transition author in [T_prev, min(T_next, T_transition + 1h)] — captures the handover whether written before or after the click. T_prev and T_next bracket the transition between adjacent status changes. 2. All comments by any author in [T_transition, T_next) — the QA discussion that follows.

Deduplicated, chronologically sorted. Fallback if no INTO_QA in changelog: last 5 comments + warning.

QA-fail heuristic (qa-fail verb)

Symmetric to qa:

1. Find the most recent REJECT transition. 2. Include all comments by the reviewer (transition author) in [T_prev_into_qa, T_transition + 1h]. 3. Include all comments by any author in [T_transition, T_next). 4. Include all comments by the implementer (= author of the most recent INTO_QA before the reject) in [T_prev_into_qa - 1h, T_transition] — this captures the implementer's scope/clarification context that the rejection is reacting to. The 1h backward extension catches handover comments written just before the INTO_QA click.

Fallback if no REJECT in changelog: last 5 comments + warning.

Status-set classification

Transitions are classified using three configurable status sets:

A transition is classified as:

• into_qa — from ∉ qa AND to ∈ qa (handover)
• reject — from ∈ qa AND to ∈ working (fail)
• forward — from ∈ qa AND to ∈ qa AND from ≠ to (multi-stage progression: QA→QA2, Review→UAT, QA→Acceptance — NOT a fail)
• resolved — to ∈ resolved — always pass `--resolution <value>` when executing this transition (see below)
• out — from ∈ qa AND to ∉ qa (uncategorised QA exit)
• other — neither side touches QA

Forward-progression detection is what lets a multi-stage QA workflow (Review → UAT → Acceptance → Closed) work identically to a single-stage one without code changes.

Resolution field on terminal transitions

When a transition lands in a resolved status, Jira stores two separate things: the status (visible in the badge) and the resolution (the green checkmark, JQL resolution is not EMPTY). The transition API sets the status but leaves the resolution field empty unless you pass it explicitly. An empty resolution means the ticket appears unresolved in filters and dashboards even though the status reads "Resolved".

Always pass --resolution with the value that matches the outcome:

jira-transition.py do PROJ-123 "Resolved" --resolution Done
jira-transition.py do PROJ-123 "Resolved" --resolution "Won't do"
jira-transition.py do PROJ-123 "Resolved" --resolution Duplicate

Available resolution names vary by Jira instance. Query yours with:

curl -s -H "Authorization: Bearer $JIRA_PERSONAL_TOKEN" "$JIRA_URL/rest/api/2/resolution" \
  | python3 -c "import sys,json; [print(r['name']) for r in json.load(sys.stdin)]"

Walking a multi-stage workflow (path)

jira-transition.py do performs one transition. Workflows with intermediate gates (e.g. QA → UAT Stage → Ready for deployment → Resolved → Closed) otherwise need one list + one do per stage — closing a ticket deep in such a workflow is 4+ round-trips of discovering the next status by hand.

path collapses that into one call: it runs the list → pick → do loop internally, walking from the current status to a target.

jira-transition.py path PROJ-123 Closed --resolution Done   # walk all the way to Closed
jira-transition.py path PROJ-123 "Ready for deployment"     # walk to an intermediate gate
jira-transition.py path PROJ-123 Closed --dry-run           # preview the first step

It is a greedy walk, not a graph search: the Jira API only exposes the transitions available from the issue's current status, so path cannot see the whole workflow ahead of time. At each step it takes the target if directly reachable, otherwise the single non-backward transition (transitions whose name matches reopen/cancel/reject/decline/abort/back, or which lead to an already-visited status, are treated as backward). If a step offers several forward options it stops and lists them rather than guess — pick one with do and re-run. --resolution/--comment apply only to the final step; --max-steps (default 10) caps the walk. Because it cannot look ahead, --dry-run shows only the first planned step.

Configuring status sets per Jira instance

Per profile in ~/.jira/profiles.json:

{
  "profiles": {
    "myinstance": {
      "url": "https://jira.example.com",
      "token": "...",
      "qa_status_names": ["Review", "UAT", "Acceptance"],
      "working_status_names": ["In Progress", "Backlog", "Reject"],
      "resolved_status_names": ["Done", "Cancelled"]
    }
  }
}

Or via env vars (comma-separated):

JIRA_QA_STATUS_NAMES="Review,UAT,Acceptance"
JIRA_WORKING_STATUS_NAMES="In Progress,Backlog,Reject"
JIRA_RESOLVED_STATUS_NAMES="Done,Cancelled"

Output formats

All verbs support the standard global flags:

• (default) Human-readable text bundle
• --json Structured payload (comments is always a list of comment dicts; verb-specific keys like reject_transition, handover_transition, implementer for context)
• --quiet Issue key only (after successful fetch — validates connectivity)

work, qa, qa-fail also accept --truncate N to cap description and per-comment body length. act has no body content so the flag is omitted there.

Example: NRS-4412-style QA-fail follow-up

The motivating case: "what did Björn reject, and what was Sebastian's scope context?"

Before (6 calls): jira-issue get, jira-comment list, jira-comment list | tail, jira-comment list | head, etc.

After (1 call):

jira-issue.py qa-fail NRS-4412

Returns: description + Sebastian's scope-setting handover comment + Björn's full AC review with rejection + Sebastian's response + subsequent resolution. Chronologically sorted, ready to read.

Transition names are exact strings

jira-transition.py do KEY "<name>" matches the transition name verbatim — including emoji prefixes some instances configure (e.g. ✅ Resolve, ❌ QA failed). On mismatch the error lists the available names; copy the wanted one exactly as printed. jira-issue.py act KEY shows them up front.

Issue Editing — Advanced

When to load

Load this reference whenever the user wants to set --fields-json, set a custom --reporter, delete an issue (especially with sub-tasks), attempt an unsupported cross-project move via CLI (see below), or change any field that is not assignee, priority, or labels.

--description for plain description edits

For a plain description rewrite, use the typed flag — it avoids JSON-escaping the body:

uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py update PROJ-123 \
    --description "Rewritten description"

# Pipe a longer body from a file
cat body.txt | uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py update PROJ-123 --description -

The body is Jira wiki markup (see the jira-syntax skill).

--fields-json for custom fields and structured payloads

jira-issue.py update accepts a raw JSON object to set any field the Jira REST API exposes — reach for it when the typed flags don't cover the field:

# Custom fields (Sprint ID as integer, Epic Link as issue key)
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py update PROJ-123 \
    --fields-json '{"customfield_SPRINT": 916, "customfield_EPIC": "PROJ-1940"}'

# Combine with typed flags — `--fields-json` wins on conflict
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py update PROJ-123 \
    --priority Critical \
    --fields-json '{"labels": ["review", "urgent"]}'

The script merges --fields-json onto the typed-flag payload (update_fields.update(extra_fields)), so any key present in both is taken from --fields-json. Use typed flags for fields the CLI exposes directly, and reach for --fields-json only for the long tail.

Look up custom field IDs with jira-fields.py — see fields-and-users.md.

Labels: replace vs incremental updates

jira-issue.py update supports three modes:

• --labels a,b,c replaces the full label set.
• --add-label / --remove-label incrementally update labels without wiping unrelated tags.
• Do not combine --labels with --add-label / --remove-label in one invocation.

Each --add-label / --remove-label may be repeated and may contain comma-separated values. Matching for removals is case-insensitive, and additions dedupe case-insensitively while preserving the casing already stored in Jira when possible.

uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py update PROJ-123 \
  --add-label backend --add-label urgent,frontend --remove-label stale

Setting a custom reporter

jira-issue.py update has no --reporter flag; the reporter on an existing issue is changed through --fields-json:

# Cloud (accountId) or Server/DC (name) — both go through --fields-json
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py update PROJ-123 \
    --fields-json '{"reporter": {"name": "jane.doe"}}'

On Jira Cloud, use {"reporter": {"accountId": "..."}} instead. The create-time shortcut is the typed --reporter flag on jira-create.py — see creation.md.

Deleting issues

# Always preview first
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py delete PROJ-123 --dry-run

# Real delete
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py delete PROJ-123

# Parent with sub-tasks — the API rejects it unless you opt in
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py delete PROJ-100 --delete-subtasks

--delete-subtasks cascades the delete. The script refuses without it when sub-tasks exist.

Moving an issue between projects

Cross-project moves are not implemented in jira-move.py because some Jira Server/DC versions accept project edits via the standard issue endpoint without actually moving the issue (silent partial updates / corruption risk). The command refuses cross-project targets for both real execution and --dry-run.

Use the Jira UI Move action (or a bulk-move workflow your admins provide) for cross-project relocation.

Within the same project, jira-move.py can change issue type:

# Preview a same-project type change
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-move.py issue PROJ-100 PROJ --issue-type Task --dry-run

# Execute the type change (issue key stays the same)
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-move.py issue PROJ-100 PROJ --issue-type Task

JQL Cookbook — Translating Natural-Language Queries

When to load

Load this reference whenever the user phrases a search request in natural language ("show me all stale bugs", "what have I been working on this sprint") and you need to decide which JQL expression is safe for which phrasing.

How to turn questions like "all my open bugs with no activity in 2 weeks" into safe, portable JQL — and which built-in scripts help with the fuzzy parts (status names, usernames, board names).

This doc complements jql-quick-reference.md, which covers JQL syntax. This one covers reasoning: which JQL expression is safe for which natural-language term, and what to do when the user's phrasing is ambiguous.

---

Fuzzy term → safe JQL

---

Status ambiguity — the #1 gotcha

Jira distinguishes status (workflow-specific) from statusCategory (instance-wide). The three categories are always:

• "To Do" — issues not started
• "In Progress" — issues actively being worked
• Done — finished issues

Rule of thumb: prefer `statusCategory` over `status` whenever the user's wording is a category-level concept ("open", "done", "active").

Reach for a specific status = "X" only when the user names a concrete workflow step ("Code Review", "Staging Tested", "Awaiting QA").

---

"Blocked" — three distinct meanings

When the user says "what's blocked?" without more context, start with the Flagged interpretation on Agile projects, and confirm the intent.

---

"Stale" — update vs. transition

If the user says "issues stale in Review for >14 days", plain updated < -14d is not right — a comment or description edit also updates updated. Two options:

1. Approximation (pure JQL): status = Review AND updated < -14d — catches most cases, but misses issues that had recent edits while still stuck in Review. 2. Exact (needs changelog): use jira-issue time-in-status <KEY> --status Review on each candidate to get the true per-status duration.

Document the limitation when presenting the result.

---

Resolution helpers — point the user here

Most fuzzy terms can be resolved before building JQL:

When a resolver returns an ambiguous result, surface the candidates and ask the user — don't silently pick the first match.

---

Worked example 1: "all bug issues open for more than 2 weeks"

Step 1 — parse the terms:

• "bug" → issuetype = Bug (⚠️ verify per instance)
• "open" → statusCategory != Done
• "for more than 2 weeks" → ambiguous; three interpretations:
• A: no activity for 14+ days → updated < -14d
• B: existed 14+ days → created < -14d
• C: stuck in current status 14+ days → needs time-in-status,

not pure JQL

Step 2 — pick the most common interpretation: A.

Step 3 — assemble:

issuetype = Bug AND statusCategory != Done AND updated < -14d

Step 4 — surface the assumption:

"I interpreted '2 weeks open' as 'no activity for 14+ days'.

If you meant created 14+ days ago or *stuck in one status for 14+

days*, say so and I'll rerun."

---

Worked example 2: "all my issues with no activity past 2 weeks"

• "my" → assignee = currentUser()
• "no activity" → updated
• "past 2 weeks" → < -14d

assignee = currentUser() AND updated < -14d

No resolvers needed. No ambiguity worth surfacing.

---

Worked example 3: "how long has PROJ-123 been in Review?"

Not a JQL question — use the changelog:

uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-issue.py \
    time-in-status PROJ-123 --status review

--status review resolves via resolve_status(); matches "In Review" or "Code Review" unambiguously on most instances.

---

Ambiguity protocol

When translating, Claude should:

1. Translate unambiguous mappings directly — "my" → currentUser(), "open" → statusCategory != Done. 2. Resolve instance-specific terms before building JQL — run resolve_status / jira-user search when the term names a status or person. 3. Pick a sensible default for vague time terms — "recently" → 7d, "stale" → 14d, "long-standing" → 30d — and state the assumption in the response. 4. On resolver ambiguity, ask — never silently pick the first match. Surface the candidates. 5. When no pure-JQL expression is accurate, say so — e.g., "stale in Review" strictly needs time-in-status; JQL alone is an approximation.

---

What's deliberately not here

• Hardcoded per-workflow shortcuts like status = "Code Review".

Status names vary per instance. Resolve first.

• Saved-query templates. Users who want named saved JQLs can use

Jira's built-in Filters (web UI) — they're reusable across this skill and Jira itself.

• Priority / resolution name lists. These are instance-configurable;

fetch them at runtime via the REST API.

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):

# 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

Text Search

List & Null

Historical

CHANGED supports predicates: FROM, TO, BY, DURING, BEFORE, AFTER, ON

status CHANGED FROM "Open" TO "In Progress" BY currentUser() AFTER -7d

Functions

User Functions

Date Functions

Date offsets: startOfDay(-1) = yesterday, startOfWeek(1) = next week

Relative Dates

Sprint Functions

Version Functions

Common Queries

By Assignment

assignee = currentUser()
assignee = "john.doe"
assignee IS EMPTY
assignee IN membersOf("developers")

By Status

status = "In Progress"
status IN (Open, "To Do", "In Progress")
status != Done
status WAS "Open"
status CHANGED FROM "Open" TO "In Progress"

By Date

created >= -7d
updated >= startOfWeek()
due <= endOfMonth()
resolved >= "2024-01-01"
created >= startOfMonth(-1) AND created < startOfMonth()

By Sprint

sprint IN openSprints()
sprint IN closedSprints()
sprint = "Sprint 42"
sprint IS EMPTY

By Text

text ~ "error message"
summary ~ "login bug"
description ~ "timeout"
comment ~ "workaround"

Combining Conditions

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

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
• JQL Functions
• JQL Keywords

Server/Data Center:

• JQL Operators (Server/DC)
• JQL Functions (Server/DC)
• JQL Keywords (Server/DC)

Links — Issue-to-Issue and Web Links

When to load

Load this reference whenever the user wants to create, list, or delete a link between two issues (jira-link.py), or a web link from an issue to an external URL (jira-weblink.py).

⚠️ Direction rule (read this before create)

jira-link.py create FROM TO --type X creates the link such that `TO` is the source/active actor (uses the link type's outward verb) and `FROM` is the destination/passive recipient (uses the inward verb).

>

Mnemonic: *TO is the agent, FROM is the patient.*

Read the call as: "on FROM, record that TO does X to it."

This matches Atlassian's REST API convention — but watch the field-name trap: in the stored link object, `inwardIssue` holds the source (active actor with the outward verb) and `outwardIssue` holds the destination (passive recipient with the inward verb). The names seem to imply the opposite; they don't. Verify after every create by reading the success sentence. The --source / --target aliases in the next section make the intent explicit:

• create FROM TO --type X ≡ create --source TO --target FROM --type X

jira-link.py prints the resulting natural-language sentence on success, so you can verify the direction immediately:

Created: IOS-18 causes NRS-878 (link-type: Cause)

Issue-to-issue links

# Create — see the direction rule above. TO is the active actor.
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-link.py create PROJ-123 PROJ-456 --type Blocks
# → "PROJ-456 blocks PROJ-123"

# Equivalent named form (recommended for clarity):
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-link.py create \
    --source PROJ-456 --target PROJ-123 --type Blocks

# Preview without writing — also prints the resolved sentence
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-link.py create PROJ-123 PROJ-456 --type Blocks --dry-run

# List — shows inward and outward links together
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-link.py list PROJ-123

# Delete by link ID (from `list --json`)
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-link.py delete PROJ-123 --id 10042

Link type naming: the canonical name (as displayed by Jira and stored in the link object) varies per instance — confirm yours via jira-link.py list-types or jira-fields.py search "link". The --type argument matches case-insensitively against the canonical name (blocks, Blocks, BLOCKS all resolve to the same type), so case mismatches will not fail; non-existent type names will.

Typical link types (names vary per instance)

In create FROM TO --type T, TO is the active party and uses the outward verb. The table is keyed on the link-type name as you pass it to --type.

Confirm the exact names on your instance via jira-link.py list-types or the admin panel.

Worked examples

Each example shows the call, the resulting natural-language sentence, and what each endpoint's view shows in the Jira UI after the link is created.

1. Blocker (infrastructure blocks a frontend ticket)

uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-link.py create FRONTEND-12 INFRA-99 --type Blockade
# Created: INFRA-99 blocks FRONTEND-12 (link-type: Blockade)

After creation:

• On FRONTEND-12 you see: is blocked by ← INFRA-99
• On INFRA-99 you see: blocks → FRONTEND-12

2. Root cause (root issue causes the observed effect)

uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-link.py create EFFECT-1 ROOT-2 --type Cause
# Created: ROOT-2 causes EFFECT-1 (link-type: Cause)

After creation:

• On EFFECT-1 you see: is caused by ← ROOT-2
• On ROOT-2 you see: causes → EFFECT-1

3. Side effect (a change affects an unrelated component)

uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-link.py create AFFECTED-3 CHANGE-4 --type "Side effect"
# Created: CHANGE-4 affects AFFECTED-3 (link-type: Side effect)

After creation:

• On AFFECTED-3 you see: is affected by ← CHANGE-4
• On CHANGE-4 you see: affects → AFFECTED-3

Bulk operations

bulk-create — create many links from a CSV

# CSV format (header required)
$ cat links.csv
from,to,type
IOS-18,NRS-878,Cause
IOS-18,NRT-4388,Deploy
IOS-18,NRS-3106,Side effect

# Preview every row's resolved sentence (no API calls)
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-link.py bulk-create \
    --from-csv links.csv --dry-run

# Run for real, halting on first failure
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-link.py bulk-create \
    --from-csv links.csv

# Skip rows where a same-type link between FROM and TO already exists
# (Jira Server is NOT idempotent on link creation — duplicates are possible)
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-link.py bulk-create \
    --from-csv links.csv --skip-existing

# Keep going past failures (records, doesn't abort)
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-link.py bulk-create \
    --from-csv links.csv --continue-on-error

The CSV from, to, type columns map to create FROM TO --type X exactly — same direction rule applies. Each row resolves through the same dry-run sentence before commit.

bulk-delete — delete many links by ID

# By comma-separated IDs
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-link.py bulk-delete \
    --ids 10042,10043,10044 --dry-run

# From a file (one ID per line)
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-link.py bulk-delete \
    --ids-file ids.txt

Get the IDs from jira-link list <ISSUE-KEY> --json first.

invert — fix a backwards link in one shot

# Preview: shows current sentence and inverted sentence
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-link.py invert \
    --id 10042 --dry-run
# Would invert: ROOT-2 causes EFFECT-1 → EFFECT-1 causes ROOT-2

# Commit the inversion (deletes original, creates swapped)
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-link.py invert --id 10042

Destructive — the original link is deleted before the inverted one is created. If the create fails, the script attempts to recreate the original. If both calls fail, you'll get an INCONSISTENT STATE error pointing at the link ID — fix it in the Jira UI.

This is the one-shot fix when --dry-run shows you a backwards sentence after a create.

Real-world reference

The netresearch-jira skill bundles a linking-conventions reference with concrete CHILD/PARENT examples for the Netresearch Jira instance. The direction semantics there agree with this document and serve as a sanity check before you call create.

Web links (links to external URLs)

# Create a web link
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-weblink.py add PROJ-123 \
    --url "https://example.com/design-doc" --title "Design doc"

# List
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-weblink.py list PROJ-123

# Delete by ID
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-weblink.py delete PROJ-123 --id 42

Web links are scoped per issue; the same URL on two issues is two independent web links.

Multi-Profile Configuration

When to load

Load this reference whenever the user mentions more than one Jira instance, asks about --profile, .jira-profile, or ~/.jira/profiles.json, or when auto-resolution by URL/issue-key prefix is unclear.

Manage connections to multiple Jira instances via ~/.jira/profiles.json.

Profile Resolution Priority

When a script runs, it resolves which profile to use in this order:

1. Explicit `--profile` flag — --profile myprofile selects the named profile directly 2. Full Jira URL — matches the URL's host against each profile's url field (normalized, port-insensitive) 3. Issue key prefix — matches the project prefix (e.g. WEB from WEB-1381) against each profile's projects list 4. `.jira-profile` file — reads the profile name from a .jira-profile file in the current working directory 5. Default profile — uses the default key from profiles.json

If none of the above match, the script raises an error listing available profiles.

--profile Flag

All scripts accept --profile (or -P) to select a profile explicitly:

uv run scripts/core/jira-issue.py --profile cloud get WEB-123
uv run scripts/core/jira-search.py --profile server query "project = OPS"

~/.jira/profiles.json Format

{
  "default": "cloud",
  "profiles": {
    "cloud": {
      "url": "https://yourcompany.atlassian.net",
      "auth": "cloud",
      "username": "user@example.com",
      "api_token": "your-cloud-api-token",
      "projects": ["WEB", "MOBILE", "API"]
    },
    "server": {
      "url": "https://jira.yourcompany.com",
      "auth": "pat",
      "token": "your-personal-access-token",
      "projects": ["OPS", "INFRA", "SRVMO"]
    }
  }
}

Fields

Top-Level Keys

.jira-profile File

Place a .jira-profile file in a project directory to set the default profile for that project:

echo "server" > /path/to/my-project/.jira-profile

When you run a script from that directory without --profile and without an issue key match, the profile named in .jira-profile is used.

Auto-Resolution from Issue Key

When you reference an issue like WEB-123, the script extracts the project prefix WEB and checks each profile's projects list. If exactly one profile lists WEB, that profile is selected automatically.

If multiple profiles claim the same project prefix, the script raises an error asking you to disambiguate with --profile.

Migration and Management

• `--migrate`: Use jira-setup.py --migrate to convert an existing ~/.env.jira file into a profile in ~/.jira/profiles.json.
• `--all-profiles`: Use jira-validate.py --all-profiles to validate all configured profiles at once.

Fallback Behavior

If ~/.jira/profiles.json does not exist, scripts fall back to the legacy ~/.env.jira file and environment variables. The --profile flag requires profiles.json to exist.

QA Gather

When to load

Load this reference when reviewing a ticket transitioned to QA / In Review / Ready for Review, or when the user asks for "QA review", "peer review", "review and resolve", or pulls a ticket from a team-review queue. Also when a peer-review style runbook (e.g. `peer-qa-review`) needs single-call context discovery for Stage 0 of its lifecycle.

The script gives you everything a reviewer typically chases across 4–5 separate calls — issue + description + comments + worklog + structured issue links + web/remote links + URLs scraped from prose (MR/PR/pipeline/commit/tag/release) + sibling tickets — in one shot.

Command

uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-qa-gather.py PROJ-123
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-qa-gather.py PROJ-123 --json

Read-only. No --dry-run needed.

Options

Output (default mode)

Human-readable sections, in order:

1. Issue key + summary 2. Status, comment count, worklog count + total minutes 3. Structured issue links (<type> → <key>: <summary> for outward, ← for inward) 4. Web/remote links (title: url) 5. URLs extracted from prose, grouped by category: merge_request, pull_request, pipeline, commit, tag, release, issue_link 6. Sibling tickets in the same project, sorted by updated DESC

JSON shape (with --json)

Top-level keys (stable):

• issue_key — string, the requested key
• issue — full Jira issue dict from client.issue() with expand=renderedFields
• comments — list of comment dicts (extracted from the issue payload, no second API call)
• worklogs — list of worklog dicts
• worklog_total_seconds — int
• issue_links — list (raw issuelinks from the issue)
• web_links — list (from get_issue_remote_links)
• extracted_urls — {category: [url, ...]} deduplicated, order-preserved
• siblings — list of issue dicts (summary + status + resolutiondate + updated)

Sibling-search semantics

Same project, summary-token overlap (case-insensitive heuristic, 4-char minimum, stop-list filtered, max 5 keywords from the source ticket's summary), updated >= -<window>d, ordered by updated DESC. Includes both resolved and still-open tickets — open sibling work is often the most relevant for QA. Project and issue keys are quoted in the JQL string to handle keys with special characters.

Failure modes

• Issue fetch fails → script exits non-zero with a sanitized error.
• Worklog / web-links / sibling-search failures → warning to stderr, the corresponding JSON field is empty/[], the script continues. The first (issue) fetch is the only hard dependency.
• Exception messages are passed through _sanitize_error() to redact tokens / passwords / api keys before being printed.

Companion runbook

The `peer-qa-review` skill provides the what to check / how to format the QA comment layer; this script provides the fetch the data layer. They compose: peer-qa-review's Stage 0 is "run jira-qa-gather; structure the rest of the review around the bundle."

If you have peer-qa-review loaded, prefer to follow its lifecycle (Claim → Discover → Formal → Functional+Inventory → Docs+Rollback+Comm → Verdict). If not, this script's output is still self-contained enough for a manual review pass.

Troubleshooting Guide

When to load

Load this reference whenever any script returns a non-zero exit code related to authentication, SSL, connectivity, or environment configuration — typically surfaced as HTTP 401/403, certificate errors, or JIRA_URL not set.

Setup Validation

Always start with:

uv run scripts/core/jira-validate.py --verbose

Exit Codes

Configuration

Scripts load configuration in priority order: 1. Explicit --env-file parameter (if provided) 2. ~/.jira/profiles.json (if exists) — supports multiple Jira instances with auto-resolution from issue key, URL, or .jira-profile file (see references/multi-profile.md) 3. ~/.env.jira file (legacy single-instance config) 4. Environment variables (fallback for missing values)

You can use any of these approaches. For multiple Jira instances, use ~/.jira/profiles.json.

Option A: Environment File

Create ~/.env.jira:

Jira Cloud

JIRA_URL=https://yourcompany.atlassian.net
JIRA_USERNAME=your-email@example.com
JIRA_API_TOKEN=your-api-token-here

Jira Server/Data Center

JIRA_URL=https://jira.yourcompany.com
JIRA_PERSONAL_TOKEN=your-personal-access-token

Option B: Environment Variables

Export variables directly (useful in CI/CD or when credentials are managed externally):

# Jira Cloud
export JIRA_URL=https://yourcompany.atlassian.net
export JIRA_USERNAME=your-email@example.com
export JIRA_API_TOKEN=your-api-token-here

# Or Jira Server/DC
export JIRA_URL=https://jira.yourcompany.com
export JIRA_PERSONAL_TOKEN=your-personal-access-token

Common Errors

"Configuration errors: Missing required"

Cause: Required variables not found in file or environment.

Fix: 1. Check ~/.env.jira exists with correct values, OR 2. Verify environment variables are exported 3. Variable names are case-sensitive 4. No quotes around values needed in .env.jira

"Failed to connect to Jira"

Cause: Network, URL, or SSL issues.

Fix: 1. Verify URL is correct (include https://) 2. Test URL in browser 3. Check VPN if on corporate network 4. For self-signed certs, may need JIRA_VERIFY_SSL=false

"401 Unauthorized"

Cause: Invalid credentials.

Cloud Fix: 1. Generate new API token at https://id.atlassian.com/manage-profile/security/api-tokens 2. Use email as JIRA_USERNAME, not display name

Server/DC Fix: 1. Create PAT in Jira: Profile → Personal Access Tokens 2. Use only JIRA_PERSONAL_TOKEN, not username/password

"403 Forbidden"

Cause: Valid auth but no permission.

Fix: 1. Verify account has project access 2. Check if IP allowlisting blocks API access 3. Confirm API access not disabled by admin

"No such option: --json"

Cause: Flag placed after subcommand.

Fix: Move flags before subcommand:

# Wrong
uv run scripts/core/jira-issue.py get PROJ-123 --json

# Correct
uv run scripts/core/jira-issue.py --json get PROJ-123

"Transition 'X' not available" (passing the transition ID)

Cause: jira-transition.py do expects the target status name, not the numeric transition ID that jira-transition.py list prints in its leftmost column.

Fix: Pass the destination status, in quotes:

# Wrong — 311 is the transition ID from `list`
uv run scripts/workflow/jira-transition.py do PROJ-123 311

# Correct — the To-Status name
uv run scripts/workflow/jira-transition.py do PROJ-123 "Resolved"

When two transitions share a name but differ by icon (e.g. "✅ QA" → Resolved vs "❌ QA" → Reopened), disambiguate by passing the target status ("Resolved" / "Reopened"), which is unique.

"Issue does not exist"

Cause: Wrong key or no permission.

Fix: 1. Verify issue key spelling and case 2. Confirm you have "Browse" permission on project 3. Check if issue was moved/deleted

"Field 'xyz' cannot be set"

Cause: Field not editable or wrong format.

Fix: 1. Use jira-fields.py search xyz to find correct field ID 2. Check field is on the edit screen for that issue type 3. Verify field format (some need {"name": "value"})

Debug Mode

Add --debug for full stack traces:

uv run scripts/core/jira-issue.py --debug get PROJ-123

Auth Mode Detection

Scripts auto-detect auth mode:

• If JIRA_PERSONAL_TOKEN set → Server/DC PAT auth
• If JIRA_USERNAME + JIRA_API_TOKEN set → Cloud basic auth
• URL containing .atlassian.net → Cloud mode

Override with JIRA_CLOUD=true or JIRA_CLOUD=false.

Versions — Releases and Fix/Affects Versions

When to load

Load this reference whenever the user asks about fix/affects versions, releases, or CRUD on project versions (list, get, create, update, release, unrelease, archive, unarchive, move, merge, delete).

List

# Default: unreleased versions in the project's native sequence (server order)
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py list PROJ

# Filter by status (released | unreleased | archived | all)
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py list PROJ --status released

# Paginated search with free-text query and explicit ordering
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py list PROJ \
    --status unreleased --query "1.4" --order-by releaseDate

# Machine-readable outputs
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py --json list PROJ
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py --quiet list PROJ

Get

# By numeric ID
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py get 10042

# By name (requires --project to disambiguate)
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py get "1.4.0" --project PROJ

# With fixed / affected / unresolved counts merged in
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py get 10042 --counts

Create

uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py create PROJ "1.4.0" \
    --release-date 2026-05-31 --description "Q2 2026 release"

# Full form with a start date and explicit released/archived flags
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py create PROJ "1.5.0" \
    --start-date 2026-06-01 --release-date 2026-06-30 --released --archived

# Preview the composed payload without hitting the API
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py create PROJ "1.4.0" \
    --release-date 2026-05-31 --dry-run

Update

# Any subset of fields; internally GET → merge → PUT to protect omitted fields
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py update 10042 \
    --description "Q2 2026 release (postponed)" --release-date 2026-06-07

# Renaming
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py update 10042 --name "1.4.0-rc2"

# Preview merged payload
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py update 10042 --name "1.4.0-rc2" --dry-run

Release / unrelease

# Mark released with a specific date
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py release 10042 --release-date 2026-05-31

# Omit --release-date to default to today
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py release 10042

# Roll back: sets released=false and explicitly clears releaseDate (null in payload)
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py unrelease 10042

Archive / unarchive

uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py archive 10039
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py unarchive 10039

Move

# After another version (IDs must be numeric; the script builds the
# `self` URL client-side from the configured Jira base URL before POSTing)
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py move 10045 --after 10042

# Relative position: First | Last | Earlier | Later
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py move 10042 --position First

Merge

# Preview: fetches relatedIssueCounts on the source and prints what would move
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py merge 10050 INTO 10042 --dry-run

# Execute: reassigns fixVersions/versions references, then deletes the source
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py merge 10050 INTO 10042

Delete

# Safe: reassign fix-version refs to another version before deleting
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py delete 10050 --move-fix-to 10042

# Reassign both fix and affects references
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py delete 10050 \
    --move-fix-to 10042 --move-affected-to 10042

# Preview (shows orphan counts when no --move-*-to is provided)
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-version.py delete 10050 --dry-run

Gotchas

• Plural field names only. On issues, use fixVersions (Fix Version/s) and versions (Affects Version/s). The singular forms fixVersion and version silently no-op on create and give a confusing "field does not exist on screen" error on update.
• Safe-merge update. update always performs GET → merge → PUT because some Jira deployments treat PUT as replace. Clearing a field (e.g. unrelease) emits an explicit null in the payload rather than omitting the key.
• 409 on duplicate names. Creating a version whose name already exists in the project returns HTTP 409; the script surfaces it as Version "X" already exists in PROJ.
• Orphaned references on delete. delete without --move-fix-to / --move-affected-to leaves dangling fixVersions / versions arrays on issues. Prefer --dry-run first to read the reassign counts.
• Numeric IDs only on mutating subcommands. update, release, unrelease, archive, unarchive, move, merge, delete validate that every positional and target version ID is numeric before any HTTP call, so values like ../../issue/KEY cannot reach the REST path. Look the version up by name (get NAME --project PROJ) first if you only have a name.
• Paginated endpoint fallback. --query / --order-by use the paginated /project/{key}/version endpoint (Jira Cloud + DC ≥9.x). On older DC the endpoint returns 404 and the script automatically retries the flat endpoint, applying --query substring filter and --order-by sort client-side.
• Archived still filterable. Archive only hides a version from pickers; JQL like fixVersion = "1.3.0" keeps matching archived versions.

See also

docs/plans/2026-04-20-versions-design.md for the full design trail.

Watchers

When to load

Load this reference whenever the user asks about watchers — listing, adding, removing, or auto-subscribing themselves or a stakeholder when an issue changes state. Watchers are not exposed anywhere else in the skill, so any "watch", "subscribe", "notify me on", "unsubscribe", or "who is watching" request should land here.

Commands

All commands are subcommands of jira-watchers.py. Global flags (--json, --quiet, --profile, --env-file, --debug) go before the subcommand.

list

# Default — header with count, one row per watcher
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-watchers.py list PROJ-123

# JSON — raw Jira response ({"watchCount", "isWatching", "watchers": [...]})
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-watchers.py --json list PROJ-123

# Quiet — one identifier per line
# DC prints usernames; Cloud prints accountIds (pipeline-friendly)
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-watchers.py --quiet list PROJ-123

add

# Self-subscribe (default — requires only Browse Projects)
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-watchers.py add PROJ-123

# Subscribe someone else (requires Manage Watchers permission)
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-watchers.py add PROJ-123 --user product.owner

# Cloud: pass an accountId directly to skip user-search
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-watchers.py add PROJ-123 --user 557058:d5765ebc-27de-4ce3-b520-a77a87e5e99a

# JSON output → {"key": "PROJ-123", "user": "asmith", "added": true}
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-watchers.py --json add PROJ-123

remove

# Un-watch yourself
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-watchers.py remove PROJ-123

# Remove someone else (requires Manage Watchers)
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-watchers.py remove PROJ-123 --user asmith

# Preview without calling the API
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-watchers.py remove PROJ-123 --user asmith --dry-run

# JSON output → {"key": "PROJ-123", "user": "asmith", "removed": true}
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-watchers.py --json remove PROJ-123

Bulk patterns (no server-side bulk endpoint)

# Watch every child of an epic
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-search.py --json query '"Epic Link" = PROJ-789' \
  | jq -r '.issues[].key' \
  | xargs -I{} uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-watchers.py add {}

Gotchas

• DC vs Cloud identity. DC uses usernames (jdoe); Cloud uses accountIds

(557058:...). The script auto-detects via client.cloud and resolve_assignee() — pass whatever identifier you have; account-id-shaped strings bypass user search.

• `issue_delete_watcher` library kwargs differ from raw REST params.

In atlassian-python-api, call issue_delete_watcher(..., username=...) on DC and issue_delete_watcher(..., account_id=...) on Cloud; the script chooses the correct kwarg based on deployment/identifier shape. If you ever drop to raw REST, the query parameter names are ?username= (DC) and ?accountId= (Cloud).

• Self-watch is idempotent. Adding yourself when already watching returns

HTTP 204, not an error — the script treats repeated self-adds as success.

• 403 on someone-else add/remove. Non-self watcher changes require the

Manage Watchers project permission. A 403 is surfaced verbatim as the error message — do not silently swallow.

• 404 on remove-non-watcher. Removing a user who is not currently watching

returns HTTP 404 on both DC and Cloud. The script surfaces this as a clean error (exit code 1), not a silent success.

See also

docs/plans/2026-04-20-watchers-design.md for the full design trail (REST shapes, DC vs Cloud matrix, out-of-scope items).

Worklogs — Advanced Logging and Cross-Cutting Queries

When to load

Load this reference whenever the user wants to log work with a custom start date/time, or query worklogs across multiple issues by date range, user, project, epic or sprint.

jira-worklog.py add — advanced flags

# Simplest — logs "now" against your account
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-worklog.py add PROJ-123 2h --comment "Work done"

# Explicit start time
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-worklog.py add PROJ-123 1h30m \
    --started "2026-04-20T14:00:00" --comment "Research session"

Time strings accept Nw Nd Nh Nm Ns combinations (Jira semantics, 8h workday).

jira-worklog-query.py — cross-cutting query

# Default: my worklogs for the current week
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-worklog-query.py

# By project with per-entry detail
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-worklog-query.py --project PROJ --detail

# By date range, JSON output
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-worklog-query.py \
    --from 2026-03-01 --to 2026-03-31 --json

# By epic or sprint
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-worklog-query.py --epic PROJ-1940
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-worklog-query.py --sprint 916

--detail shows individual worklog entries grouped by issue. Default output groups by issue with per-issue and grand totals. --json emits the raw worklog list — pipe to jq for custom reports.

Relative dates

--from and --to accept plain YYYY-MM-DD. For rolling queries, compute the dates in the shell:

uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-worklog-query.py \
    --from "$(date -d 'monday last week' -I)" --to "$(date -I)"