Jira Create Issues

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

This skill governs how the agent creates Jira issues. Default is self-hosted Jira Data Center via user-mcp-atlassian. Jira Cloud (Premium trial) is a second site via user-mcp-atlassian-cloud — pick the namespace from the instance the user named. DC WBS, 8-pillar components, and AC/DoR/DoD/BV custom-field IDs apply to DC only unless the user explicitly asks to enforce an equivalent contract on Cloud.

Two Jira instances — pick the right MCP

Never mix field IDs, parent-link mechanics, or governance rules across sites.

Cloud-specific create rules (confirmed 2026-08-24 on SCRUM)

Use these instead of the DC field IDs and WBS/governance contract when creating issues on Cloud:

Cloud link types in use: Blocks, Relates. SCRUM transitions: To Do 11, In Progress 21, In Review 31, Blocked 41, Done 51.

Fields and screens cannot be configured via MCP

MCP can read field metadata (jira_search_fields, jira_get_create_fields, jira_get_project_fields, jira_get_field_options) and set values on issues (jira_create_issue / jira_update_issue). It cannot create custom fields, add fields to screens, edit screen schemes or field configurations, or change workflows (beyond transitioning an issue).

On team-managed Cloud, field layout is Project settings → Issue types → [type] → Fields. On company-managed Cloud or DC, screens are admin UI. If a field is missing from the issue type, configure it in Jira first, then backfill values with MCP.

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.

