Jira Ticket

Style: Focus on conciseness in your output. Stay brief, but never sacrifice semantics (meaning) for conciseness.

Jira ticket

Produce or update Jira tickets with a consistent, per-type section structure, in German, written as real Markdown for a Jira MCP server.

Configuration

$JIRA_PROJECT_KEY is the Jira project key these tickets are created in. Resolve it before any write; if unset, ask the user once and offer to record it in their CLAUDE.md / AGENTS.md. The skill assumes a Jira MCP server that accepts Markdown directly (e.g. mcp-atlassian).

Quick start

• New ticket → pick the type, fill the matching template from references/templates.md, confirm, then jira_create_issue.
• Existing ticket → jira_get_issue to read its type and current body, propose a merged version, confirm, then jira_update_issue.

Ticket types & sections

One model: descending altitude with context inheritance. Every type starts with Kontext; each child's Kontext is the parent's forward-looking section made concrete. Requirements sharpen as altitude drops: Outcome → High-Level → (User Story + functional AC) → (Low-Level + technical AC).

Invariants:

• Be compact by default. Terse is the target, not the exception. Aim for 2–5 short bullets or 1–3 sentences per section; a Kontext is a short paragraph, not an essay. Length may scale up for genuinely multi-system work, but when in doubt, cut. Never pad to look complete, never restate the same point across sections, prefer one illustrative example over enumeration, and drop every optional section that isn't earning its place.
• Kontext is universal. Draft a child's Kontext from the parent's forward-looking section (Initiative Ziel → Epic Kontext, Epic Outcome → Capability Kontext, Capability High-Level-Anforderungen → Story/Task Kontext). Don't restate the parent — make it concrete for this level.
• Initiative is the root (no parent); it bundles epics toward one goal. Its time window lives in the Jira start/due date fields (mandatory — Plans renders the timeline from them), never in the description. Weekly status goes into a Jira comment, not the description.
• Story Acceptance Criteria are functional, testable German bullets (AC1:, AC2: …). Default to a plain checklist; use Given/When/Then only for criteria describing complex, multi-path workflows. Do not justify the checklist default on "scope control" grounds.
• Task Definition of Done is technical verification of the implementation against the parent ticket's requirement — not standalone, user-facing acceptance criteria.
• Bug tickets describe the problem, not the solution. Fehlerbild states observed behavior and known root-cause facts; Erwartetes Verhalten states the desired outcome, solution-open and verifiable. No implementation directives (no Low-Level-Anforderungen, no "umbauen zu X"). Agreed constraints on where a fix may or may not happen belong in Out of Scope, not in the requirements.
• Epic Outcome is purely qualitative — quantitative targets live, if anywhere, on the Initiative (Erfolgsmetriken, optional and only where a number naturally exists); never invent measurable targets on epics.
• Spike sits outside the altitude chain (like Bug): it produces knowledge, not functionality. Fragestellung must be binary-answerable; Timebox caps the effort; Ergebnis names where the answer flows (follow-up ticket, ADR, decision).
• Out of Scope is allowed on any type; it is mandatory on Capability.
• Parent: Epic → Initiative (optional); Capability → Epic; Story → Capability/Epic; Task → Capability/Epic/Story; Spike → optional.
• "Capability" here means a functional slice of an Epic — not the SAFe Capability (Large-Solution construct above Feature, spanning multiple ARTs). The Jira type names are fixed; this is a vocabulary clarification only.

Full templates with per-section guidance: references/templates.md.

Workflow

1. Mode — create or update. For update: jira_get_issue (issue_key, fields: "summary,description,issuetype,parent"), read the issue type and the current description.
2. Type — map the Jira issue type to Initiative/Epic/Capability/Story/Task/Bug/Spike. If the type is unknown or ambiguous, ask.
3. Parent — Initiative never has one; Bugs and Spikes often have none; Epics optionally parent to an Initiative. For everything else, ask for / confirm the parent key, fetch it if helpful, and derive this ticket's Kontext from the parent's forward-looking section (inheritance + traceability).
4. Draft — fill the matching template from references/templates.md, in German.
5. Confirm — show the proposed body and get explicit confirmation before any write (repo rule: explain the plan, get confirmation).
6. Write:
   • New: jira_create_issue — project_key: "$JIRA_PROJECT_KEY", summary, issue_type, description (the Markdown body). A parent goes into additional_fields: '{"parent": "PROJ-1234"}'.
   • Update: jira_update_issue — issue_key plus fields as a JSON string: '{"description": "## Kontext\n…"}'. Pass return_fields: "key" to keep the response small. Merge: preserve and refine existing content, add only the missing sections, never silently clobber. Flag anything you replace.

Formatting rules (critical)

The Jira MCP server (e.g. mcp-atlassian) takes real Markdown directly in description / body — no contentFormat flag, no cloudId:

• Headings ## / ###, **bold**, `code`, - or 1. lists, > block quotes.
• Never Jira wiki markup — no h2., no {{monospace}}, no _wiki-italic_. (This is the PROJ-317 failure mode: wiki markup renders literally.)
• In jira_update_issue the body is nested inside the fields JSON string, so escape newlines as \n.
• The same rules apply to comments via jira_add_comment (issue_key, body).

Out of scope (deliberate)

This skill owns structure + formatting only. It does not enforce your organisation's compliance checks (roles/permissions, audit logging, affected systems/APIs, NFRs, partner release note). When those matter, consult your own org-internal ticket guidelines.