openshift-eng/hypershift

HyperShift Jira Conventions

This skill provides HyperShift team-specific conventions for creating Jira issues in CNTRLPLANE and OCPBUGS projects.

When to Use This Skill

This skill is automatically invoked when:

• Summary or description contains HyperShift keywords: "HyperShift", "ARO HCP", "ROSA HCP", "hosted control plane"
• Component contains "HyperShift"
• User explicitly requests HyperShift conventions

This skill works in conjunction with the cntrlplane skill, adding HyperShift-specific requirements on top of generic CNTRLPLANE/OCPBUGS conventions.

Component Requirements

ALL HyperShift issues in CNTRLPLANE and OCPBUGS must have a component set to one of:

1. HyperShift / ARO - ARO HCP (Azure Red Hat OpenShift Hosted Control Planes)
2. HyperShift / ROSA - ROSA HCP (Red Hat OpenShift Service on AWS Hosted Control Planes)
3. HyperShift - When it's not clear if the issue is about AWS, Azure, or agent platform

Component Selection Logic

Auto-detection based on summary/description keywords:

| Keywords | Component | Confidence | |----------|-----------|------------| | ARO, Azure, "ARO HCP" | HyperShift / ARO | High | | ROSA, AWS, "ROSA HCP" | HyperShift / ROSA | High | | Both ARO and ROSA mentioned | HyperShift | High (multi-platform) | | "All platforms", "platform-agnostic" | HyperShift | Medium (verify with user) | | No platform keywords | Prompt user | N/A (cannot auto-detect) |

Important: If no platform keywords are found, do NOT assume platform-agnostic. Prompt the user to clarify which component.

Examples:

Summary: "Enable autoscaling for ROSA HCP clusters"
→ Component: HyperShift / ROSA (auto-detected)

Summary: "ARO HCP control plane pods crash on upgrade"
→ Component: HyperShift / ARO (auto-detected)

Summary: "Multi-cloud support for ARO and ROSA HCP"
→ Component: HyperShift (auto-detected, mentions both platforms)

Summary: "Improve control plane pod scheduling"
→ Component: Prompt user (no keywords, cannot determine platform)

When Auto-Detection is Uncertain

If component cannot be confidently auto-detected:

1. Present options to user with descriptions
2. Ask for clarification

Prompt example:

Which HyperShift platform does this issue affect?

1. HyperShift / ARO - for ARO HCP (Azure) issues
2. HyperShift / ROSA - for ROSA HCP (AWS) issues
3. HyperShift - for platform-agnostic issues or affects both

Select (1-3):

Version Defaults

HyperShift team uses specific version defaults:

CNTRLPLANE Issues

Target Version (customfield_10855):

• Default: openshift-4.21
• Override: User may specify different versions (e.g., 4.20, 4.22, 4.23)

OCPBUGS Issues

Affects Version/s:

• Default: 4.21
• User should specify: The actual version where the bug was found

Target Version (customfield_10855):

• Default: 4.21
• Override: May be different based on severity and backport requirements

Labels

In addition to ai-generated-jira (from CNTRLPLANE skill), HyperShift issues may include:

Platform-specific:

• aro-hcp - ARO HCP specific
• rosa-hcp - ROSA HCP specific

Feature area:

• autoscaling
• networking
• observability
• upgrade
• lifecycle

Priority/type:

• technical-debt
• security
• performance

MCP Tool Integration

Note: Always include contentFormat: "markdown" when calling createJiraIssue or editJiraIssue so descriptions are interpreted as Markdown.

For HyperShift Stories/Tasks in CNTRLPLANE

Use createJiraIssue with contentFormat: "markdown", project key CNTRLPLANE, and set the component to one of HyperShift / ARO, HyperShift / ROSA, or HyperShift based on the auto-detection logic above. Include customfield_10855 (target version) set to "openshift-4.21" (or user-specified version), along with standard labels and security fields.

For HyperShift Bugs in OCPBUGS

Use createJiraIssue with contentFormat: "markdown", project key OCPBUGS, issue type Bug, and the appropriate HyperShift component. Include versions (affects version) as [{"name": "4.21"}], customfield_10855 (target version) set to "4.21", along with standard labels and security fields.

Examples

Example 1: ROSA HCP Story (Auto-Detection)

Input:

/jira:create story CNTRLPLANE "Enable automatic node pool scaling for ROSA HCP"

Auto-detected:

• Component: HyperShift / ROSA (detected from "ROSA HCP")
• Target Version: openshift-4.21
• Labels: ai-generated-jira
• Security: Red Hat Employee

Interactive prompts:

• User story format (As a... I want... So that...)
• Acceptance criteria

