# Jira Ticket

> Write or update Jira tickets (Initiative, Epic, Capability, Story, Task, Bug, Spike) in a consistent German section structure with correct Markdown for a Jira MCP server. Use when the user wants to create, write, refine, or restructure an Initiative/Epic/Capability/Story/Task/Bug/Spike, or fix Jira ticket formatting.

- Skill: `jo-bity/jira-ticket` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jo-bity/jira-ticket`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jo-bity/jira-ticket/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Jo-bity (https://skillmd.com/u/jo-bity)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jo-bity/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](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).

| Type | Plane | Sections (in order) |
|------|-------|---------------------|
| **Initiative** | Portfolio — *Wozu + bis wann* | `Kontext`, `Ziel`, *(opt.)* `Erfolgsmetriken`, *(opt.)* `Out of Scope` |
| **Epic** | Strategy — *Warum + Wohin* | `Kontext`, `Outcome`, *(opt.)* `Out of Scope` |
| **Capability** | Solution-shape — *Was, im Rahmen* | `Kontext`, `High-Level-Anforderungen`, `Out of Scope` |
| **Story** | User requirement — *Was für den Nutzer* | `Kontext`, `User Story`, `Acceptance Criteria`, *(opt.)* `Out of Scope` |
| **Task** | Implementation — *Wie, verifizierbar* | `Kontext`, `Low-Level-Anforderungen`, `Definition of Done`, *(opt.)* `Out of Scope` |
| **Bug** | Problem — *Was ist kaputt* | `Kontext`, `Fehlerbild`, `Erwartetes Verhalten`, *(opt.)* `Out of Scope` |
| **Spike** | Erkenntnis — *Was wissen wir nicht* | `Kontext`, `Fragestellung`, `Timebox`, `Ergebnis` |

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](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](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.