Jira Create Issues

Jira: Create Epics, Features, and Sprint Issues (mcp-atlassian)

This skill governs how the agent creates Jira issues through the user-mcp-atlassian MCP server against a self-hosted Jira Data Center instance. It enforces a stricter mandatory field set than Jira's screens require and the organisation's three-dimension governance model.

Initiative → Epic/Feature → Sprint-Issue Hierarchy

This project uses a multi-level hierarchy:

1. Initiative — top-level parent. Carries the WBS root number with a pillar prefix (e.g. 0.0 OPS: Operational Tasks & General Work, 1.0 DCM: Knowledge Graph Platform).
2. Epic / Feature — children of the Initiative and peers at the same hierarchy level. They share the same X.Y WBS sequence.
3. Story / Task / Test / Defect — sprint-level delivery issues under an Epic or Feature. Inherit X.Y.Z.
4. Sub-task — granular work items under Story/Task/Test/Defect.

Epic vs Feature decision rule

• Use Feature when the scoped deliverable should close within roughly one quarter (typically <= 2 months).
• Use Epic when work is broad, exploratory, or expected to run across multiple quarters.
• If unclear, default to Feature and note the assumption in the proposal for user confirmation.

Initiative Pillar Prefixes

Initiatives are numbered and prefixed by pillar:

Initiative Gating Rule

An Initiative requires 3+ Epics and a 3+ month timeline. Work that doesn't meet this threshold should be modelled as Epics under an existing Initiative, not as new Initiatives. Single-deliverable items (e.g. "Construct Cursor Rules", "Reaching out to stakeholder") must be demoted to Epic.

Three Orthogonal Dimensions

The core principle: pillars, teams, and products are three different things. Use three separate Jira mechanisms — never overload one to encode the others:

Components — Pillars Only (8 Total)

Components map directly to the governance model pillars. Every issue MUST have at least one component. Cross-pillar work gets multiple components.

Choosing the right component(s)

• If the work belongs to one pillar, set that single component.
• If the work is cross-pillar (e.g. a model routing epic touching Reasoning & Orchestration + Runtime), set both components.
• If the work is HiVE platform integration contributed by a specific pillar, set both the pillar component and HiVE Platform.
• If unsure, ask the user. Use jira_get_project_components to verify component names.

Labels — Teams and Products

Labels encode who is doing the work and what product it serves. Every issue MUST have at least one team:* label. Product/BU labels are required for issues serving specific BU projects.

Team labels (team:*)

Team inference rule notes:

• If work is for Tianxi, default to team:ro-prc-p unless the user explicitly specifies another Tianxi team.
• For Reasoning & Orchestration component work, pick an team:ro-* label (do not map to non-RO teams).

Product / BU labels (product:*, bu:*)

Special labels

Cross-Pillar Work Rules

Structural long-term exceptions (Qira, Tianxi, Enterprise AI)

BU projects that span multiple pillars by design:

• Get a BU- prefixed Initiative.
• Get product:* / bu:* labels on every issue.
• Get multiple pillar components on each issue.

Temporary exceptions (time-bound cross-pillar support)

• Issues go in the lending pillar's Initiative.
• Add label cross-pillar + the supporting pillar's component.
• Include an explicit end date in the epic description.

HiVE platform contributions (all pillars contribute)

• Component: the pillar that owns the capability + HiVE Platform.
• Label: product:hive.
• Initiative: under the pillar's Initiative (not HIVE-9.0) unless it is HiVE core team work.

Mandatory fields (always)

Every issue created by this skill MUST include ALL of the following fields, regardless of whether Jira marks them as required. Never skip these. If the user hasn't provided content for one of them, generate sensible defaults or ask the user — do NOT create issues with blank mandatory fields.

For sprint-level issues (Story/Task/Test/Defect)

For Epics

Epics do NOT get an Epic Link field (they are the epic). Instead, Epics require:

Note: Estimate is optional on Epics (story points usually live on child Stories).

For Features

Features are peers of Epics under an Initiative and follow the same approval/workflow expectations.

Field Guidelines

Summary: Every summary MUST begin with a WBS (Work Breakdown Structure) number that reflects the issue's position in the hierarchy. The WBS number is followed by a space and the title text. Stories should use the format "[WBS] [verb] [object] [context]".

Description: Markdown body explaining what the issue is about, why it matters, and any relevant context. For stories, include a brief user-story format ("As a [role], I want [goal], so that [benefit]") when appropriate. DoR and DoD must always be embedded in the description body under ## Definition of Ready and ## Definition of Done headings.

Epic Link (epicKey or customfield_10006): Only on stories/tasks — set to the epic key. Not used on the epic itself.

Estimate (customfield_10816): Story points. Always pass this as a string (e.g. "0.5", "1", "3", "5", "8", "13") — this Jira DC rejects a numeric value at create/update time with Operation value must be a string. If the user doesn't provide estimates, ask or make reasonable suggestions based on apparent complexity.

Component/s: The Jira component(s) this issue belongs to — must be from the 8-pillar list. Use jira_get_project_components to verify valid component names if needed.

Labels: Must include at least one team:* label. Add product:* / bu:* labels for BU-specific work. See Labels — Teams and Products.

Function area (customfield_16400): Auto-derived from Components — see Function area mapping. Always include this field.

