gh-openshift-eng-ai-helpers-plugins-jira/skills/cntrlplane/SKILL.md

---
name: CNTRLPLANE Jira Conventions
description: Jira conventions for the CNTRLPLANE project used by OpenShift teams
---

# CNTRLPLANE Jira Conventions

This skill provides conventions and requirements for creating Jira issues in the CNTRLPLANE project, which is used by various OpenShift teams for feature development, epics, stories, and tasks.

## When to Use This Skill

Use this skill when creating Jira items in the CNTRLPLANE project:
- **Project: CNTRLPLANE** - Features, Epics, Stories, Tasks for OpenShift teams
- **Issue Types: Story, Epic, Feature, Task**

This skill is automatically invoked by the `/jira:create` command when the project_key is "CNTRLPLANE".

## Project Information

### CNTRLPLANE Project
**Full name:** Red Hat OpenShift Control Planes

**Key:** CNTRLPLANE

**Used for:** Features, Epics, Stories, Tasks, Spikes

**Used by:** Multiple OpenShift teams (HyperShift, Cluster Infrastructure, Networking, Storage, etc.)

## Version Requirements

**Note:** Universal requirements (Security Level: Red Hat Employee, Labels: ai-generated-jira) are defined in the `/jira:create` command and automatically applied to all tickets.

### Target Version (customfield_12319940)

**Status:** OPTIONAL (many issues in CNTRLPLANE have null target version)

**Recommendation:** **Omit this field** unless specifically required by the team or user explicitly requests it.

**If target version must be set:**

1. **First, fetch available versions:**
   ```python
   versions = mcp__atlassian__jira_get_project_versions(project_key="CNTRLPLANE")
   ```

2. **Find the version ID** for the desired version (e.g., "openshift-4.21" has id "12448830")

3. **Use correct MCP format** (array of version objects with ID):
   ```python
   "customfield_12319940": [{"id": "12448830"}]  # openshift-4.21
   ```

**Common version IDs:**
- `openshift-4.21`: `{"id": "12448830"}`
- `openshift-4.20`: `{"id": "12447110"}`
- `openshift-4.22`: `{"id": "12448831"}`

**IMPORTANT:** Do NOT use string format like `"openshift-4.21"` - this will fail. Must use array with version ID.

**Never set:**
- Fix Version/s (`fixVersions`) - This is managed by the release team

### Version Override Handling

If user specifies a version:
1. Fetch available versions using `mcp__atlassian__jira_get_project_versions`
2. Find the matching version ID
3. If version doesn't exist, suggest closest match or ask user to confirm
4. Use array format with version ID: `[{"id": "VERSION_ID"}]`

## Epic Link Requirements

**⚠️ CRITICAL:** To link a story to an epic in CNTRLPLANE, you **MUST** use the Epic Link custom field, NOT the `parent` field.

### Epic Link Field (customfield_12311140)

**Field Details:**
- **Field Name:** Epic Link
- **Custom Field ID:** `customfield_12311140`
- **MCP Parameter:** `additional_fields.customfield_12311140`
- **Value Format:** Epic key as string (e.g., `"CNTRLPLANE-123"`)
- **Used For:** Linking stories to epics

**IMPORTANT:** Do NOT use `additional_fields.parent` for epic-story relationships. The `parent` field has different semantics and will cause creation to fail.

### MCP Format for Epic Link

```python
additional_fields={
    "customfield_12311140": "CNTRLPLANE-123",  # Epic Link (use actual epic key)
    "labels": ["ai-generated-jira"],
    "security": {"name": "Red Hat Employee"}
}
```

### Epic Linking Implementation Strategy

When the `--parent` flag is provided for a story/task, use this implementation strategy:

#### Pre-Validation (Do This First)

Before attempting to create the issue:
1. Verify the parent epic exists using `mcp__atlassian__jira_get_issue`
2. If epic doesn't exist, prompt user:
   ```
   Epic {epic_key} not found. Options:
   1. Proceed without epic link
   2. Specify different epic
   3. Cancel creation

   What would you like to do?
   ```
3. Only proceed if epic is valid or user chooses to proceed without link

#### Preferred Approach: Include Epic Link in Creation

