oprogramadorreal/optimus-claude / skills/jira
jira
VerifiedFetches 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.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 6.9 KB |
| SKILL.md | skill md | 6.3 KB |
| agents/openai.yaml | config | 198 B |
| references/jira-codebase-analysis.md | markdown | 6.9 KB |
| references/jira-context-extraction.md | markdown | 8.0 KB |
| references/jira-implementation-tickets.md | markdown | 6.3 KB |
| references/jira-refresh.md | markdown | 7.6 KB |
| references/jira-setup.md | markdown | 3.0 KB |
| references/plan-mode-prompt.md | markdown | 1.0 KB |
references/jira-context-extraction.md
View on GitHub# JIRA MCP: Detection, Safety, and Context Extraction
Server detection, tool name resolution, MCP safety rules, and the fetch/output procedure. Read by the jira skill at Step 1. The **MCP Safety** section is the single source of truth for which tools the skill may call and at which gate.
## Contents
1. [Detection Procedure](#detection-procedure)
2. [Tool Name Resolution](#tool-name-resolution)
3. [MCP Safety](#mcp-safety)
4. [Fetch Procedure](#fetch-procedure)
5. [Structured Output Format](#structured-output-format)
6. [Error Handling](#error-handling)
## Detection Procedure
1. **Find the tools:** look among your available tools for names in the table below or containing `jira`/`Jira`. If none match, query `ToolSearch` (when present) for `jira`, then `atlassian`.
2. **Tools found** → record the server name and tool prefix (`mcp__atlassian__` = Rovo, `mcp__mcp-atlassian__` = sooperset, anything else = generic) and report: `Detected: [server name] ([N] JIRA tools available)`. **No tools found** → the skill routes to `jira-setup.md`.
## Tool Name Resolution
Discover tools at runtime as in the [Detection Procedure](#detection-procedure) — never hard-code assumptions.
**Tools the skill calls, by server:**
| Operation | Rovo (`mcp__atlassian__`) | sooperset (`mcp__mcp-atlassian__`) | Safety |
|-----------|--------------------------|-----------------------------------|--------|
| Search issues (JQL) | `searchJiraIssuesUsingJql` | `jira_search` | Read |
| Get single issue | `getJiraIssue` | `jira_get_issue` | Read |
| Get link types | `getIssueLinkTypes` | `jira_get_link_types` | Read |
| Resolve site (cloudId) | `getAccessibleAtlassianResources` | — | Read |
| Create issue | `createJiraIssue` | `jira_create_issue` | **Write** |
| Add comment | `addCommentToJiraIssue` | `jira_add_comment` | **Write** |
| Create link | `createIssueLink` | `jira_create_issue_link` | **Write** |
When a **Read** tool is unavailable, fall back to the search tool with targeted JQL (e.g., `key = PROJ-123` when the get-issue tool is missing). Write operations have no fallback — if the specified write tool is unavailable, inform the user and skip the write.
**Generic servers** (detection matched neither Rovo nor sooperset): map each **Read** operation by tool-name pattern among the tools the Detection Procedure found. Treat all writes as unavailable unless a discovered tool's name unambiguously matches one of the permitted purposes in the [MCP Safety](#mcp-safety) table (add comment, create issue, create link) — when in doubt, fail closed and skip the write.
## MCP Safety
During context extraction (Steps 1–3.5 of the jira skill, including the refresh path), only call tools marked **Read** in the table above.
**Hard rule:** NEVER call any tool whose name, after any server prefix such as `jira_`, **starts with** `add`, `create`, `edit`, `update`, `transition`, or `delete` during context extraction (e.g., `addCommentToJiraIssue`, `jira_add_comment`, `editJiraIssue`, `jira_update_issue`).
**Comments:** comments are embedded in the get-issue response or in search results — there is no dedicated "get comments" tool. Do NOT use `addCommentToJiraIssue` to read comments; it is a write tool that creates a new comment on the issue.
Write tools are only permitted in Step 5 of the jira skill, after explicit user confirmation. The full set of writes the skill is allowed to call:
| Tool (Rovo / sooperset) | Purpose | Gate |
|------------------------|---------|------|
| `addCommentToJiraIssue` / `jira_add_comment` | Post the analysis comment | Step 5 user confirmation |
| `createJiraIssue` / `jira_create_issue` | Spawn implementation tickets | Step 5 user confirmation + ticket-creation confirmation gate (default Skip), Complex scope only |
| `createIssueLink` / `jira_create_issue_link` | Link new implementation tickets to the parent (best-effort) | Same gates as `createJiraIssue` |
All other write tools (`editJiraIssue`, `jira_update_issue`, `transitionJiraIssue`, `jira_transition_issue`, `addWorklogToJiraIssue`, `jira_add_worklog`, deletes, etc.) are forbidden by this skill regardless of branch.
## Fetch Procedure
Given an issue key, fetch in this order. If an optional field fails or returns empty, skip it silently — never fail on optional fields.
1. **Issue details** — get-single-issue tool (`getJiraIssue` / `jira_get_issue`). Capture summary, description, issue type, status, priority, assignee, sprint, epic/parent, and labels.
2. **Linked issues and subtasks** — from the issue details: link type + key + summary per linked issue; subtasks listed separately.
3. **Comments** — the last 10, from the issue data already fetched in step 1 (embedded — make no separate MCP call). Record author, relative date, and body.
4. **Sprint context** — if the issue has a sprint: record the sprint name and goal, then fetch sibling issues (keys + summaries) with JQL `sprint = {SPRINT_ID} AND key != {KEY} ORDER BY rank ASC`, where `{SPRINT_ID}` is the id of the issue's current (latest) sprint. Skip entirely if sprint data is unavailable.
**Truncation limits:**
| Field | Limit |
|-------|-------|
| Description | 2000 characters (append "(truncated)" if truncated) |
| Comments | Max 10 comments, total text capped at 2000 characters (append "(older comments omitted)" if truncated) |
| Sprint siblings | Max 15 issues, keys + summaries only |
| Linked issues | Max 10 |
| Subtasks | Max 10 |
## Structured Output Format
After fetching, assemble the data into this format:
```
## Task: [Issue Key] — [Summary]
### Goal
[Single-sentence distilled goal — synthesized from the summary and description.
For bugs: "Fix [symptom] in [component]." For stories: "Implement [capability]
for [user/system]." For tasks: "Complete [action] for [purpose]."]
### Acceptance Criteria
[Extract from the description if structured criteria exist (numbered lists,
checkbox lists, "Given/When/Then" blocks). If the description has no explicit
criteria, infer 3–5 testable criteria from the description and linked context.
Present as a numbered list.]
### Context
- Type: [Issue type]
- Status: [Current status]
- Priority: [Priority]
- Assignee: [Name]
- Sprint: [Sprint name — sprint goal, if available]
- Parent: [Epic key — Epic summary, if applicable]
- Labels: [Comma-separated labels, if any]
- Linked issues: [KEY — summary (link type), for each. Omit if none.]
- Subtasks: [KEY — summary (status), for each. Omit if none.]
- Related sprint work: [KEY — summary, for sibling issues that may interact
with this task. Omit if no sprint context or no relevant siblings.]
### Key Decisions (from comments)
[Distill decisions, clarifications, or context from comments that would affect
implementation. Ignore routine status updates, @mentions without substance,
and automated comments. If no meaningful decisions found, omit this section.]
```
## Error Handling
| Error | User-facing message |
|-------|---------------------|
| 401 Unauthorized | "Your JIRA authentication has expired. For Rovo: re-authenticate the server (Claude Code: run `/mcp` and re-authenticate it; Codex: `codex mcp login <server>`; elsewhere: the host's MCP connection settings). For mcp-atlassian: verify your API token has not expired at id.atlassian.com/manage-profile/security/api-tokens and update your MCP configuration." |
| 403 Forbidden | "You don't have permission to view {KEY}. Check your JIRA project access with your JIRA admin." |
| 404 Not Found | "Issue {KEY} not found. Verify the key is correct (format: PROJECT-NUMBER) and that you have access to the project." |
| 429 Rate Limited | Retry once after 2 seconds. If still rate limited: "JIRA rate limit reached. Wait a moment and try `/optimus:jira {KEY}` again." |
| MCP tool error | "The JIRA MCP tool returned an error: {error message}. This may be a server configuration issue — in Claude Code, verify the MCP server is running with `claude mcp list`; in Codex, check its own MCP configuration." |
| Empty response | "The JIRA server returned no data for {KEY}. The issue may exist but have restricted visibility." |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |