/jira

description: Fetches a JIRA issue via a configured MCP server and distills it into a structured task file at docs/jira/<KEY>.md that downstream skills auto-detect. Analyzes the codebase to surface missing criteria, scope, and risks; optionally writes an analysis comment or implementation tickets back to JIRA after explicit confirmation. Re-runs reconcile the local file instead of regenerating. Guides MCP setup if none is configured.
disable-model-invocation: true
argument-hint: "[issue-key]"

JIRA Context

Fetch a JIRA issue, distill it into a structured task file, analyze the codebase against it, and optionally enrich the issue in JIRA. Works with any JIRA MCP server (Atlassian Rovo, sooperset/mcp-atlassian, or generic).

Safety

Steps 1–3.5 (including the refresh path) perform no MCP writes; local file writes are permitted. MCP writes are allowed only in Step 5 after explicit user confirmation. The **MCP Safety** section of `jira-context-extraction.md` is the single source of truth for which tools the skill may call and at which gate.

Language

Content written back to JIRA MUST stay in the issue's original language — never translate it to English. All local files (`docs/jira/*.md`) and all user-facing output are in English; translate as needed while distilling.

Step 1: Detect JIRA MCP Server

Read `$CLAUDE_PLUGIN_ROOT/skills/jira/references/jira-context-extraction.md` and follow its **Detection Procedure**. Server detected → record the server name and tool prefix, continue. None detected under Codex → stop and ask the user to configure a compatible JIRA MCP server in Codex, then re-run this skill; the bundled setup configures Claude Code only. Otherwise read `$CLAUDE_PLUGIN_ROOT/skills/jira/references/jira-setup.md` and follow it; if the user skips setup, stop.

Step 2: Find the Issue

If the user provided an issue key inline, validate it: the entire input must match `^[A-Z][A-Z0-9]+-\d+$` (e.g., `PROJ-123`). Ask for a corrected key if invalid, then continue to Step 3.

If no key was provided, ask the user (AskUserQuestion) whether to enter a key, search their assigned open issues, or browse by project:

• **Assigned issues** — JQL: `assignee = currentUser() AND resolution = Unresolved ORDER BY updated DESC`
• **By project** — ask for the project key and validate it against `^[A-Z][A-Z0-9]{1,9}$` before interpolating (JQL injection guard), then JQL: `project = {KEY} AND resolution = Unresolved ORDER BY updated DESC`

Present at most 10 results as a numbered list (`KEY — Summary [Type, Priority]`) and let the user pick.

Step 3: Fetch Issue Context

Follow the **Fetch Procedure** in `jira-context-extraction.md` (read in Step 1): issue details, linked issues and subtasks, recent comments, sprint context. Handle failures per its **Error Handling** table — on 401/403/404, report the specified message and stop.

Step 3.5: Detect Prior Run

If `docs/jira/<ISSUE-KEY>.md` exists at the project root, read `$CLAUDE_PLUGIN_ROOT/skills/jira/references/jira-refresh.md` and follow the **Refresh Procedure** instead of Step 4 — it owns its own routing on completion. Otherwise continue.

Step 4: Distill into Structured Task

Assemble the fetched data into the **Structured Output Format** from `jira-context-extraction.md` — the single source for section names. Omit sections with no data. If the issue's acceptance criteria use Given/When/Then phrasing, preserve it verbatim in each entry — `/optimus:brainstorm` reformats those into `### Scenario:` blocks.

Present the structured task and confirm with the user, iterating on requested adjustments. Then save it to `docs/jira/<ISSUE-KEY>.md` and report the path:

---
source: jira
issue: [ISSUE-KEY]
date: [YYYY-MM-DD]
description-refresh-date: [YYYY-MM-DD]
---

[The full structured task — Goal, Acceptance Criteria, Context, Key Decisions]

Step 5: Analyze Against Codebase

Read `$CLAUDE_PLUGIN_ROOT/skills/jira/references/jira-codebase-analysis.md` and follow the **Analysis Procedure** using the Goal and the ORIGINAL Acceptance Criteria from the task file (exclude items tagged `(from codebase analysis)` — prior enrichment, not source criteria). Present the **Impact Summary**.

Verify with `ToolSearch` that the detected server's add-comment tool named in the MCP Safety permitted-write table (`addCommentToJiraIssue` for Rovo, `jira_add_comment` for sooperset) is in the runtime tool list — do not probe for other comment-like tools. Then ask the user (AskUserQuestion) how to use the findings:

• **Update JIRA and local context** (offer only if the add-comment tool is available) — enrich the local file and post an analysis comment to JIRA
• **Update local context only** — enrich `docs/jira/<ISSUE-KEY>.md` only
• **Skip** — proceed without changes

On either update choice, run the **Task File Update** procedure first — the local file is the single source of truth. On the JIRA branch, then post the comment per the **JIRA Comment Format**, translated to the issue's original language if it isn't English; comments are append-only, so no further confirmation is needed. If the tool call fails at runtime, inform the user and keep the local update.

**Complex scope, JIRA branch only:** if the Scope Assessment is `Complex` and the user chose "Update JIRA and local context", read `$CLAUDE_PLUGIN_ROOT/skills/jira/references/jira-implementation-tickets.md` and follow it to optionally spawn implementation tickets — it has its own confirmation gate defaulting to no JIRA writes.

Step 6: Recommend Next Step

Route by issue type and the Step 5 Scope Assessment (fall back to acceptance-criteria count when inconclusive). If the user has no feature branch yet, also mention `/optimus:commit branch`. The recommended skill gathers its own context, so suggest a fresh conversation for it.

• **Tech debt / refactoring** (issue type, labels like `tech-debt`/`refactor`, or a goal that restructures code without changing behavior) → recommen