Attempt to create the issue with Epic Link included:
```python
mcp__atlassian__jira_create_issue(
    project_key="CNTRLPLANE",
    summary="<story title>",
    issue_type="Story",
    description="<description>",
    components="<component>",
    additional_fields={
        "customfield_12311140": "<epic-key>",  # Epic Link (e.g., "CNTRLPLANE-456")
        "labels": ["ai-generated-jira"],
        "security": {"name": "Red Hat Employee"}
    }
)
```

#### Fallback Strategy (If Creation Fails)

If creation fails with an error related to epic linking:
1. Detect error contains keywords: "epic", "parent", "customfield", or "link"
2. Inform user: "Epic link failed during creation, using fallback strategy..."
3. Create issue WITHOUT the epic link:
   ```python
   story = mcp__atlassian__jira_create_issue(
       project_key="CNTRLPLANE",
       summary="<story title>",
       issue_type="Story",
       description="<description>",
       components="<component>",
       additional_fields={
           "labels": ["ai-generated-jira"],
           "security": {"name": "Red Hat Employee"}
       }
   )
   ```
4. If creation succeeds, link to epic via update:
   ```python
   mcp__atlassian__jira_update_issue(
       issue_key=story["key"],
       fields={},
       additional_fields={
           "customfield_12311140": "<epic-key>"
       }
   )
   ```
5. Inform user of success:
   ```
   Created: CNTRLPLANE-XXX
   Linked to epic: <epic-key> ✓
   Title: <story title>
   URL: https://issues.redhat.com/browse/CNTRLPLANE-XXX
   ```

#### If Fallback Also Fails

If the update call to add Epic Link also fails:
```
Story created: CNTRLPLANE-XXX
⚠️  Automatic epic linking failed. Please link manually in Jira.
URL: https://issues.redhat.com/browse/CNTRLPLANE-XXX
```

## Component Requirements

**IMPORTANT:** Component requirements are **team-specific**.

Some teams require specific components, while others do not. The CNTRLPLANE skill does NOT enforce component selection.

**Team-specific component handling:**
- Teams may have their own skills that define required components
- For example, HyperShift team uses `hypershift` skill for component selection
- Other teams may use different components based on their structure

**If component is not specified:**
- Prompt user: "Does this issue require a component? (optional)"
- If yes, ask user to specify component name
- If no, proceed without component

## Issue Type Requirements

**Note:** Issue type templates and best practices are defined in type-specific skills (create-story, create-epic, create-feature, create-task).

### Stories
- Must include acceptance criteria
- May link to parent Epic (use `--parent` flag)

### Epics
- **Epic Name field required:** `customfield_epicname` must be set (same value as summary)
- May link to parent Feature (use `--parent` flag)

### Features
- Should include market problem and success criteria (see `create-feature` skill)

### Tasks
- May link to parent Story or Epic (use `--parent` flag)

**Note:** Security validation (credential scanning) is defined in the `/jira:create` command and automatically applied to all tickets.

## MCP Tool Integration

### For CNTRLPLANE Stories

**Basic story (no epic link):**
```python
mcp__atlassian__jira_create_issue(
    project_key="CNTRLPLANE",
    summary="<concise story title>",  # NOT full user story format
    issue_type="Story",
    description="<formatted description with full user story and AC>",
    components="<component name>",  # if required by team
    additional_fields={
        "labels": ["ai-generated-jira"],
        "security": {"name": "Red Hat Employee"}
    }
)
```

**Story linked to epic:**
```python
mcp__atlassian__jira_create_issue(
    project_key="CNTRLPLANE",
    summary="<concise story title>",  # NOT full user story format
    issue_type="Story",
    description="<formatted description with full user story and AC>",
    components="<component name>",  # if required by team
    additional_fields={
        "customfield_12311140": "<epic-key>",  # Epic Link (e.g., "CNTRLPLANE-456")
        "labels": ["ai-generated-jira"],
        "security": {"name": "Red Hat Employee"}
    }
)
```

### For CNTRLPLANE Epics

**Basic epic (no parent feature):**
```python
mcp__atlassian__jira_create_issue(
    project_key="CNTRLPLANE",
    summary="<concise epic title>",
    issue_type="Epic",
    description="<epic description with scope and AC>",
    components="<component name>",  # if required
    additional_fields={
        "customfield_12311141": "<epic name>",  # required, same as summary
        "labels": ["ai-generated-jira"],
        "security": {"name": "Red Hat Employee"}
    }
)
```

**Epic linked to parent feature:**
```python
mcp__atlassian__jira_create_issue(
    project_key="CNTRLPLANE",
    summary="<concise epic title>",
    issue_type="Epic",
    description="<epic description with scope and AC>",
    components="<component name>",  # if required
    additional_fields={
        "customfield_12311141": "<epic name>",  # required, same as summary
        "labels": ["ai-generated-jira"],
        "security": {"name": "Red Hat Employee"},
        "parent": {"key": "CNTRLPLANE-123"}  # parent feature link
    }
)
```

### For CNTRLPLANE Features

```python
mcp__atlassian__jira_create_issue(
    project_key="CNTRLPLANE",
    summary="<concise feature title>",
    issue_type="Feature",
    description="<feature description with market problem and success criteria>",
    components="<component name>",  # if required
    additional_fields={
        "labels": ["ai-generated-jira"],
        "security": {"name": "Red Hat Employee"}
        # Target version is optional - omit unless specifically required
    }
)
```

### For CNTRLPLANE Tasks

**Task linked to epic (via Epic Link):**
```python
mcp__atlassian__jira_create_issue(
    project_key="CNTRLPLANE",
    summary="<task summary>",
    issue_type="Task",
    description="<task description with what/why/AC>",
    components="<component name>",  # if required
    additional_fields={
        "customfield_12311140": "CNTRLPLANE-456",  # Epic Link (if linking to epic)
        "labels": ["ai-generated-jira"],
        "security": {"name": "Red Hat Employee"}
    }
)
```

**Note:** If you need to link a task to a parent story, use Epic Link field (`customfield_12311140`) with the story key.

### Field Mapping Reference

| Requirement | MCP Parameter | Value | Required? |
|-------------|---------------|-------|-----------|
| Project | `project_key` | `"CNTRLPLANE"` | Yes |
| Issue Type | `issue_type` | `"Story"`, `"Epic"`, `"Feature"`, `"Task"` | Yes |
| Summary | `summary` | Concise title (5-10 words), NOT full user story | Yes |
| Description | `description` | Formatted template (contains full user story) | Yes |
| Component | `components` | Team-specific component name | Varies by team |
| Target Version | `additional_fields.customfield_12319940` | Array: `[{"id": "12448830"}]` **Recommend omitting** | No |
| Labels | `additional_fields.labels` | `["ai-generated-jira"]` | Yes |
| Security Level | `additional_fields.security` | `{"name": "Red Hat Employee"}` | Yes |
| Epic Link (stories→epics) | `additional_fields.customfield_12311140` | Epic key as string: `"CNTRLPLANE-123"` | No |
| Epic Name (epics only) | `additional_fields.customfield_epicname` | Same as summary | Yes (epics) |
| Parent Link (epics→features) | `additional_fields.parent` | `{"key": "FEATURE-123"}` | No |

## Interactive Prompts

**Note:** Detailed prompts for each issue type are defined in type-specific skills (create-story, create-epic, create-feature, create-task).

**CNTRLPLANE-specific prompts:**
- **Target version** (optional): "Which version should this target? (default: openshift-4.21)"
- **Component** (if required by team): Defer to team-specific skills
- **Parent link** (for epics/tasks): "Link to parent Feature/Epic?" (optional)

## Examples

**Note:** All examples automatically apply universal requirements (Security: Red Hat Employee, Labels: ai-generated-jira) as defined in `/jira:create` command.

### Create CNTRLPLANE Story

```bash
/jira:create story CNTRLPLANE "Enable pod disruption budgets for control plane"
```

**CNTRLPLANE-specific defaults:**
- Target Version: openshift-4.21

**Prompts:** See `create-story` skill for story-specific prompts

### Create CNTRLPLANE Epic

```bash
/jira:create epic CNTRLPLANE "Improve cluster lifecycle management"
```

**CNTRLPLANE-specific defaults:**
- Target Version: openshift-4.21
- Epic Name: Same as summary (required field)

**Prompts:** See `create-epic` skill for epic-specific prompts

### Create CNTRLPLANE Feature

```bash
/jira:create feature CNTRLPLANE "Advanced observability capabilities"
```

**CNTRLPLANE-specific defaults:**
- Target Version: openshift-4.21

**Prompts:** See `create-feature` skill for feature-specific prompts

### Create CNTRLPLANE Task

```bash
/jira:create task CNTRLPLANE "Refactor cluster controller reconciliation logic"
```

**CNTRLPLANE-specific defaults:**
- Target Version: openshift-4.21

