oprogramadorreal/optimus-claude/jira

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 → 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 (as a faithful English translation if the issue isn't in English) — /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. Present the Impact Summary.

Verify 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 available, found as in the Detection Procedure — 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; 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 Scope Assessment — this run's Step 5, else the task file's ### Scope Assessment (fall back to acceptance-criteria count when absent or inconclusive). Pass the task to the recommended skill explicitly, as below, and 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) → recommend /optimus:refactor "<scope>", the scope drawn from the Goal and Codebase Impact — refactor does not read docs/jira/.
• Simple (assessment simple, or 1–3 criteria in a single component) → recommend /optimus:tdd docs/jira/<ISSUE-KEY>.md.
• Complex (assessment complex, or 7+ criteria, multiple components, architecture/migration concerns, unclear design) → recommend /optimus:brainstorm <ISSUE-KEY>.
• Medium (between the two) → offer a plan-mode prompt: read $CLAUDE_PLUGIN_ROOT/skills/jira/references/plan-mode-prompt.md and follow it. If the user declines, recommend /optimus:tdd as for Simple.