optimus-claude

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 if it doesn't exist
2. Write the structured task to docs/jira/<ISSUE-KEY>.md (e.g., docs/jira/AUTH-456.md) with YAML frontmatter:

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

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

1. Report the file path: "Task context saved to docs/jira/<ISSUE-KEY>.md"

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 docs/jira/<ISSUE-KEY>.md (exclude items tagged (from codebase analysis) — those are prior enrichment, not source criteria).

Present the Impact Summary to the user.

Check whether the detected MCP server has a comment tool (see Tool Name Resolution table in jira-context-extraction.md). If no comment tool is available, present only "Update local context only" and "Skip". Otherwise, present all three options. Use AskUserQuestion — header "Codebase impact", question "How would you like to use these findings?":

• Update JIRA and local context (only if a comment tool is available) — "Enrich docs/jira/<ISSUE-KEY>.md and post an analysis comment to the JIRA issue"
• Update local context only — "Enrich docs/jira/<ISSUE-KEY>.md only"
• Skip — "Proceed without changes"

If Update JIRA and local context

1. Update the docs/jira/<ISSUE-KEY>.md file following the Task File Update procedure in the reference. The local file is always updated first — it is the single source of truth.

1. Post a structured JIRA comment using the add-comment tool from the Tool Name Resolution table in jira-context-extraction.md (addCommentToJiraIssue for Rovo). Derive the comment content from the sections just written to the local file, following the JIRA Comment Format in jira-codebase-analysis.md. If the JIRA issue is not in Englis