Correction (2026-07-16/17): Business Value/AC/DoR/DoD used to be required in both the custom field and the description body for every issue type. That was wrong — for Story/Task/Test/Defect/Sub-task, these four now live only in their dedicated custom fields; do not add matching headings to the description (it's redundant duplication, not a compliance requirement). This was applied retroactively to 112 pre-existing sprint-level Infra issues on 2026-07-17.

Correction (2026-07-22): Epics/Initiatives now follow the same custom-field-only rule — do not embed ## Business Value, ## Acceptance Criteria, ## Definition of Ready, or ## Definition of Done headings in Epic/Initiative descriptions either. This reverses the earlier belief that these fields were "untested/unconfirmed on the Epic screen" — all 4 custom fields (customfield_11491, customfield_10515, customfield_16516, customfield_16544) were confirmed settable via jira_update_issue across 36 real Infra Epics/Initiatives (e.g. LATC-5803, LATC-5101), including successfully backfilling a previously-empty Business Value field on a live Epic. Description bodies for Epic/Initiative keep their narrative sections (Problem/Opportunity, Outcomes, Scope, Out of scope, Stakeholders) but never the four governance-field headings. This was applied retroactively to 36 pre-existing Infra Epics/Initiatives on 2026-07-22.

Screen-availability caveat discovered during the 2026-07-17 retroactive fix (still applies): this Jira DC's screen configuration does not expose all 4 fields on every sprint-level issue type — confirmed by dozens of real rejections, not just the earlier single-Story test:

• Sub-task screen: none of the 4 fields (customfield_10515 AC, customfield_16516 DoR, customfield_16544 DoD, customfield_11491 BV) are settable — every attempt on real Sub-tasks (e.g. LATC-2718–LATC-2725, LATC-2333, LATC-5794) was rejected with Field '<id>' cannot be set. It is not on the appropriate screen, or unknown.
• Task screen: AC/DoR/DoD are settable (confirmed on many real Tasks), but Business Value is not — rejected on every Task tested (LATC-5550, LATC-5483, LATC-3555, LATC-3554, LATC-3553, LATC-3552, LATC-2926, LATC-2095), including via jira_update_issue (edit), not just create.
• Story, Epic, Initiative screens: all 4 fields confirmed settable (create and/or edit).

Fallback rule when a field is genuinely unavailable on that issue type's screen: don't silently drop the content and don't force it into a field that will be rejected. Keep it in the description under its original ## heading instead (currently only needed for ## Business Value on a Task, or all of AC/DoR/DoD/BV on a Sub-task) — this is the one exception to "custom-field-only," justified by an actual platform constraint rather than a style choice. Note the limitation to the user and suggest a Jira admin add the missing field(s) to that issue type's screen scheme if this recurs often.

Active enforcement scope (by explicit direction): Epic, Initiative, Story, and Task are actively enforced end-to-end. Sub-task is out of scope for now — don't flag existing Sub-tasks as compliance gaps or spend effort remediating them until told otherwise. If you're creating a new Sub-task anyway, still apply the description-heading fallback (it's free and correct), just don't treat Sub-task cleanup as required work.

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

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, including custom-field-only placement for the four governance fields.

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: For Epics/Initiatives, a markdown body explaining what the issue is about, why it matters, and relevant context — sections like ## Problem / Opportunity, ## Outcomes, ## Scope, ## Out of scope, ## Stakeholders. For Story/Task/Test/Defect/Sub-task, keep it short: a condensed 1–3 sentence summary (no heading) instead of separate Context/Goal/Approach sections, plus any remaining sections that genuinely have no dedicated field (## Out of scope, ## Links, ## Outcomes (value unlocked)). Business Value/AC/DoR/DoD go in their custom fields only — never in the description — for every issue type, including Epic/Initiative (updated 2026-07-22; the sole exceptions remain Business Value on Task and all four on Sub-task, where the field has no screen slot).

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): 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. Custom field only, for every issue type — including Epic/Initiative (confirmed settable 2026-07-22) — do not add it to the description. customfield_11491 has been confirmed rejected on the Story/Task create screen but accepted on the edit screen; on Epic/Initiative it has been observed accepted via jira_update_issue. Attempt it at create time via additional_fields, and if Jira rejects it, immediately follow up with a jira_update_issue call setting just that field rather than dropping it or writing it into the description. Exception: Task has no Business Value field on its screen at all — keep ## Business Value in the description there only. 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): 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. Custom field only, for every issue type — including Epic/Initiative — never embed ## Acceptance Criteria in the description (exception: Sub-task, which has no field for it). 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): Conditions that must be met before work can begin. Custom field only, for every issue type — including Epic/Initiative — never embed ## Definition of Ready in the description (exception: Sub-task). 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): Conditions that must be met for the work to be considered complete. Custom field only, for every issue type — including Epic/Initiative — never embed ## Definition of Done in the description (exception: Sub-task). 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 (corrected 2026-07-16/17, extended to Epic/Initiative 2026-07-22): For Epic, Initiative, and Story, all 4 fields (AC/DoR/DoD/BV) live only in their native custom fields — never embed matching ## headings in the description. For Task, AC/DoR/DoD are custom-field-only, but Business Value has no field on the Task screen at all — keep ## Business Value in the description for Tasks (the one sanctioned exception, forced by a platform limitation rather than a style choice). For Sub-task, none of the 4 fields exist on that screen — keep all of AC/DoR/DoD/BV as ## headings in the description. Flag to the user that a Jira admin could add these fields to the Task/Sub-task screen schemes if this recurs often.

Scope note (by explicit direction): Epic, Initiative, Story, and Task are the actively-enforced issue types — treat gaps on those as real compliance issues worth fixing. Sub-task is deprioritized for now: the description-heading fallback above is still correct behavior if you're touching one anyway, but don't proactively audit or remediate existing Sub-tasks until told otherwise.

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.

Infrastructure vs Operations (corrected 2026-08-07 — supersedes the 2026-07-24 "always use Operations" note, which was wrong): the Operations & Infrastructure component maps to two distinct Function area values, and you must choose based on the nature of the work rather than defaulting:

• Infrastructure — the default for this component, and the dominant value in LATC (581 issues vs 309 for Operations). Use it whenever the work builds, changes, or hardens technical infrastructure: cloud accounts and landing zones, GPU clusters and compute enablement, Kubernetes, networking, IaC/Terraform, CI/CD pipelines and runners, registries, deployment and GitOps, storage/buckets, security tooling and scanning, observability plumbing.
• Operations — reserve for work that is legitimately operational rather than technical: process definition, governance, intake and triage, licensing/procurement and vendor administration, access-review and audit cadences, reporting/dashboard upkeep, runbook and on-call process (as opposed to the tooling that implements it), hiring, and anything on the Operations (Non-Tech) component.

If a ticket sits on the boundary, ask which side it belongs to rather than guessing — and never relabel an existing Infrastructure ticket to Operations as a normalization pass.

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 → decide by the nature of the work per the Infrastructure vs Operations rule above; Operations (Non-Tech) being present is a strong signal for Operations, but technical platform work still takes Infrastructure.
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. On DC, 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. Skip WBS on Cloud unless the user asks.
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 matching MCP namespace, not raw REST. DC → user-mcp-atlassian. Cloud → user-mcp-atlassian-cloud. Do not send DC custom-field IDs to Cloud or Cloud IDs to DC.
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 (DC only) — DoR, DoD, AC, and Business Value are always required, never

…(truncated)