**Prompts:** See `create-task` skill for task-specific prompts

## Error Handling

### Invalid Version

**Scenario:** User specifies a version that doesn't exist.

**Action:**
1. Use `mcp__atlassian__jira_get_project_versions` to fetch available versions
2. Suggest closest match: "Version 'openshift-4.21.5' not found. Did you mean 'openshift-4.21.0'?"
3. Show available versions: "Available: openshift-4.20.0, openshift-4.21.0, openshift-4.22.0"
4. Wait for confirmation or correction

### Component Required But Missing

**Scenario:** Team requires component, but user didn't specify.

**Action:**
1. If team skill detected required components, show options
2. Otherwise, generic prompt: "Does this issue require a component?"
3. If yes, ask user to specify component name
4. If no, proceed without component

### Sensitive Data Detected

**Scenario:** Credentials or secrets found in description.

**Action:**
1. STOP issue creation immediately
2. Inform user: "I detected potential credentials in the description."
3. Show general location: "Found in: Technical details section"
4. Do NOT echo the sensitive data back
5. Suggest: "Please use placeholder values like 'YOUR_API_KEY'"
6. Wait for user to provide sanitized content

### Parent Issue Not Found

**Scenario:** User specifies `--parent CNTRLPLANE-999` but issue doesn't exist.

**Action:**
1. Attempt to fetch parent issue using `mcp__atlassian__jira_get_issue`
2. If not found: "Parent issue CNTRLPLANE-999 not found. Would you like to proceed without a parent?"
3. Offer options:
   - Proceed without parent
   - Specify different parent
   - Cancel creation

### MCP Tool Failure

**Scenario:** MCP tool returns an error.

**Action:**
1. Parse error message for actionable information
2. Common errors:
   - **"Field 'component' is required"** → Prompt for component (team-specific requirement)
   - **"Permission denied"** → User may lack permissions
   - **"Version not found"** → Use version error handling above
   - **"Issue type not available"** → Project may not support this issue type
3. Provide clear next steps
4. Offer to retry after corrections

### Wrong Issue Type

**Scenario:** User tries to create a bug in CNTRLPLANE.

**Action:**
1. Inform user: "Bugs should be created in OCPBUGS. CNTRLPLANE is for stories/epics/features/tasks."
2. Suggest: "Would you like to create this as a story in CNTRLPLANE, or as a bug in OCPBUGS?"
3. Wait for user decision

**Note:** Jira description formatting (Wiki markup) is defined in the `/jira:create` command.

## Team-Specific Extensions

Teams using CNTRLPLANE may have additional team-specific requirements defined in separate skills:

- **HyperShift team:** Uses `hypershift` skill for component selection (HyperShift / ARO, HyperShift / ROSA, HyperShift)
- **Other teams:** May define their own skills with team-specific components and conventions

Team-specific skills are invoked automatically when team keywords are detected in the summary or when specific components are mentioned.

## Workflow Summary

When `/jira:create` is invoked for CNTRLPLANE:

1. ✅ **CNTRLPLANE skill loaded:** Applies project-specific conventions
2. ⚙️ **Apply CNTRLPLANE defaults:**
   - Target version: openshift-4.21 (default)
   - Epic name field (for epics)
3. 🔍 **Check for team-specific skills:** If team keywords detected, invoke team skill (e.g., `hypershift`)
4. 💬 **Interactive prompts:** Collect missing information (see type-specific skills for details)

**Note:** Universal requirements (security, labels), security validation, and issue creation handled by `/jira:create` command.

## Best Practices

1. **Version consistency:** Use common defaults (openshift-4.21) unless team specifies otherwise
2. **Template adherence:** Defer to type-specific skills for templates (create-story, create-epic, etc.)
3. **Link hierarchy:** Link epics to features, tasks to stories/epics using `--parent` flag
4. **Descriptive summaries:** Use clear, searchable issue summaries
5. **Component selection:** Defer to team-specific skills when applicable (e.g., HyperShift)

**Note:** Universal best practices (security, labels, formatting, credential scanning) are defined in the `/jira:create` command.

## See Also

- `/jira:create` - Main command that invokes this skill
- `ocpbugs` skill - For OCPBUGS bugs
- Team-specific skills (e.g., `hypershift`) - For team-specific conventions
- Type-specific skills (create-story, create-epic, create-feature, create-task) - For issue type best practices