jira

# JIRA Context

Fetch a JIRA issue, distill it into a structured task for Claude Code, analyze the codebase to surface missing criteria, scope, and risks, and optionally enrich the issue in JIRA. The skill works with any JIRA MCP server (Atlassian Rovo or community servers like sooperset/mcp-atlassian) and guides first-time setup when no server is configured.

## Safety

Steps 1–3.5 perform no MCP writes. Local file writes (e.g., the refresh path's updates to `docs/jira/<KEY>.md`) are permitted; MCP writes are only allowed in Step 5 after explicit user confirmation. See `jira-context-extraction.md` "MCP Safety" for the full permitted-write table — that reference is the single source of truth for which tools the skill is allowed to call and at which gate.

## Language

All content written back to JIRA (comments) MUST preserve the original language used in the JIRA issue. Do not translate JIRA content into English when writing to JIRA.

All local artifacts (`docs/jira/*.md`) and all Claude Code output to the user MUST be in English, regardless of the source language. Translate as needed when distilling the structured task and producing local files.

## Step 1: Detect JIRA MCP Server

Read `$CLAUDE_PLUGIN_ROOT/skills/jira/references/jira-mcp-detection.md` and follow the **Detection Procedure**.

- **Server detected** → record `jira-server-name` and tool prefix, proceed to Step 2
- **No server detected** → follow the **Guided Setup Procedure** in the same reference. If setup completes successfully, proceed to Step 2. If the user skips setup, stop

## Step 2: Find the Issue

Two modes based on whether the user provided an issue key inline.

### Direct fetch

If the user provided an issue key inline (e.g., `/optimus:jira PROJ-123`):
1. Validate format — must match `^[A-Z][A-Z0-9]+-\d+$` (entire input, no extra characters — e.g., `PROJ-123`, `AB-1`)
2. If valid → proceed to Step 3 with this key
3. If invalid → inform the user and use `AskUserQuestion` to request a corrected key

### Search mode

If no issue key was provided (e.g., `/optimus:jira` with no argument), use `AskUserQuestion` — header "Find issue", question "How would you like to find your JIRA issue?":
- **Enter issue key** — "I know the key (e.g., PROJ-123)"
- **My open issues** — "Search my assigned open issues"
- **Search by project** — "List recent issues in a specific project"

**Enter issue key:** Use `AskUserQuestion` — header "Issue key", question "Enter the JIRA issue key:". Validate and proceed to Step 3.

**My open issues:** Read `$CLAUDE_PLUGIN_ROOT/skills/jira/references/jira-context-extraction.md`, section **Search: Assigned Issues**. Execute the JQL search, present results as a numbered list (max 10). Use `AskUserQuestion` — header "Select issue", question "Which issue are you working on?" with each issue as an option (label: `KEY — Summary`, description: `[Type, Priority]`). Proceed to Step 3 with the selected key.

**Search by project:** Use `AskUserQuestion` — header "Project", question "Enter the JIRA project key (e.g., PROJ):". Execute the project search from the extraction reference. Present results and let the user pick, same as above. Proceed to Step 3 with the selected key.

## Step 3: Fetch Issue Context

Read `$CLAUDE_PLUGIN_ROOT/skills/jira/references/jira-context-extraction.md` and follow the **Fetch Procedure** for the selected issue key:

1. Fetch issue details (summary, description, type, status, priority, assignee, sprint, parent/epic)
2. Fetch linked issues and subtasks (keys + summaries only)
3. Fetch recent comments (last 10, truncated to 2000 characters total)
4. Fetch sprint context (sprint name, goal, sibling issues)

Handle errors according to the **Error Handling** table in the reference. If a critical error occurs (401, 403, 404), report it to the user with the specified message and stop.

## Step 3.5: Detect Prior Run

Check whether `docs/jira/<ISSUE-KEY>.md` exists at the project root.

- **File does not exist** → first run for this issue. Continue to Step 4 unchanged.
- **File exists** → read `$CLAUDE_PLUGIN_ROOT/skills/jira/references/jira-refresh.md` and follow the **Refresh Procedure**. Do NOT continue to Step 4 — the refresh procedure owns its own routing on completion.

## Step 4: Distill into Structured Task

Assemble the fetched data into the **Structured Output Format** from the extraction reference:

```
## Task: [Issue Key] — [Summary]

### Goal
[Single-sentence distilled goal]

### Acceptance Criteria
[Extracted or inferred acceptance criteria as a numbered list]

### Context
- Type: [Issue type]
- Status: [Current status]
- Priority: [Priority]
- Assignee: [Name]
- Sprint: [Sprint name — sprint goal]
- Parent: [Epic key — Epic summary]
- Linked issues: [KEY — summary (link type)]
- Subtasks: [KEY — summary (status)]
- Related sprint work: [Sibling issues in the same sprint]

### Key Decisions (from comments)
[Distilled decisions and context from comments]
```

Omit sections that have no data (e.g., no sprint, no linked issues, no comments with decisions).

If the original JIRA issue uses Given/When/Then phrasing in its acceptance criteria, preserve that phrasing verbatim in each Acceptance Criteria entry — `/optimus:brainstorm` can then reformat each entry into a `### Scenario:` block in its Scenarios section.

Present the structured task to the user. Use `AskUserQuestion` — header "Task review", question "Does this capture the task correctly?":
- **Looks good** — "Use this task description"
- **Adjust** — "I want to refine before continuing"

If "Adjust": use `AskUserQuestion` — header "Refinement", question "What would you like to change?" (free text). Apply the changes and present the updated version. Re-confirm.

### Save task context to file

After the user confirms the structured task, save it to a persistent file so downstream skills (`/optimus:tdd`, `/optimus:brainstorm`) can auto-detect it without copy-paste.

1. Create the `docs/jira/` directory at the project root i