oprogramadorreal/skills/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 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]

3. 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.

2. 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 English, translate the derived content into the issue's original language before posting (see Language section above).

3. If the comment tool call fails at runtime (e.g., tool was listed but is unavailable), inform the user and skip the JIRA write — the local file update still applies.

4. Report success or failure. No further confirmation needed for the comment — comments are append-only and non-destructive.

5. Complex scope only — if the Scope Assessment from the Impact Summary is Complex, read $CLAUDE_PLUGIN_ROOT/skills/jira/references/jira-implementation-tickets.md and follow the Implementation Ticket Creation Procedure to optionally spawn implementation tickets. The procedure has its own confirmation gate; the default is to skip JIRA writes and emit a proposed list to the local file only. Then proceed to Step 6.

If Update local context only

Update the docs/jira/<ISSUE-KEY>.md file following the Task File Update procedure. Proceed to Step 6.

If Skip

Proceed to Step 6.

Step 6: Recommend Next Step

First, handle tech debt and refactoring tickets separately — they have a fixed route:

• Refactoring / Tech debt → "Recommend running /optimus:refactor to restructure the code. Tip: for best results, start a fresh conversation for the next skill — each skill gathers its own context from scratch."

For stories, features, and bugs, use the Scope Assessment from Step 5 as the primary complexity signal. When the scope assessment is inconclusive, supplement with the structured task's acceptance criteria count and context.

After giving the recommendation for any path above (including refactoring), also mention /optimus:branch if the user hasn't created a feature branch yet.

Simple (codebase assessment: simple, or 1–3 acceptance criteria with single component)

Recommend running /optimus:tdd to implement this test-first. It will auto-detect the task file at docs/jira/<ISSUE-KEY>.md. Tip: for best results, start a fresh conversation for the next skill — each skill gathers its own context from scratch.

Medium (codebase assessment: medium, or 4–6 acceptance criteria across 2–3 components)

This task has a few moving parts — recommend exploring the codebase in plan mode before implementing.

Use AskUserQuestion — header "Plan mode", question "Would you like a plan-mode prompt for this task? It will help you explore the codebase and plan the implementation before coding.":

• Generate prompt — "Create a ready-to-paste plan-mode prompt"
• Skip to TDD — "I'll go straight to /optimus:tdd"

If Generate prompt: assemble a self-contained plan-mode prompt pre-filled from the structured task (and codebase impact findings if available from Step 5):

```
## Goal
[Goal from the structured task]

## Context
[Acceptance criteria + context fields + key decisions from the structured task.
If Step 5 produced a codebase impact summary, include the Files Affected and
Risks sections here.]

## Starting Hints
- Task context: docs/jira/<ISSUE-KEY>.md
[If Step 5 ran, add key files identified in the impact summary]

## What to Figure Out
1. What approach best balances simplicity with the task's requirements? Consider at least 2 alternatives briefly before committing.
2. Which existing files and modules need to be modified or extended?
3. What's the right implementation sequence given the acceptance criteria?
4. Are there existing patterns in the codebase to follow or reuse?
5. What are the risks or edge cases not covered by the acceptance criteria?

## Plan Deliverable
The plan should include:
- Proposed approach with rationale
- Files to create or modify, with what changes
- Implementation sequence and dependencies
- Test strategy for each acceptance criterion

## Scope
- Focus on: [component/area from the structured task context]
- Out of scope: [anything explicitly excluded in the JIRA issue]

## How this conversation should run
Treat this conversation as a review loop — validate the plan against the actual codebase and iterate with me. When I say I'm done iterating, acknowledge but do not write yet — plan mode is read-only. I will then toggle plan mode off and send a short follow-up message (e.g. "go"). On that follow-up, append a `### Refined plan` section (heading exactly `### Refined plan`) to `docs/jira/<ISSUE-KEY>.md` to capture the refined plan, and stop. I will start a fresh conversation to run `/optimus:tdd`.
```

When emitting both the plan-mode prompt above and the execution prompt below, substitute <ISSUE-KEY> with the real key so each pasted block is self-contained.

Tell the user:

1. Start a fresh Claude Code conversation in plan mode (CLI: press Shift+Tab until the mode indicator shows plan mode; other clients: use the equivalent toggle). Paste the prompt above.
2. Iterate with Claude. Do not approve the plan — approval executes immediately and skips /optimus:tdd's Red-Green-Refactor discipline. When you're satisfied, tell Claude you're done iterating; Claude will acknowledge. Then toggle plan mode off using the same control and send a short follow-up message (e.g. "go") — Claude will append a ### Refined plan section to docs/jira/<ISSUE-KEY>.md in response.
3. Start a second fresh conversation and paste the execution prompt below.

Then emit the execution prompt as a second copyable block, pre-filled from the task file:

```
## Goal
Run `/optimus:tdd` to implement the refined plan in `docs/jira/<ISSUE-KEY>.md` test-first.

## Starting Hints
- JIRA task (with "Refined plan" section): docs/jira/<ISSUE-KEY>.md
- Acceptance criteria: [carry forward from the task file]

## Scope
- Focus on: [component/area from the structured task context]
- Out of scope: [anything explicitly excluded in the JIRA issue]
```

See $CLAUDE_PLUGIN_ROOT/references/skill-handoff.md for the full handoff convention and why plan mode is used review-only.

If Skip to TDD: Recommend running /optimus:tdd to implement this test-first. It will auto-detect the task file at docs/jira/<ISSUE-KEY>.md. Tip: for best results, start a fresh conversation for the next skill — each skill gathers its own context from scratch.

Complex (codebase assessment: complex, or 7+ acceptance criteria, multiple components, architecture/migration mentions, or unclear design direction)

This task needs design thinking before implementation. Recommend running /optimus:brainstorm to explore design approaches — it will auto-detect the task file at docs/jira/<ISSUE-KEY>.md.

Tell the user: Tip: for best results, start a fresh conversation for the next skill — each skill gathers its own context from scratch.