Implementation guide for creating Jira epics with proper scope and parent linking
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
This skill provides implementation guidance for creating well-structured Jira epics that organize related stories and tasks into cohesive bodies of work.
This skill is automatically invoked by the /jira:create epic command to guide the epic creation process.
An agile epic is:
Epics should:
| Level | Scope | Duration | Example |
|---|---|---|---|
| Feature | Strategic objective, market problem | Multiple releases | "Advanced cluster observability" |
| Epic | Specific capability, narrower than feature | One quarter/release | "Multi-cluster metrics aggregation" |
| Story | Single user-facing functionality | One sprint | "As an SRE, I want to view metrics from multiple clusters in one dashboard" |
IMPORTANT: Many Jira configurations require the epic name field to be set.
MCP Tool Handling:
The epic description should:
Good example:
Enable administrators to manage multiple hosted control plane clusters from a single observability dashboard.
This epic delivers unified metrics aggregation, alerting, and visualization across clusters, reducing the operational overhead of managing multiple cluster environments.
Target users: SREs, Platform administrators
Epic-level acceptance criteria define when the epic is complete:
Format:
h2. Epic Acceptance Criteria
* <High-level outcome 1>
* <High-level outcome 2>
* <High-level outcome 3>
Example:
h2. Epic Acceptance Criteria
* Administrators can view aggregated metrics from all clusters in a single dashboard
* Alert rules can be configured to fire based on cross-cluster conditions
* Historical metrics are retained for 30 days across all clusters
* Documentation is complete for multi-cluster setup and configuration
Characteristics:
Include timeframe information:
Example:
h2. Timeline
* Target: Q1 2025 / OpenShift 4.21
* Milestone 1: Metrics collection infrastructure (Sprint 1-2)
* Milestone 2: Dashboard and visualization (Sprint 3-4)
* Milestone 3: Alerting and historical data (Sprint 5-6)
If the epic belongs to a larger feature:
--parent flagExample:
h2. Parent Feature
This epic is part of [PROJ-100] "Advanced cluster observability" and specifically addresses the multi-cluster aggregation capability.
When creating an epic, guide the user through:
Prompt: "What is the main objective or goal of this epic? What capability will it deliver?"
Helpful questions:
Example response:
Enable SREs to manage and monitor multiple ROSA HCP clusters from a unified observability dashboard, reducing the operational complexity of multi-cluster environments.
Prompt: "What is included in this epic? What is explicitly out of scope?"
Helpful questions:
Example response:
In scope:
- Metrics aggregation from multiple clusters
- Unified dashboard for cluster health
- Cross-cluster alerting
- 30-day historical metrics retention
Out of scope:
- Log aggregation (separate epic)
- Cost reporting (different feature)
- Support for non-HCP clusters (future work)
Prompt: "What are the high-level outcomes that define this epic as complete?"
Guidance:
Example response:
- SREs can view aggregated metrics from all managed clusters in one dashboard
- Alert rules can be defined for cross-cluster conditions (e.g., "any cluster CPU >80%")
- Historical metrics available for 30 days
- Configuration documented and tested
Prompt: "What is the target timeframe for this epic? (quarter, release, or estimated sprints)"
Example responses:
Prompt: "Is this epic part of a larger feature? If yes, provide the feature key."
If yes:
Before submitting the epic, validate:
mcp__atlassian__jira_create_issue(
project_key="<PROJECT_KEY>",
summary="<epic summary>",
issue_type="Epic",
description="""
<Epic objective and description>
h2. Epic Acceptance Criteria
* <Outcome 1>
* <Outcome 2>
* <Outcome 3>
h2. Scope
h3. In Scope
* <What's included>
h3. Out of Scope
* <What's not included>
h2. Timeline
Target: <quarter/release>
""",
components="<component name>", # if required
additional_fields={
"customfield_epicname": "<epic name>", # if required, same as summary
# Add other project-specific fields
}
)
mcp__atlassian__jira_create_issue(
project_key="CNTRLPLANE",
summary="Multi-cluster metrics aggregation for ROSA HCP",
issue_type="Epic",
description="""
Enable SREs to manage and monitor multiple ROSA HCP clusters from a unified observability dashboard, reducing operational complexity of multi-cluster environments.
h2. Epic Acceptance Criteria
* SREs can view aggregated metrics from all managed clusters in one dashboard
* Alert rules can be defined for cross-cluster conditions (e.g., "any cluster CPU >80%")
* Historical metrics retained for 30 days across all clusters
* Multi-cluster setup documented and tested with production workloads
* Performance acceptable with 100+ clusters
h2. Scope
h3. In Scope
* Metrics aggregation across ROSA HCP clusters
* Unified dashboard for cluster health and performance
* Cross-cluster alerting capabilities
* 30-day historical metrics retention
* Configuration via CLI and API
h3. Out of Scope
* Log aggregation (separate epic CNTRLPLANE-200)
* Cost reporting (different feature)
* Support for standalone OCP clusters (future consideration)
* Integration with external monitoring systems (post-MVP)
h2. Timeline
* Target: Q1 2025 / OpenShift 4.21
* Estimated: 6 sprints
* Key milestone: MVP dashboard by end of Sprint 3
h2. Target Users
* SREs managing multiple ROSA HCP clusters
* Platform administrators
* Operations teams
h2. Dependencies
* Requires centralized metrics storage infrastructure ([CNTRLPLANE-150])
* Depends on cluster registration API ([CNTRLPLANE-175])
""",
components="HyperShift / ROSA",
additional_fields={
"customfield_12319940": "openshift-4.21", # target version
"customfield_epicname": "Multi-cluster metrics aggregation for ROSA HCP", # epic name
"labels": ["ai-generated-jira", "observability"],
"security": {"name": "Red Hat Employee"}
}
)
When linking an epic to a parent feature via --parent flag, use the Parent Link custom field (NOT Epic Link, NOT standard parent field):
mcp__atlassian__jira_create_issue(
project_key="CNTRLPLANE",
summary="Multi-cluster monitoring dashboard",
issue_type="Epic",
description="<epic content with scope and AC>",
components="HyperShift",
additional_fields={
"customfield_12311141": "Multi-cluster monitoring dashboard", # Epic Name (required)
"customfield_12313140": "CNTRLPLANE-100", # Parent Link - links to parent FEATURE (STRING!)
"labels": ["ai-generated-jira"],
"security": {"name": "Red Hat Employee"}
}
)
IMPORTANT:
customfield_12313140) - value is a STRINGcustomfield_12311140) - value is a STRINGparent field does NOT work for these relationshipsSee: /jira:create command documentation for complete parent linking hierarchy and implementation strategy.
Use Jira's native formatting (Wiki markup):
<Epic objective - what capability will be delivered and why it matters>
h2. Epic Acceptance Criteria
* <High-level outcome 1>
* <High-level outcome 2>
* <High-level outcome 3>
h2. Scope
h3. In Scope
* <Functionality included in this epic>
* <Capabilities to be delivered>
h3. Out of Scope
* <Related work NOT in this epic>
* <Future considerations>
h2. Timeline
* Target: <quarter or release>
* Estimated: <sprints>
* Key milestones: <major deliverables>
h2. Target Users
* <User group 1>
* <User group 2>
h2. Dependencies (optional)
* [PROJ-XXX] - <dependency description>
h2. Parent Feature (if applicable)
This epic is part of [PROJ-YYY] "<feature name>" and addresses <how this epic contributes>.
Scenario: Epic creation fails due to missing epic name field.
Action:
customfield_epicname = summaryNote: Field ID may vary by Jira instance:
customfield_epicname (common)customfield_10011 (numbered field)Scenario: Epic seems too large (would take >1 quarter).
Action:
Example:
This epic seems quite large (estimated 12+ sprints). Consider:
Option 1: Split into multiple epics
- Epic 1: Core metrics aggregation (sprints 1-6)
- Epic 2: Advanced dashboards and alerting (sprints 7-12)
Option 2: Create as Feature instead
- This might be better as a Feature with multiple child Epics
Which would you prefer?
Scenario: Epic could be completed in one sprint.
Action:
Example:
This epic seems small enough to be a single Story (completable in one sprint).
Epics should typically:
- Span multiple sprints (2-8 sprints)
- Contain multiple stories
- Deliver a cohesive capability
Would you like to create this as a Story instead? (yes/no)
Scenario: User specifies parent, but it's not a Feature.
Action:
Example:
Parent issue PROJ-100 is an Epic, but epics should typically link to Features (not other Epics).
Options:
1. Link to the parent Feature instead (if PROJ-100 has a parent)
2. Proceed without parent link
3. Create a Feature first, then link this Epic to it
What would you like to do?
Scenario: User doesn't provide epic acceptance criteria.
Action:
Example:
Epic acceptance criteria help define when this epic is complete. Let's add some.
What are the key outcomes that must be achieved?
- What capabilities will exist when this epic is done?
- How will you demonstrate the epic is complete?
- What must work end-to-end?
Example: "Administrators can view aggregated metrics from all clusters"
Scenario: Sensitive data detected in epic content.
Action:
Scenario: MCP tool returns an error when creating the epic.
Action:
Common errors:
Input:
/jira:create epic CNTRLPLANE "Multi-cluster metrics aggregation" --parent CNTRLPLANE-100
Interactive prompts:
What is the main objective of this epic?
> Enable SREs to monitor multiple ROSA HCP clusters from one dashboard
What is included in scope?
> Metrics aggregation, unified dashboard, cross-cluster alerting, 30-day retention
What is out of scope?
> Log aggregation, cost reporting, non-HCP cluster support
Epic acceptance criteria?
> - View aggregated metrics from all clusters
> - Configure cross-cluster alerts
> - 30-day historical retention
> - Complete documentation
Timeframe?
> Q1 2025, estimate 6 sprints
Implementation:
additional_fields={
"customfield_12311141": "Multi-cluster metrics aggregation", # Epic Name
"customfield_12313140": "CNTRLPLANE-100", # Parent Link (STRING, not object!)
"labels": ["ai-generated-jira"],
"security": {"name": "Red Hat Employee"}
}
Result:
customfield_12313140)Input:
/jira:create epic CNTRLPLANE "Advanced node pool autoscaling for ARO HCP"
Auto-applied (via cntrlplane skill):
Interactive prompts:
Result:
Input:
/jira:create epic MYPROJECT "Improve test coverage for API endpoints"
Result:
❌ Epic is actually a story
"As a user, I want to view a dashboard"
✅ Too small, create as Story instead
❌ Epic is actually a feature
"Complete observability platform redesign" (12 months, 50+ stories)
✅ Too large, create as Feature with child Epics
❌ Vague acceptance criteria
- Epic is done when everything works
✅ Be specific: "SREs can view metrics from 100+ clusters with <1s load time"
❌ Implementation details in AC
- Backend uses PostgreSQL for metrics storage
- API implements gRPC endpoints
✅ Focus on outcomes, not implementation
❌ No scope definition
Description: "Improve monitoring"
✅ Define what's included and what's not
/jira:create - Main command that invokes this skill (includes Issue Hierarchy and Parent Linking documentation)create-feature skill - For creating parent featurescreate-story skill - For stories within epics (uses Epic Link field, NOT parent field)cntrlplane skill - CNTRLPLANE specific conventions