Business Value (customfield_11491 in additional_fields AND ## Business Value section in description): Always set both, same treatment as AC/DoR/DoD. 1–3 sentences on why this work matters — what risk it reduces, what outcome/metric it improves, or who benefits. Generate sensible, issue-specific content if the user hasn't supplied it; never leave it blank. customfield_11491 has been confirmed rejected on the Task screen (Field 'customfield_11491' cannot be set. It is not on the appropriate screen, or unknown.) — attempt it anyway via additional_fields, and if Jira rejects it, drop that one field silently and rely on the description section (same fallback pattern as DoR/DoD). Example:

Reduces manual reconciliation effort by ~2 hours/week for the TPM team and removes a recurring source of stale dashboard data reported by stakeholders.

Acceptance Criteria (customfield_10515 in additional_fields AND ## Acceptance Criteria section in description): Always set both. A bullet list of testable conditions that must be true for the issue to be considered accepted. Write these in "Given/When/Then" or simple checkbox format. Example:

- [ ] User can authenticate via OAuth2
- [ ] Existing sessions are migrated without data loss
- [ ] Error responses follow the standard API format

Definition of Ready (customfield_16516 AND embedded in description under ## Definition of Ready): Conditions that must be met before work can begin. Always set both the custom field and the description section. Generate sensible defaults if not provided:

- [ ] Requirements are clearly defined
- [ ] Acceptance criteria are documented
- [ ] Dependencies are identified
- [ ] Design/technical approach is agreed upon

Definition of Done (customfield_16544 AND embedded in description under ## Definition of Done): Conditions that must be met for the work to be considered complete. Always set both the custom field and the description section. Generate sensible defaults if not provided:

- [ ] Code is written and peer-reviewed
- [ ] Unit tests are passing
- [ ] Documentation is updated
- [ ] QA testing is complete
- [ ] Deployed to staging and verified

Screen availability — where fields are accepted by Jira

Not all mandatory fields are on all screen schemes. Based on testing:

Rule: AC (customfield_10515), DoR (customfield_16516), DoD (customfield_16544), and Business Value (customfield_11491) must always be embedded as sections in the description body (## Acceptance Criteria, ## Definition of Ready, ## Definition of Done, ## Business Value). AC, DoR, and DoD should also be attempted as native custom fields via additional_fields on Story/Task screens — all three are confirmed accepted there (tested 2026-07-09 by directly setting them on LATC-5309, a Task). Business Value has been rejected on Task and is unconfirmed elsewhere — attempt it regardless, and if Jira returns a screen error for that field specifically, drop only that field and keep creating. On Epic screens, none of the four have been confirmed available — embed in description only there unless re-tested. Omitting the description section for any of the four is never acceptable, regardless of whether the custom field succeeds.

How Epics link to Initiatives

Epics are linked to their parent Initiative via two mechanisms — both must be set:

1. Parent Link custom field (customfield_12913) — set on the Epic at create time so portfolio scans work.
2. GANTT hierarchy link — after creating the Epic, call jira_create_issue_link:

type_name: "multi-level hierarchy [GANTT]"
inward_issue_key:  "<EPIC-KEY>"        # the child
outward_issue_key: "<INITIATIVE-KEY>"  # the parent

This makes the Initiative "is parent task of" the Epic.

WBS numbering

Every issue carries a Work Breakdown Structure prefix at the front of both the Summary and (for Epics) the Epic Name:

Format rules

• Single space between the WBS number and the title text.
• Zero-padding is not used (0.10, never 0.010).
• Initiatives are not created by this skill; their prefix is read, not assigned. If an Initiative has no prefix, stop and ask the user to add one.
• The same WBS string goes into both summary and (for Epics) customfield_10005 (Epic Name).

WBS Number Derivation (CRITICAL — Always Required)

NEVER invent or guess WBS numbers. Before assigning a WBS number to any new issue, you MUST:

1. Fetch the parent using jira_get_issue to get its summary and extract the WBS prefix.

   • For an Epic under an Initiative: extract the root number (e.g., 0 from "0.0 OPS: Operational Tasks")
   • For a Story under an Epic: extract the Epic's full prefix (e.g., 0.4 from "0.4 Data and Infra Ops Tasks")

2. Scan existing children to find all existing WBS numbers at that level:

   • For Epics: run project = <PROJ> AND "Parent Link" = <INIT> AND issuetype = Epic
   • For Stories/Tasks: run project = <PROJ> AND "Epic Link" = <EPIC> AND issuetype in (Story, Task)

3. Parse WBS prefixes from each child's summary and collect the numbers at the relevant level.

4. Determine the next available number — find the highest existing number and increment by 1.

   • For example, if children are 0.1, 0.2, 0.4, the next available is 0.5
   • DO NOT fill gaps (like 0.3 in this example) — gaps may be intentional

5. For batch creates, allocate consecutive numbers starting at the next free slot: 0.5, 0.6, 0.7, etc.

6. Report to the user before creating: "Initiative <INIT> is X.0. Existing Epics: <list>. Next Epic will be X.<nextY>. Confirm?"

7. Flag non-conforming siblings (e.g., issues without WBS prefixes) for the user to review later.

Computing the next number

Creating an Epic or Feature under Initiative <INIT>:

1. Run jira_get_issue on <INIT> and extract the leading X.0 from summary. Call this X.
2. List children at level X.Y (both Epics and Features):

   project = <PROJ> AND "Parent Link" = <INIT> AND issuetype in (Epic, Feature)
   

3. Parse the leading X.Y prefix from each child summary. Collect the Y values (Epic+Feature share one sequence).
4. Next Y = max(Y) + 1, floor of 1 if set is empty.
5. Show the user: "Initiative <INIT> is X.0. Existing Epics: <list>. Next Epic will be X.<nextY>. Confirm?"
6. Flag any siblings that don't match the X.Y pattern (e.g. LATC-1980) for the user to decide whether to renumber later.

Creating a Story/Task under Epic <EPIC>:

1. Run jira_get_issue on <EPIC> and extract the leading X.Y from summary.
2. List children:

   project = <PROJ> AND "Epic Link" = <EPIC> AND issuetype in (Story, Task)
   

3. Parse the leading X.Y.Z prefix from each child summary. Collect the Z values.
4. Next Z = max(Z) + 1, floor of 1 if set is empty.
5. Show the user the list and chosen number before creating.
6. If the Epic has un-numbered legacy children, do not back-fill them. Start X.Y.1 for the new one and warn the user.

Batch creates:

Allocate consecutive numbers starting at the next free slot. Example: if the highest existing Epic under LATC-7 is 0.4, a batch of 3 new Epics gets 0.5, 0.6, 0.7. Show the full numbered list before creating.

Worked example: LATC-7 (0.0 Operational Tasks & General Work)

Highest conforming Y = 4. Next Epic under LATC-7 would be 0.5 <title>. Surface LATC-1980 to the user as a follow-up to renumber.

Function area mapping

customfield_16400 ("Function area") must be included in every new issue where the Jira screen supports it. Always derive it automatically from the Components field — do not ask the user.

Resolution rules when an issue has multiple components:

1. If all components point to the same pillar → use that pillar.
2. If components span multiple pillars → use the pillar of the most specific / primary component and note the assumption in the draft. Ask the user if genuinely ambiguous.
3. If both Operations & Infrastructure and Operations (Non-Tech) are set → use Operations.
4. If HiVE Platform is combined with a domain pillar → use the domain pillar's function area (the HiVE component is captured via labels and components; Function area reflects the primary domain).

Always show the resolved pillar in the pre-create draft so the user can override before confirmation.

If the field is rejected at create time ("Field 'customfield_16400' cannot be set. It is not on the appropriate screen"): omit it, note the omission in the creation report, and advise the user that a Jira admin needs to add the field to that issue type's screen.

The value is a free-text string — use the exact pillar names from the table above, including punctuation (Data, Context, & Memory).

Operating contract

1. Never silently omit a mandatory field. If a value is missing, draft a placeholder from conversation context and present the full draft to the user for confirmation before calling jira_create_issue. Mark uncertain content as TBD: <what's needed>.
2. Always show the proposed payload before creating. Single create AND batch create. Show every mandatory field filled, then explicitly ask "Create this now?" Wait for an affirmative reply. No exceptions.
3. Always inherit a WBS prefix from the parent. Every Epic and Story summary MUST start with the WBS number computed from its parent's prefix and the next free sibling slot. If the parent has no WBS prefix, stop and tell the user — do not invent one.
4. Never assume the project key. Ask if not stated. The MCP tool's regex enforces ^[A-Z][A-Z0-9_]+$.
5. Never assume Epic Link. If the user says "create stories under Epic X" without a key, search first and ask which one.
6. Use the MCP server, not raw REST. All operations go through user-mcp-atlassian tools.
7. Never use components outside the 8-pillar list. Old sub-component names (e.g. "RAG", "Agentic Framework", "AI Agent Runtime") are retired. If the user uses old names, map them to the correct pillar component and confirm with the user.
8. HARD STOP — DoR, DoD, AC, and Business Value are always required, never optional. Every Epic, Story, and Task MUST include all four sections in the description body before the issue is created. There are no exceptions — not for simple tasks, not for tasks without explicit user input. If the user has not provided content for these fields, generate sensible, task-specific content based on context. A blank or placeholder-only DoR/DoD/AC/Business Value is not acceptable. This rule overrides any user instruction to "keep it simple" or "just create the ticket". The proposal shown in Step 2 MUST display the filled DoR, DoD, AC, and Business Value content so the user can review them before creation.

Pre-flight checks (run before creating)

Run only the checks relevant to what's missing or ambiguous. Skip ones already verified in this conversation.

• Resolve parent key: if the user gave a name instead of a key, run jira_search with JQL like project = <KEY> AND issuetype in (Initiative, Epic, Feature) AND (summary ~ "<query>" OR "Epic Name" ~ "<query>") and confirm.
• Read parent prefix: run jira_get_issue on the parent and extract the leading WBS prefix (X.0 for Initiative, X.Y for Epic). If absent, stop.
• Scan siblings for WBS: run the JQL in Computing the next number and parse prefixes. Report the chosen next number and any non-conforming siblings.
• Validate components: run jira_get_project_components with project_key. Only accept names from the 8-pillar list. If the user requests an unlisted component, tell them it must be created in Jira UI by an admin first.
• Confirm issue type exists: Epic, Feature, Story, Task, Test, and Defect are expected. If the project uses custom variants, confirm via jira_get_issue on a recent same-type issue first.

Workflow

Step 1 — Gather Information

Before creating anything, confirm or collect:

1. Project key — e.g. LATC. Ask if unknown.
2. Parent Initiative or Epic — the parent issue key that these issues will live under. Ask if unknown.
3. Issue summaries — the titles/names for each issue (without WBS prefix — that will be computed).
4. Issue descriptions — what the work is about and why it matters.
5. Component(s) — which pillar component(s) from the 8-pillar list. Ask if unknown.
6. Labels — which team(s) and product(s). At least one team:* label is required.
7. Estimates — story point estimates for each issue.
8. Assignee (optional) — who should own the issues.
9. Priority (optional) — any extra metadata.

If the user gives you a high-level feature description and asks you to break it down, generate 3–8 stories that decompose the work into concrete, actionable tasks. Each story should be small enough for one sprint and have a clear definition of done. Generate all mandatory field content for each story (acceptance criteria, DoR, DoD, estimate).

Step 2 — Present Proposal for Approval (MANDATORY)

NEVER create tickets directly. ALWAYS present a proposal first and wait for the user to approve it before creating anything in Jira.

After gathering information and computing WBS numbers, present the full plan as a formatted table showing all issues you intend to create. Include:

• WBS number (computed from parent scan)
• Issue type (Epic / Story / Task / Subtask)
• Summary title (with WBS prefix)
• Estimate (story points)
• Component(s)
• Label(s)

Example proposal format:

After presenting the proposal, explicitly ask the user:

"Does this look good? I'll create these tickets once you approve, or let me know what you'd like to change."

Wait for explicit approval. The user may:

• Approve as-is → proceed to creation
• Request additions, removals, or modifications → update the proposal and present it again
• Change estimates, components, or story wording → update and re-present

Only proceed to ticket creation after the user confirms the proposal.

Step 3 — Compute WBS Numbers

Before creating, compute WBS numbers by scanning existing children (see WBS Number Derivation):

1. Fetch the parent issue and extract its WBS prefix
2. Scan existing children with appropriate JQL
3. Parse WBS numbers from summaries
4. Determine next available number(s)
5. Show the scan results to the user and confirm the chosen numbers

Step 4 — Create Issues

For each issue in the approved proposal:

For an Epic:

Use jira_create_issue with:

• issue_type: "Epic"
• summary with WBS prefix
• customfield_10005 (Epic Name) set to same value as summary
• customfield_12913 (Parent Link) set to Initiative key in additional_fields
• All mandatory fields (components, labels, description with Business Value/AC/DoR/DoD embedded)

After creation, call jira_create_issue_link to establish the GANTT hierarchy:

type_name: "multi-level hierarchy [GANTT]"
inward_issue_key:  "<EPIC-KEY>"        # the new epic (child)
outward_issue_key: "<INITIATIVE-KEY>"  # the parent initiative

For a sprint-level issue (Story/Task/Test/Defect):

Use jira_create_issue with:

• issue_type: one of "Story", "Task", "Test", "Defect"
• summary with WBS prefix
• epic_link in additional_fields set to the Epic key
• All mandatory fields (estimate, components, labels, Business Value, AC, DoR, DoD)
• AC (customfield_10515), DoR (customfield_16516), and DoD (customfield_16544) set via additional_fields and embedded in the description body — all three confirmed accepted on Story/Task screens. Business Value embedded in description body always; also attempted via customfield_11491 in additional_fields, but confirmed rejected on Task screens — drop it silently if rejected.

For batch creates:

Use jira_batch_create_issues:

1. Call with validate_only: true first to catch errors
2. Fix any reported errors
3. Call with validate_only: false to create
4. Report the resulting keys with their WBS numbers

Step 5 — Report Results

After all issues are created, present a summary table:

Also note that all issues include Business Value, Acceptance Criteria, Definition of Ready, and Definition of Done.

Tool call shape

Use jira_create_issue with additional_fields carrying the custom fields. additional_fields is a JSON-encoded string, not a JSON object.

Example payload for a Story:

{
  "project_key": "LATC",
  "summary": "0.4.7 Provision dashboard refresh job on shared VM",
  "issue_type": "Story",
  "description": "## Context\n...\n\n## Goal\n...\n\n## Approach\n...\n\n## Out of scope\n...\n\n## Links\n...\n\n## Business Value\n...\n\n## Definition of Ready\n- [ ] AC reviewed by assignee\n- [ ] Dependencies confirmed\n- [ ] Effort estimated\n\n## Definition of Done\n- [ ] Code merged, CI green\n- [ ] Tests passing\n- [ ] AC verified by reviewer\n- [ ] Stakeholders notified",
  "components": "Operations & Infrastructure",
  "additional_fields": "{\"epic_link\":\"LATC-1304\",\"customfield_10816\":\"3\",\"customfield_16400\":\"Operations\",\"customfield_10515\":\"- [ ] Given the VM is healthy, when the timer fires, then fresh data lands within 5 min.\",\"customfield_16516\":\"- Requirements are clearly defined\\n- Dependencies are identified\",\"customfield_16544\":\"- Code merged and CI green\\n- AC verified by reviewer\",\"customfield_11491\":\"Removes recurring manual refresh toil and prevents stale data reaching stakeholder dashboards.\",\"labels\":[\"team:infra-row\"],\"priority\":{\"name\":\"Medium\"}}"
}

Notes on this example: customfield_16516 (DoR) and customfield_16544 (DoD) are included directly in additional_fields — confirmed accepted on Story/Task screens (tested 2026-07-09). customfield_11491 (Business Value) is included too, but expect it to be rejected on Task screens; if so, drop only that field and retry rather than blocking the whole create.

Example payload for an Epic (under Initiative LATC-7):

{
  "project_key": "LATC",
  "summary": "0.5 Self-service Jira Reports for Managers",
  "issue_type": "Epic",
  "description": "## Problem / Opportunity\n...\n\n## Outcomes\n...\n\n## Scope\n...\n\n## Out of scope\n...\n\n## Stakeholders\n...\n\n## Business Value\n...\n\n## Acceptance Criteria\n- [ ] Managers can generate reports without admin help.\n\n## Definition of Ready\n- [ ] AC reviewed\n- [ ] Dependencies confirmed\n\n## Definition of Done\n- [ ] All child Stories closed\n- [ ] AC verified\n- [ ] Stakeholders notified",
  "components": "Operations (Non-Tech)",
  "additional_fields": "{\"customfield_10005\":\"0.5 Self-service Jira Reports for Managers\",\"customfield_12913\":\"LATC-7\",\"customfield_16400\":\"Operations\",\"labels\":[\"team:infra-row\"]}"
}

Notes:

• summary carries the WBS prefix. Never call create with a bare title.
• epic_link is the MCP-friendly alias for customfield_10006. Either works on Stories.
• Epics use customfield_10005 (Epic Name) and customfield_12913 (Parent Link); they do not get an epic_link.
• DoR and DoD (customfield_16516, customfield_16544) are confirmed accepted via additional_fields on Story/Task screens (tested 2026-07-09 on LATC-5309) — always set both the custom field and the description section. On Epic screens this is unconfirmed; embed in description only ther

…(truncated)