Result:

• Story created with HyperShift / ROSA component
• All CNTRLPLANE conventions applied

Example 2: ARO HCP Bug

Input:

/jira:create bug "ARO HCP control plane pods crash on upgrade"

Auto-detected:

• Project: OCPBUGS (default for bugs)
• Component: HyperShift / ARO (detected from "ARO HCP")
• Affected Version: 4.21 (default, user can override)
• Target Version: 4.21
• Labels: ai-generated-jira
• Security: Red Hat Employee

Interactive prompts:

• Bug template sections

Result:

• Bug created in OCPBUGS with HyperShift / ARO component

Example 3: Platform-Agnostic Epic

Input:

/jira:create epic CNTRLPLANE "Improve HyperShift operator observability"

Auto-detected:

• Component: HyperShift (platform-agnostic, from "HyperShift operator")
• Target Version: openshift-4.21
• Epic Name: Same as summary
• Labels: ai-generated-jira
• Security: Red Hat Employee

Interactive prompts:

• Epic objective and scope
• Acceptance criteria

Result:

• Epic created with HyperShift component (not platform-specific)

Example 4: Multi-Platform Feature

Input:

/jira:create feature CNTRLPLANE "Advanced observability for ROSA and ARO HCP"

Auto-detected:

• Component: HyperShift (affects both platforms)
• Target Version: openshift-4.21
• Labels: ai-generated-jira
• Security: Red Hat Employee

Interactive prompts:

• Market problem
• Strategic value
• Success criteria
• Epic breakdown

Result:

• Feature with HyperShift component (since it affects both platforms)

Example 5: Uncertain Component (Prompts User)

Input:

/jira:create story CNTRLPLANE "Improve control plane pod scheduling"

Detection: Summary doesn't contain platform-specific keywords

Prompt:

Which HyperShift platform does this issue affect?

1. HyperShift / ARO - for ARO HCP (Azure) issues
2. HyperShift / ROSA - for ROSA HCP (AWS) issues
3. HyperShift - for platform-agnostic issues or affects both

Select (1-3):

User selects: 3

Result:

• Component set to HyperShift

Component Override

User can override auto-detection using --component flag:

# Override auto-detection
/jira:create story CNTRLPLANE "Enable autoscaling for ROSA HCP" --component "HyperShift"

This will use "HyperShift" component instead of auto-detected "HyperShift / ROSA".

Error Handling

Invalid Component

Scenario: User specifies component that's not a valid HyperShift component.

Action:

Component "Networking" is not a valid HyperShift component.

HyperShift issues must use one of:
- HyperShift / ARO
- HyperShift / ROSA
- HyperShift

Which component would you like to use?

Component Required but Missing

Scenario: Component cannot be auto-detected and user didn't specify.

Action:

HyperShift issues require a component. Which component?

1. HyperShift / ARO - for ARO HCP (Azure) issues
2. HyperShift / ROSA - for ROSA HCP (AWS) issues
3. HyperShift - for platform-agnostic issues

Select (1-3):

Workflow Summary

When creating a HyperShift issue:

1. ✅ CNTRLPLANE skill loads - Applies generic conventions (security, labels, versions)
2. ✅ HyperShift skill loads - Adds HyperShift-specific requirements
3. 🔍 Auto-detect component - Analyze summary/description for ARO/ROSA keywords
4. ⚙️ Apply component:
   • If auto-detected with high confidence → Use detected component
   • If uncertain → Prompt user for component selection
   • If --component flag provided → Use specified component (validate it's HyperShift)
5. 💬 Interactive prompts - Collect issue type-specific information
6. 🔒 Security scan - Validate no credentials/secrets
7. ✅ Create issue - Use MCP tool with HyperShift component
8. 📤 Return result - Issue key, URL, applied defaults (including component)

Best Practices

1. Include platform keywords in summary - Makes auto-detection more accurate

   • ✅ "Enable autoscaling for ROSA HCP"
   • ❌ "Enable autoscaling" (unclear which platform)

2. Be specific about platform when known

   • If issue is ARO-specific, mention "ARO" or "Azure" in summary
   • If issue is ROSA-specific, mention "ROSA" or "AWS" in summary

3. Use platform-agnostic component wisely

   • Only use "HyperShift" (without /ARO or /ROSA) when issue truly affects all platforms
   • When in doubt, ask the team

4. Component consistency within epic

   • Stories within an epic should generally have the same component as the epic
   • Exception: Epic is platform-agnostic but stories target specific platforms

See Also

• /jira:create - Main command that invokes this skill
• cntrlplane skill - Generic CNTRLPLANE/OCPBUGS conventions
• HyperShift team documentation