zhongwei/gh-openshift-eng-ai-helpers-plugins-jira
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:46:00 +08:00
commit 2109c2330b
22 changed files with 9156 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

504
skills/cntrlplane/SKILL.md Normal file
View File

@@ -0,0 +1,504 @@
---
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

558
skills/create-bug/SKILL.md Normal file
View File

@@ -0,0 +1,558 @@
---
name: Create Jira Bug
description: Implementation guide for creating well-formed Jira bug reports
---
# Create Jira Bug
This skill provides implementation guidance for creating well-structured Jira bug reports with complete reproduction steps and clear problem descriptions.
## When to Use This Skill
This skill is automatically invoked by the `/jira:create bug` command to guide the bug creation process.
## Prerequisites
- MCP Jira server configured and accessible
- User has permissions to create issues in the target project
- Bug information available (problem description, steps to reproduce, etc.)
## Bug Report Best Practices
### Complete Information
A good bug report contains:
1. **Clear summary** - Brief description that identifies the problem
2. **Detailed description** - Complete context and background
3. **Reproducibility** - How often the bug occurs
4. **Steps to reproduce** - Exact sequence to trigger the bug
5. **Actual vs expected results** - What happens vs what should happen
6. **Environment details** - Version, platform, configuration
7. **Additional context** - Logs, screenshots, error messages
### Summary Guidelines
The summary should:
- Be concise (one sentence)
- Identify the problem clearly
- Include key context when helpful
- Avoid vague terms like "broken" or "doesn't work"
**Good examples:**
- "API server returns 500 error when creating namespaces"
- "Control plane pods crash on upgrade from 4.20 to 4.21"
- "Memory leak in etcd container after 24 hours"
**Bad examples:**
- "Things are broken"
- "Error in production"
- "Fix the bug"
## Bug Description Template
Use this template structure for consistency:
```
Description of problem:
<Clear, detailed description of the issue>
Version-Release number of selected component (if applicable):
<e.g., 4.21.0, openshift-client-4.20.5>
How reproducible:
<Always | Sometimes | Rarely>
Steps to Reproduce:
1. <First step - be specific>
2. <Second step>
3. <Third step>
Actual results:
<What actually happens - include error messages>
Expected results:
<What should happen instead>
Additional info:
<Logs, screenshots, stack traces, related issues, workarounds>
```
## Interactive Bug Collection Workflow
When creating a bug, guide the user through each section interactively:
### 1. Problem Description
**Prompt:** "What is the problem? Describe it clearly and in detail."
**Tips to share:**
- Provide context: What were you trying to do?
- Be specific: What component or feature is affected?
- Include impact: Who is affected? How severe is it?
**Example response:**
```
The kube-apiserver pod crashes immediately after upgrading a hosted control plane cluster from version 4.20 to 4.21. The pod enters CrashLoopBackOff state and all API requests to the cluster fail.
```
### 2. Version Information
**Prompt:** "Which version exhibits this issue? (e.g., 4.21.0, 4.20.5)"
**Tips:**
- Include full version number if known
- Specify component version if different from platform version
- Note if issue affects multiple versions
**Default:** Use project-specific default (e.g., 4.21 for OCPBUGS)
### 3. Reproducibility
**Prompt:** "How reproducible is this issue?"
**Options:**
- **Always** - Happens every time following the steps
- **Sometimes** - Happens intermittently, even with same steps
- **Rarely** - Hard to reproduce, happened once or few times
**Use case for each:**
- Always: Easiest to debug and fix
- Sometimes: May be timing-related or race condition
- Rarely: May be environmental or complex interaction
### 4. Steps to Reproduce
**Prompt:** "What are the exact steps to reproduce this issue? Be as specific as possible."
**Guidelines:**
- Number each step
- Be precise (exact commands, button clicks, inputs)
- Include environment setup if needed
- Use code blocks for commands
- Mention any prerequisites
**Example:**
```
Steps to Reproduce:
1. Create a ROSA HCP cluster on version 4.20.0:
rosa create cluster --name test-cluster --version 4.20.0 --hosted-cp
2. Wait for cluster to be fully ready (about 15 minutes)
3. Initiate upgrade to 4.21.0:
rosa upgrade cluster --cluster test-cluster --version 4.21.0
4. Monitor the control plane pods:
oc get pods -n clusters-test-cluster -w
5. Observe kube-apiserver pod status
```
**Validation:**
- Ensure at least one step is provided
- Check that steps are numbered/ordered
- Verify steps are specific enough to follow
### 5. Actual Results
**Prompt:** "What actually happens when you follow those steps?"
**Guidelines:**
- Describe exactly what occurs
- Include error messages (full text)
- Mention symptoms (crashes, hangs, wrong output)
- Include relevant logs or stack traces
- Note timing (immediate, after 5 minutes, etc.)
**Example:**
```
Actual results:
The kube-apiserver pod crashes immediately after the upgrade completes. The pod restarts continuously (CrashLoopBackOff). Error in pod logs:
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x0 pc=0x...]
API requests to the cluster fail with:
Error from server: error dialing backend: dial tcp: lookup kube-apiserver: no such host
```
### 6. Expected Results
**Prompt:** "What should happen instead? What is the expected behavior?"
**Guidelines:**
- Describe the correct behavior
- Be specific about expected state/output
- Contrast with actual results
**Example:**
```
Expected results:
The kube-apiserver pod should start successfully after the upgrade. The pod should be in Running state, and API requests to the cluster should succeed normally.
```
**Validation:**
- Ensure expected results differ from actual results
- Check that expected behavior is clearly stated
### 7. Additional Information
**Prompt:** "Any additional context? (Optional: logs, screenshots, workarounds, related issues)"
**Helpful additions:**
- Full logs or log excerpts
- Screenshots or recordings
- Stack traces
- Related Jira issues or documentation
- Workarounds discovered
- Impact assessment (severity, affected users)
- Environment specifics (region, network config, etc.)
**Example:**
```
Additional info:
- Cluster ID: abc123-def456
- Region: us-east-1
- Full pod logs attached: kube-apiserver.log
- Related issue: OCPBUGS-12340 (similar crash in 4.19→4.20 upgrade)
- Workaround: Rollback to 4.20.0 and cluster recovers
- Affects all ROSA HCP clusters in production
```
## Component and Version Handling
### Auto-Detection
Analyze the bug description for component hints:
- Product names: "OpenShift", "ROSA", "ARO", "HyperShift"
- Component names: "API server", "etcd", "networking", "storage"
- Platform: "AWS", "Azure", "GCP", "bare metal"
### Version Fields
Different projects may use versions differently:
**OCPBUGS:**
- **Affects Version/s** (`versions`): Version where bug was found
- **Target Version** (`customfield_12319940`): Version where fix is targeted
- Never set **Fix Version/s** (`fixVersions`)
**General projects:**
- May only have **Affects Version/s**
- Check project configuration for version fields
### Project-Specific Overrides
If bug is for a known project with specific conventions (e.g., CNTRLPLANE/OCPBUGS), the cntrlplane skill will be invoked automatically and will override defaults.
## Field Validation
Before submitting the bug, validate:
### Required Fields
- ✅ Summary is not empty and is clear
- ✅ Description contains problem description
- ✅ Component is specified (or project doesn't require it)
- ✅ Affects version is specified (if required by project)
### Description Quality
- ✅ "Steps to Reproduce" has at least one step
- ✅ "Actual results" is different from "Expected results"
- ✅ "How reproducible" is specified (Always/Sometimes/Rarely)
### Security
- ✅ No credentials, API keys, or secrets in any field
- ✅ Logs are sanitized (passwords, tokens redacted)
- ✅ Screenshots don't expose sensitive information
## MCP Tool Parameters
### Basic Bug Creation
```python
mcp__atlassian__jira_create_issue(
project_key="<PROJECT_KEY>", # e.g., "OCPBUGS", "MYPROJECT"
summary="<bug summary>",
issue_type="Bug",
description="<formatted bug template>",
components="<component name>", # optional, if required by project
additional_fields={
"versions": [{"name": "<version>"}], # affects version, if supported
# Add other project-specific fields as needed
}
)
```
### With Project-Specific Fields (e.g., OCPBUGS)
```python
mcp__atlassian__jira_create_issue(
project_key="OCPBUGS",
summary="Control plane pods crash on upgrade",
issue_type="Bug",
description="""
h2. Description of problem
Control plane pods crash immediately after upgrading from 4.20 to 4.21.
h2. Version-Release number
4.21.0
h2. How reproducible
Always
h2. Steps to Reproduce
# Create a cluster on 4.20
# Upgrade to 4.21
# Observe control plane pod status
h2. Actual results
Pods enter CrashLoopBackOff state.
h2. Expected results
Pods should start successfully.
h2. Additional info
Logs attached.
""",
components="HyperShift",
additional_fields={
"versions": [{"name": "4.21"}], # affects version
"customfield_12319940": "4.21", # target version
"labels": ["ai-generated-jira"],
"security": {"name": "Red Hat Employee"} # if required
}
)
```
## Jira Description Formatting
Use Jira's native formatting (Wiki markup):
### Headings
```
h1. Main Heading
h2. Subheading
h3. Sub-subheading
```
### Text Formatting
```
*bold text*
_italic text_
{{monospace}}
{quote}quoted text{quote}
```
### Lists
```
* Bullet item 1
* Bullet item 2
** Nested bullet
# Numbered item 1
# Numbered item 2
```
### Code Blocks
```
{code}
command line text or code
{code}
{code:java}
// Language-specific syntax highlighting
public class Example {}
{code}
```
### Links
```
[Link text|http://example.com]
[OCPBUGS-123] // Auto-links to Jira issue
```
## Error Handling
### Missing Required Information
**Scenario:** User doesn't provide required fields.
**Action:**
1. Identify missing required fields
2. Prompt user for each missing field
3. Provide context/examples to help
4. Re-validate before submission
**Example:**
```
Summary is required but not provided. Please provide a brief summary of the bug:
Example: "API server crashes when creating namespaces"
```
### Invalid Version
**Scenario:** Specified version doesn't exist in project.
**Action:**
1. Use `mcp__atlassian__jira_get_project_versions` to fetch valid versions
2. Suggest closest match or list available versions
3. Ask user to confirm or select different version
**Example:**
```
Version "4.21.5" not found for project OCPBUGS.
Available versions: 4.19, 4.20, 4.21, 4.22
Did you mean "4.21"?
```
### Component Required But Not Provided
**Scenario:** Project requires component, but none specified.
**Action:**
1. Ask user which component the bug affects
2. If available, fetch and display component list for project
3. Accept user's component selection
4. Validate component exists before submission
### Security Validation Failure
**Scenario:** Sensitive data detected in bug content.
**Action:**
1. STOP submission immediately
2. Inform user what type of data was detected (without echoing it)
3. Provide guidance on redaction
4. Request sanitized version
**Example:**
```
I detected what appears to be an API token in the "Steps to Reproduce" section.
Please replace with a placeholder like "YOUR_API_TOKEN" or "<redacted>" before proceeding.
```
### MCP Tool Error
**Scenario:** MCP tool returns an error when creating the bug.
**Action:**
1. Parse error message
2. Translate to user-friendly explanation
3. Suggest corrective action
4. Offer to retry
**Common errors:**
- **"Field 'component' is required"** → Prompt for component
- **"Version not found"** → Use version error handling
- **"Permission denied"** → User may lack project permissions, inform them to contact admin
## Examples
### Example 1: Simple Bug
**Input:**
```bash
/jira:create bug MYPROJECT "Login button doesn't work on mobile"
```
**Interactive prompts:**
```
What is the problem? Describe it clearly.
> The login button on the mobile app doesn't respond to taps on iOS devices.
Which version exhibits this issue?
> 2.1.0
How reproducible is this issue?
> Always
What are the exact steps to reproduce?
> 1. Open mobile app on iPhone 13 (iOS 16.5)
> 2. Navigate to login screen
> 3. Tap the "Login" button
> 4. Nothing happens
What actually happens?
> The button doesn't respond to taps. No visual feedback, no navigation.
What should happen instead?
> The button should navigate to the credentials input screen when tapped.
Any additional context?
> Works fine on Android. Only affects iOS.
```
**Result:**
- Issue created in MYPROJECT
- Type: Bug
- Summary: "Login button doesn't work on mobile"
- Description: Formatted with bug template
### Example 2: Bug with Auto-Detection (CNTRLPLANE/OCPBUGS)
**Input:**
```bash
/jira:create bug "ROSA HCP control plane pods crash on upgrade"
```
**Auto-applied (via cntrlplane skill):**
- Project: OCPBUGS (default for bugs)
- Component: HyperShift / ROSA (detected from "ROSA HCP")
- Affects Version: 4.21
- Target Version: 4.21
- Labels: ai-generated-jira
- Security: Red Hat Employee
**Interactive prompts:**
- Bug template sections (same as Example 1)
**Result:**
- Full bug report created with all CNTRLPLANE conventions applied
### Example 3: Bug with All Fields Provided
**Input:**
```bash
/jira:create bug OCPBUGS "etcd pod OOMKilled after 48 hours" --component "HyperShift" --version "4.21"
```
**Minimal prompts:**
- Description of problem
- Steps to reproduce
- Actual/expected results
- Additional info
**Result:**
- Bug created with provided component and version
- Only prompts for description content
## Best Practices Summary
1. **Clear summaries:** One sentence, specific problem
2. **Complete steps:** Exact sequence to reproduce
3. **Specific results:** Include error messages and symptoms
4. **Sanitize content:** Remove all credentials and secrets
5. **Add context:** Logs, environment details, workarounds
6. **Use template:** Follow standard bug template structure
7. **Validate before submit:** Check all required fields populated
## Workflow Summary
1. ✅ Parse command arguments (project, summary, flags)
2. 🔍 Auto-detect component/version from summary keywords
3. ⚙️ Apply project-specific defaults (if applicable)
4. 💬 Interactively collect bug template sections
5. 🔒 Scan for sensitive data
6. ✅ Validate required fields
7. 📝 Format description with Jira markup
8. ✅ Create bug via MCP tool
9. 📤 Return issue key and URL
## See Also
- `/jira:create` - Main command that invokes this skill
- `cntrlplane` skill - CNTRLPLANE/OCPBUGS specific conventions
- Jira documentation on bug workflows

661
skills/create-epic/SKILL.md Normal file
View File

@@ -0,0 +1,661 @@
---
name: Create Jira Epic
description: Implementation guide for creating Jira epics with proper scope and parent linking
---
# Create Jira Epic
This skill provides implementation guidance for creating well-structured Jira epics that organize related stories and tasks into cohesive bodies of work.
## When to Use This Skill
This skill is automatically invoked by the `/jira:create epic` command to guide the epic creation process.
## Prerequisites
- MCP Jira server configured and accessible
- User has permissions to create issues in the target project
- Understanding of the epic scope and related work
## What is an Epic?
An agile epic is:
- A **body of work** that can be broken down into specific items (stories/tasks)
- Based on the needs/requests of customers or end-users
- An important practice for agile and DevOps teams
- A tool to **manage work** at a higher level than individual stories
### Epic Characteristics
Epics should:
- Be **more narrow** than a market problem or feature
- Be **broader** than a user story
- **Fit inside a time box** (quarter/release)
- Stories within the epic should **fit inside a sprint**
- Include **acceptance criteria** that define when the epic is done
### Epic vs Feature vs Story
| 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" |
## Epic Name Field Requirement
**IMPORTANT:** Many Jira configurations require the **epic name** field to be set.
- **Epic Name** = **Summary** (should be identical)
- This is a separate required field in addition to the summary field
- If epic name is missing, epic creation will fail
**MCP Tool Handling:**
- Some projects auto-populate epic name from summary
- Some require explicit epic name field
- Always set epic name = summary to ensure compatibility
## Epic Description Best Practices
### Clear Objective
The epic description should:
- State the overall goal or objective
- Explain the value or benefit
- Identify the target users or stakeholders
- Define the scope (what's included and excluded)
**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
```
### Acceptance Criteria for Epics
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:**
- Broader than story AC (focus on overall capability, not implementation details)
- Measurable outcomes
- User-observable (not technical implementation)
- Typically 3-6 criteria (if more, consider splitting epic)
### Timeboxing
Include timeframe information:
- Target quarter or release
- Key milestones or dependencies
- Known constraints
**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)
```
### Parent Link to Feature
If the epic belongs to a larger feature:
- Link to parent feature using `--parent` flag
- Explain how this epic contributes to the feature
- Reference feature key in description
**Example:**
```
h2. Parent Feature
This epic is part of [PROJ-100] "Advanced cluster observability" and specifically addresses the multi-cluster aggregation capability.
```
## Interactive Epic Collection Workflow
When creating an epic, guide the user through:
### 1. Epic Objective
**Prompt:** "What is the main objective or goal of this epic? What capability will it deliver?"
**Helpful questions:**
- What is the overall goal?
- What high-level capability will be delivered?
- Who will benefit from this epic?
**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.
```
### 2. Epic Scope
**Prompt:** "What is included in this epic? What is explicitly out of scope?"
**Helpful questions:**
- What functionality is included?
- What related work is NOT part of this epic?
- Where are the boundaries?
**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)
```
### 3. Epic Acceptance Criteria
**Prompt:** "What are the high-level outcomes that define this epic as complete?"
**Guidance:**
- Focus on capabilities, not implementation
- Should be measurable/demonstrable
- Typically 3-6 criteria
**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
```
### 4. Timeframe
**Prompt:** "What is the target timeframe for this epic? (quarter, release, or estimated sprints)"
**Example responses:**
- "Q1 2025"
- "OpenShift 4.21"
- "Estimate 6 sprints"
- "Must complete by March 2025"
### 5. Parent Feature (Optional)
**Prompt:** "Is this epic part of a larger feature? If yes, provide the feature key."
**If yes:**
- Validate parent exists
- Confirm parent is a Feature (not another Epic)
- Link epic to parent
## Field Validation
Before submitting the epic, validate:
### Required Fields
- ✅ Summary is clear and describes the capability
- ✅ Epic name field is set (same as summary)
- ✅ Description includes objective
- ✅ Epic acceptance criteria present
- ✅ Timeframe specified
- ✅ Component is specified (if required by project)
- ✅ Target version is set (if required by project)
### Epic Quality
- ✅ Scope is broader than a story, narrower than a feature
- ✅ Can fit in a quarter/release timeframe
- ✅ Has measurable acceptance criteria
- ✅ Clearly identifies target users/stakeholders
- ✅ Defines what's in scope and out of scope
### Parent Validation (if specified)
- ✅ Parent issue exists
- ✅ Parent is a Feature (not Epic or Story)
- ✅ Epic contributes to parent's objective
### Security
- ✅ No credentials, API keys, or secrets in any field
## MCP Tool Parameters
### Basic Epic Creation
```python
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
}
)
```
### With Project-Specific Fields (e.g., CNTRLPLANE)
```python
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"}
}
)
```
### With Parent Feature
```python
mcp__atlassian__jira_create_issue(
project_key="MYPROJECT",
summary="Multi-cluster monitoring dashboard",
issue_type="Epic",
description="<epic content>",
additional_fields={
"customfield_epicname": "Multi-cluster monitoring dashboard",
"parent": {"key": "MYPROJECT-100"} # link to parent feature
}
)
```
## Jira Description Formatting
Use Jira's native formatting (Wiki markup):
### Epic Template Format
```
<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>.
```
## Error Handling
### Epic Name Field Missing
**Scenario:** Epic creation fails due to missing epic name field.
**Action:**
1. Check if project requires epic name field
2. If required, set `customfield_epicname` = summary
3. Retry creation
**Note:** Field ID may vary by Jira instance:
- `customfield_epicname` (common)
- `customfield_10011` (numbered field)
- Check project configuration if standard field names don't work
### Epic Too Large
**Scenario:** Epic seems too large (would take >1 quarter).
**Action:**
1. Suggest splitting into multiple epics
2. Identify natural split points
3. Consider if this should be a Feature instead
**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?
```
### Epic Too Small
**Scenario:** Epic could be completed in one sprint.
**Action:**
1. Suggest creating as a Story instead
2. Explain epic should be multi-sprint effort
**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)
```
### Parent Not a Feature
**Scenario:** User specifies parent, but it's not a Feature.
**Action:**
1. Check parent issue type
2. If parent is Epic or Story, inform user
3. Suggest correction
**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?
```
### Missing Acceptance Criteria
**Scenario:** User doesn't provide epic acceptance criteria.
**Action:**
1. Explain importance of epic AC
2. Ask probing questions
3. Help construct AC
**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"
```
### Security Validation Failure
**Scenario:** Sensitive data detected in epic content.
**Action:**
1. STOP submission
2. Inform user what type of data was detected
3. Ask for redaction
### MCP Tool Error
**Scenario:** MCP tool returns an error when creating the epic.
**Action:**
1. Parse error message
2. Provide user-friendly explanation
3. Suggest corrective action
**Common errors:**
- **"Field 'epic name' is required"** → Set epic name = summary
- **"Invalid parent"** → Verify parent is Feature type
- **"Issue type 'Epic' not available"** → Check if project supports Epics
## Examples
### Example 1: Epic with Full Details
**Input:**
```bash
/jira:create epic CNTRLPLANE "Multi-cluster metrics aggregation"
```
**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
Parent feature? (optional)
> CNTRLPLANE-100
```
**Result:**
- Epic created with complete description
- Linked to parent feature
- All CNTRLPLANE conventions applied
### Example 2: Epic with Auto-Detection
**Input:**
```bash
/jira:create epic CNTRLPLANE "Advanced node pool autoscaling for ARO HCP"
```
**Auto-applied (via cntrlplane skill):**
- Component: HyperShift / ARO (detected from "ARO HCP")
- 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
- Timeframe
**Result:**
- Full epic with ARO component
### Example 3: Standalone Epic (No Parent)
**Input:**
```bash
/jira:create epic MYPROJECT "Improve test coverage for API endpoints"
```
**Result:**
- Epic created without parent
- Standard epic fields applied
- Ready for stories to be linked
## Best Practices Summary
1. **Clear objective:** State what capability will be delivered
2. **Define scope:** Explicitly state what's in and out of scope
3. **Epic AC:** High-level outcomes that define "done"
4. **Right size:** 2-8 sprints, fits in a quarter
5. **Timebox:** Specify target quarter/release
6. **Link to feature:** If part of larger initiative
7. **Target users:** Identify who benefits
8. **Epic name field:** Always set (same as summary)
## Anti-Patterns to Avoid
❌ **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
## Workflow Summary
1. ✅ Parse command arguments (project, summary, flags)
2. 🔍 Auto-detect component from summary keywords
3. ⚙️ Apply project-specific defaults
4. 💬 Interactively collect epic objective and scope
5. 💬 Interactively collect epic acceptance criteria
6. 💬 Collect timeframe and parent link (if applicable)
7. 🔒 Scan for sensitive data
8. ✅ Validate epic size and quality
9. ✅ Set epic name field = summary
10. 📝 Format description with Jira markup
11. ✅ Create epic via MCP tool
12. 📤 Return issue key and URL
## See Also
- `/jira:create` - Main command that invokes this skill
- `create-feature` skill - For larger strategic initiatives
- `create-story` skill - For stories within epics
- `cntrlplane` skill - CNTRLPLANE specific conventions
- Agile epic management best practices

744
skills/create-feature-request/SKILL.md Normal file
View File

@@ -0,0 +1,744 @@
---
name: Create Jira Feature Request
description: Implementation guide for creating Feature Requests in the RFE project
---
# Create Jira Feature Request
This skill provides implementation guidance for creating Feature Requests in the RFE Jira project, which captures customer-driven enhancement requests.
## When to Use This Skill
This skill is automatically invoked by the `/jira:create feature-request RFE` command to guide the feature request creation process.
## Prerequisites
- MCP Jira server configured and accessible
- User has permissions to create issues in the RFE project
- Understanding of the customer need and business justification
- Knowledge of affected components/teams
## What is a Feature Request?
A Feature Request (RFE) is:
- A **customer-driven request** for new functionality or enhancement
- Submitted to the **RFE project** in Jira
- Captures **business requirements** and customer justification
- Links specific **components and teams** that need to implement the request
- Focuses on **what** is needed rather than **how** to implement it
### Feature Request vs Feature vs Story
| Type | Purpose | Project | Example |
|------|---------|---------|---------|
| **Feature Request (RFE)** | Customer request for capability | RFE | "Support for Foo in ProductA managed control planes" |
| Feature | Strategic product objective | CNTRLPLANE, etc. | "Advanced hosted control plane security" |
| Story | Single user-facing functionality | Any | "User can upload custom SSL certificate via console" |
### Feature Request Characteristics
Feature Requests should:
- Clearly state the **customer need** or problem
- Provide **business justification** for the request
- Identify **affected components** and teams
- Be **customer-focused** (what they need, not how to build it)
- Include enough detail for engineering teams to **understand and estimate**
## Feature Request Description Best Practices
### Title
The title should be:
- **Clear and concise** (50-80 characters)
- **Customer-focused** (describes the capability needed)
- **Specific** (not vague or overly broad)
**Good examples:**
```
Support Foo for ProductA managed control planes
Enable pod autoscaling based on custom metrics
Multi-cluster backup and restore for ProductB
```
**Bad examples:**
```
Better security (too vague)
SSL stuff (not specific)
Make autoscaling work better (not clear)
```
### Nature and Description
Clearly describe:
- **What** is being requested (the capability or enhancement)
- **Current limitations** or gaps (what doesn't work today)
- **Desired behavior** (what should happen)
- **Use case** (how customers will use this)
**Good example:**
```
h2. Nature and Description of Request
Customers need the ability to use Foo for ProductA managed control plane endpoints, rather than relying on vendor-provided defaults.
h3. Current Limitation
Today, ProductA clusters use vendor-managed configuration for the API server endpoint. Customers cannot provide their own configuration, which creates issues for:
- Corporate security policies requiring organization-specific settings
- Integration with existing enterprise infrastructure
- Compliance requirements (SOC2, ISO 27001)
h3. Desired Behavior
Customers should be able to:
- Upload their own configuration during cluster creation
- Rotate configuration after cluster creation
- Validate configuration before cluster becomes active
- Receive alerts when configuration changes are needed
h3. Use Case
Enterprise customers with strict security policies need all infrastructure to use internally-managed configuration. This blocks ProductA adoption in regulated industries (finance, healthcare, government) where configuration management is a compliance requirement.
```
**Bad example:**
```
We need better SSL support.
```
### Business Requirements
Explain **why** the customer needs this:
- **Business impact** (what happens without this)
- **Customer segment** affected (who needs this)
- **Regulatory/compliance** drivers (if applicable)
- **Competitive** context (if relevant)
- **Priority** indicators (blocking deals, customer escalations)
**Good example:**
```
h2. Business Requirements
h3. Customer Impact
- **Primary segment**: Enterprise customers in regulated industries (finance, healthcare, government)
- **Affected customers**: 10+ customers have requested this capability
- **Deal blockers**: Multiple active deals blocked by this limitation
- **Escalations**: Several P1 customer escalations due to compliance failures
h3. Regulatory Requirements
- SOC2 Type II compliance requires organization-specific configuration
- ISO 27001 mandates lifecycle management
- Financial services regulations (PCI-DSS) require integration with enterprise infrastructure
- Government contracts require validated configuration chains
h3. Business Justification
Without this capability:
- Cannot close enterprise deals in regulated industries
- Risk losing existing customers to competitors during renewals
- Increasing support burden from compliance audit failures
- Limiting market expansion into high-value segments
h3. Competitive Context
Major competitors (CompetitorA, CompetitorB, CompetitorC) all support this capability for managed Kubernetes control planes. This is a gap that affects product competitive positioning.
```
**Bad example:**
```
Customers need this for security.
```
### Affected Packages and Components
Identify:
- **Teams** that need to implement this (use team names like "HyperShift", "ROSA SRE")
- **Operators** or controllers affected (e.g., "cluster-ingress-operator")
- **Components** in Jira (this will be set as the Component field)
- **Related services** (APIs, CLIs, consoles)
**Good example:**
```
h2. Affected Packages and Components
h3. Teams
- **HyperShift Team**: Control plane infrastructure, configuration management
- **ROSA SRE Team**: Operational validation, configuration rotation
- **OCM Team**: Console and API for configuration upload
- **Networking Team**: Networking and configuration distribution
h3. Technical Components
- **cluster-ingress-operator**: Configuration provisioning and installation
- **hypershift-operator**: Control plane configuration
- **openshift-console**: UI for configuration upload and management
- **rosa CLI**: CLI support for configuration operations
h3. Jira Component
Based on the primary team and technical area, this should be filed under:
**Component**: HyperShift / ProductA
h3. Related Services
- Product API (configuration upload endpoint)
- Configuration management service (validation, storage)
- Control plane API server (configuration installation)
```
**Note:** The "Jira Component" will be used to set the `components` field when creating the issue.
## Interactive Feature Request Collection Workflow
When creating a feature request, guide the user through these specific questions:
### 1. Proposed Title
**Prompt:** "What is the proposed title for this feature request? Make it clear, specific, and customer-focused (50-80 characters)."
**Validation:**
- Not too vague ("Better performance")
- Not too technical ("Implement TLS 1.3 in ingress controller")
- Customer-facing capability
**Example response:**
```
Support Foo for ProductA managed control planes
```
### 2. Nature and Description
**Prompt:** "What is the nature and description of the request? Describe:
- What capability is being requested
- Current limitations
- Desired behavior
- Use case"
**Probing questions if needed:**
- What doesn't work today that should?
- What would you like to be able to do?
- How would customers use this capability?
**Example response:**
```
Customers need to use Foo for ProductA API endpoints instead of vendor-provided defaults.
Current limitation: ProductA only supports vendor-managed configuration, blocking customers with corporate requirements.
Desired behavior: Customers can upload, validate, and rotate custom configuration for the control plane API.
Use case: Enterprise customers in regulated industries (finance, healthcare) need organization-specific configuration for compliance.
```
### 3. Business Requirements
**Prompt:** "Why does the customer need this? List the business requirements, including:
- Customer impact and affected segment
- Regulatory/compliance drivers
- Business justification
- What happens without this capability"
**Helpful questions:**
- Who is asking for this? (customer segment)
- Why is this blocking them? (compliance, policy, competitive)
- What is the business impact? (deals, escalations, churn risk)
- Are there regulatory requirements?
**Example response:**
```
Customer impact:
- 10+ enterprise customers have requested this
- Multiple active deals blocked
- Several P1 escalations from compliance failures
Regulatory requirements:
- SOC2, ISO 27001, PCI-DSS require organization-specific configuration
- Government contracts require validated configuration chains
Business justification:
- Cannot close deals in regulated industries (finance, healthcare, government)
- Competitive gap (CompetitorA, CompetitorB, CompetitorC all support this capability)
- Risk of customer churn during renewals
```
### 4. Affected Packages and Components
**Prompt:** "What packages, components, teams, or operators are affected? This helps route the request to the right teams.
Provide details like:
- Team names (e.g., 'HyperShift', 'Networking', 'OCM')
- Operators (e.g., 'cluster-ingress-operator')
- Technical areas (e.g., 'control plane', 'API server')
- Services (e.g., 'OCM console', 'rosa CLI')"
**Follow-up:** After collecting this information, help the user determine the appropriate **Jira Component** value.
**Component mapping guidance:**
- If **HyperShift**, **ProductA**, or **ProductB** mentioned → Component: "HyperShift"
- If **Networking**, **Ingress** mentioned → Component: "Networking"
- If **OCM**, **Console** mentioned → Component: "OCM"
- If **Multi-cluster**, **Observability** mentioned → Component: "Observability"
- If unclear, ask: "Based on the teams and technical areas mentioned, which component should this be filed under?"
**Example response:**
```
Teams affected:
- HyperShift Team (primary - control plane configuration management)
- ROSA SRE Team (configuration rotation, operations)
- OCM Team (console UI for configuration upload)
- Networking Team (networking configuration distribution)
Operators/components:
- cluster-ingress-operator
- hypershift-operator
- openshift-console
Suggested Jira Component: HyperShift
```
## Field Validation
Before submitting the feature request, validate:
### Required Fields
- ✅ Title is clear, specific, and customer-focused
- ✅ Nature and description explains what is requested
- ✅ Business requirements justify why this is needed
- ✅ Affected components and teams are identified
- ✅ Jira Component is set appropriately
- ✅ Project is set to "RFE"
- ✅ Issue type is "Feature Request"
### Content Quality
- ✅ Describes customer need (not implementation details)
- ✅ Business justification is clear
- ✅ Enough detail for engineering teams to understand
- ✅ No vague statements ("better performance", "more secure")
- ✅ Use case is explained
### Security
- ✅ No credentials, API keys, or secrets in any field
- ✅ No confidential customer information (use anonymized references if needed)
## MCP Tool Parameters
### Basic Feature Request Creation
```python
mcp__atlassian__jira_create_issue(
project_key="RFE",
summary="<title of feature request>",
issue_type="Feature Request",
description="""
<Brief overview of the request>
h2. Nature and Description of Request
<What is being requested - capability, current limitations, desired behavior, use case>
h2. Business Requirements
h3. Customer Impact
* <Customer segment affected>
* <Number of customers requesting>
* <Deals blocked or escalations>
h3. Regulatory/Compliance Requirements (if applicable)
* <Compliance driver 1>
* <Compliance driver 2>
h3. Business Justification
<Why this is important, what happens without it>
h3. Competitive Context (if applicable)
<How competitors handle this, gaps>
h2. Affected Packages and Components
h3. Teams
* <Team 1>: <Responsibility>
* <Team 2>: <Responsibility>
h3. Technical Components
* <Operator/component 1>
* <Operator/component 2>
h3. Related Services
* <Service 1>
* <Service 2>
""",
components="<component name>", # Based on affected teams/areas
additional_fields={
# NOTE: Custom field IDs need to be discovered for RFE project
# Placeholder examples below - replace with actual field IDs
# "customfield_12345": "<customer name>", # If RFE has customer field
# "customfield_67890": "<priority level>", # If RFE has priority field
"labels": ["ai-generated-jira"],
"security": {"name": "Red Hat Employee"}
}
)
```
### Example: Foo Feature Request
```python
mcp__atlassian__jira_create_issue(
project_key="RFE",
summary="Support Foo for ProductA managed control planes",
issue_type="Feature Request",
description="""
Enable customers to use Foo for ProductA managed control plane API server endpoints, replacing the current vendor-managed approach.
h2. Nature and Description of Request
Customers need the ability to use Foo for ProductA API endpoints rather than relying on vendor-provided defaults.
h3. Current Limitation
ProductA clusters currently use vendor-managed configuration for the API server endpoint. Customers cannot provide their own configuration, which creates issues for:
* Corporate security policies requiring organization-specific settings
* Integration with existing enterprise infrastructure
* Compliance requirements (SOC2, ISO 27001, PCI-DSS)
h3. Desired Behavior
Customers should be able to:
* Upload their own configuration during cluster creation
* Rotate custom configuration after cluster creation without cluster downtime
* Validate configuration before cluster becomes active
* Receive proactive alerts when configuration updates are needed (30 days, 7 days)
* View configuration details in product console
h3. Use Case
Enterprise customers with strict security policies need all infrastructure components to use internally-managed configuration. This capability is required for ProductA adoption in regulated industries (finance, healthcare, government) where configuration management is a compliance requirement and external configuration violates security policies.
h2. Business Requirements
h3. Customer Impact
* **Primary segment**: Enterprise customers in regulated industries (finance, healthcare, government, defense)
* **Affected customers**: 10+ enterprise customers have explicitly requested this capability
* **Deal blockers**: Multiple active enterprise deals are currently blocked by this limitation
* **Escalations**: Several Priority 1 customer escalations due to failed compliance audits
h3. Regulatory/Compliance Requirements
* SOC2 Type II compliance requires use of organization-specific configuration with documented lifecycle management
* ISO 27001 certification mandates configuration lifecycle management and infrastructure integration
* PCI-DSS (Payment Card Industry) requires configuration from approved infrastructure
* Government contracts (FedRAMP, DoD) require validated configuration chains
* Industry-specific regulations (HIPAA, GDPR) require organizational control of configuration
h3. Business Justification
Without this capability:
* Cannot close enterprise deals in regulated industries (blocking market expansion)
* Risk losing existing customers to competitors during renewal periods
* Increasing support burden from compliance audit failures and customer escalations
* Limiting addressable market to non-regulated segments
* Missing revenue opportunity in high-value enterprise segments
h3. Competitive Context
All major competitors support this capability for managed Kubernetes control planes:
* CompetitorA: Supports custom configuration via service manager
* CompetitorB: Allows bring-your-own configuration for API server
* CompetitorC: Supports custom configuration for control plane endpoints
This is a competitive gap affecting ProductA positioning in enterprise sales cycles.
h2. Affected Packages and Components
h3. Teams
* **HyperShift Team**: Primary owner - control plane infrastructure, configuration management, rotation logic
* **ROSA SRE Team**: Operational validation, configuration rotation procedures, monitoring and alerting
* **OCM Team**: Console UI for configuration upload, validation, and lifecycle management
* **Networking Team**: Networking configuration, configuration distribution to load balancers
* **Security Team**: Configuration validation, security review, key management
h3. Technical Components
* **hypershift-operator**: Control plane configuration and installation
* **cluster-ingress-operator**: Configuration provisioning for API server
* **openshift-console**: UI components for configuration upload and management
* **rosa CLI**: CLI commands for configuration operations (upload, rotate, view)
* **control-plane-operator**: API server configuration mounting
h3. Related Services
* OCM API: New endpoints for configuration upload, validation, and management
* Configuration storage service: Secure storage for sensitive data (encryption at rest)
* Control plane API server: Configuration installation and serving
* Monitoring and alerting: Configuration monitoring and proactive alerts
h2. Jira Component
**Component**: HyperShift
(Primary team is HyperShift, primary technical area is control plane infrastructure)
""",
components="HyperShift",
additional_fields={
# TODO: Discover actual custom field IDs for RFE project
# These are placeholders - need to query Jira API to get correct field IDs
# Common RFE fields might include:
# - Customer name (customfield_XXXXX)
# - Request priority (customfield_XXXXX)
# - Target release (customfield_XXXXX)
"labels": ["ai-generated-jira", "security", "compliance", "product-a"],
"security": {"name": "Red Hat Employee"}
}
)
```
## Jira Description Formatting
Use Jira's native formatting (Wiki markup):
### Feature Request Template Format
```
<Brief overview>
h2. Nature and Description of Request
<What is being requested>
h3. Current Limitation
<What doesn't work today>
h3. Desired Behavior
<What should work>
h3. Use Case
<How customers will use this>
h2. Business Requirements
h3. Customer Impact
* <Affected segment>
* <Number of requests>
* <Deal impacts>
h3. Regulatory/Compliance Requirements
* <Requirement 1>
* <Requirement 2>
h3. Business Justification
<Why this matters, impact of not having it>
h3. Competitive Context (optional)
<Competitor capabilities, market gaps>
h2. Affected Packages and Components
h3. Teams
* <Team>: <Responsibility>
h3. Technical Components
* <Component/operator>
h3. Related Services
* <Service>
h2. Jira Component
**Component**: <component name>
```
## Error Handling
### Missing Business Justification
**Scenario:** User provides feature request without clear business justification.
**Action:**
1. Explain importance of business requirements
2. Ask probing questions about customer impact
3. Help articulate business case
**Example:**
```
For a Feature Request to be prioritized, we need to understand the business impact.
Can you provide:
1. Who is requesting this? (customer segment, specific customers)
2. Why is it blocking them? (compliance, policy, competitive)
3. What is the business impact? (deals blocked, escalations, churn risk)
4. Are there regulatory requirements driving this?
This helps product management and engineering teams understand priority and urgency.
```
### Vague Description
**Scenario:** Description lacks specifics about what is needed.
**Action:**
1. Identify vague areas
2. Ask clarifying questions
3. Help user be more specific
**Example:**
```
The description "better security" is too vague. Let's be more specific:
1. What security capability is needed? (authentication, encryption, access control)
2. What doesn't work today? (specific limitation or gap)
3. What should work? (desired behavior)
4. How would customers use this? (use case)
For example: "Support custom SSL certificates" is specific and actionable.
```
### Missing Component Information
**Scenario:** User doesn't know which teams or components are affected.
**Action:**
1. Ask about technical area or keywords
2. Provide component mapping guidance
3. Suggest likely component based on description
**Example:**
```
To route this Feature Request correctly, we need to identify the component.
Based on your description mentioning "ProductA control plane" and "configuration", this likely affects:
- **HyperShift Team** (control plane infrastructure)
- **Networking Team** (networking and configuration)
I recommend setting the Jira Component to: **HyperShift**
Does this seem correct based on your understanding?
```
### Security Validation Failure
**Scenario:** Sensitive data detected in feature request content.
**Action:**
1. STOP submission
2. Inform user what type of data was detected
3. Ask for sanitization
**Example:**
```
I detected potentially confidential information (customer names, specific revenue figures).
If this is a public Jira project, please anonymize:
- Use "Enterprise Customer A" instead of actual customer names
- Use ranges ($1-5M) instead of exact revenue figures
- Remove any confidential business information
Would you like to revise the content?
```
### MCP Tool Error
**Scenario:** MCP tool returns an error when creating the feature request.
**Action:**
1. Parse error message
2. Provide user-friendly explanation
3. Suggest corrective action
**Common errors:**
- **"Issue type 'Feature Request' not available"** → Verify RFE project configuration, may need to use "Story" or "Enhancement" instead
- **"Component 'X' does not exist"** → List valid components for RFE project
- **"Field 'customfield_xyz' does not exist"** → Remove custom field, update placeholder in skill
## Examples
### Example 1: Enterprise Customer Request
**Input:**
```bash
/jira:create feature-request RFE "Support Foo for ProductA"
```
**Interactive prompts collect:**
- Title: "Support Foo for ProductA managed control planes"
- Nature: Current limitation with vendor defaults, need for custom configuration, use case for regulated industries
- Business requirements: 10+ customers, multiple blocked deals, compliance drivers
- Components: HyperShift team, cluster-ingress-operator, hypershift-operator
**Result:**
- Complete Feature Request with business justification
- Component: HyperShift
- Routed to appropriate teams for review
### Example 2: Compliance-Driven Request
**Input:**
```bash
/jira:create feature-request RFE "Multi-cluster backup and restore for ProductB"
```
**Auto-detected:**
- Component: HyperShift (ProductB keyword)
- Compliance: GDPR data residency, disaster recovery requirements
**Result:**
- Feature Request with regulatory justification
- Clear business impact (compliance blocking deals)
## Best Practices Summary
1. **Customer-focused:** Describe what customers need, not how to implement it
2. **Business justification:** Always include customer impact, deals, escalations, compliance drivers
3. **Specific and actionable:** Avoid vague descriptions like "better performance" or "more secure"
4. **Component routing:** Identify affected teams and set appropriate Jira component
5. **Regulatory context:** Include compliance requirements if applicable (SOC2, ISO, PCI, HIPAA, etc.)
6. **Competitive awareness:** Note if competitors have this capability
7. **No implementation details:** Focus on "what" is needed, not "how" to build it
## Anti-Patterns to Avoid
❌ **Vague title**
```
"Better security"
```
✅ Use specific capability: "Support Foo for ProductA managed control planes"
❌ **No business justification**
```
"Customers want this"
```
✅ Provide specifics: "10+ customers requested, multiple blocked deals, SOC2 compliance requirement"
❌ **Technical implementation details**
```
"Implement TLS 1.3 in ingress-operator using new controller"
```
✅ Focus on customer need: "Support Foo with modern security standards"
❌ **No component information**
```
"Someone should look at this"
```
✅ Identify teams: "HyperShift team (control plane), Networking team (ingress)"
## Workflow Summary
1. ✅ Parse command arguments (project=RFE, summary)
2. 💬 Interactively collect: Proposed title
3. 💬 Interactively collect: Nature and description of request
4. 💬 Interactively collect: Business requirements (why customer needs this)
5. 💬 Interactively collect: Affected packages and components
6. 🔍 Determine appropriate Jira Component from team/operator information
7. 🔒 Scan for sensitive data (credentials, confidential customer info)
8. ✅ Validate feature request quality and completeness
9. 📝 Format description with Jira Wiki markup
10. ✅ Create Feature Request via MCP tool
11. 📤 Return issue key and URL
## See Also
- `/jira:create` - Main command that invokes this skill
- `create-feature` skill - For strategic product features
- `create-epic` skill - For implementation epics
- RFE project documentation (if available)
## Notes
### Custom Field Discovery
This skill uses placeholder comments for custom fields because the actual field IDs for the RFE project need to be discovered. To find the correct field IDs:
1. **Query Jira API for RFE project metadata:**
```bash
curl -X GET "https://issues.redhat.com/rest/api/2/issue/createmeta?projectKeys=RFE&expand=projects.issuetypes.fields"
```
2. **Look for custom fields** like:
- Customer name
- Request priority
- Target release/version
- Business impact
3. **Update `additional_fields` dictionary** with actual field IDs
**TODO:** Once field IDs are discovered, update the MCP tool examples with real field mappings.

752
skills/create-feature/SKILL.md Normal file
View File

@@ -0,0 +1,752 @@
---
name: Create Jira Feature
description: Implementation guide for creating Jira features representing strategic objectives and market problems
---
# Create Jira Feature
This skill provides implementation guidance for creating Jira features, which represent high-level strategic objectives and solutions to market problems.
## When to Use This Skill
This skill is automatically invoked by the `/jira:create feature` command to guide the feature creation process.
## Prerequisites
- MCP Jira server configured and accessible
- User has permissions to create issues in the target project
- Understanding of the strategic objective and market problem
- Product/business context for the feature
## What is a Feature?
A feature is:
- A **strategic objective** that addresses a market problem or customer need
- **Broader than an epic** - typically contains multiple epics
- A **product capability** that delivers business value
- Aligned with **product roadmap** and business goals
- Typically spans **one or more releases**
### Feature vs Epic vs Story
| Level | Scope | Duration | Example |
|-------|-------|----------|---------|
| **Feature** | Strategic objective, market problem | 1-3 releases (3-9 months) | "Advanced hosted control plane observability" |
| Epic | Specific capability within feature | 1 quarter/release | "Multi-cluster metrics aggregation" |
| Story | Single user-facing functionality | 1 sprint | "View aggregated cluster metrics in dashboard" |
### Feature Characteristics
Features should:
- Address a **specific market problem** or customer need
- Be **more strategic** than implementation details
- Contain **multiple epics** (typically 3-8 epics)
- Deliver **measurable business value**
- Align with **product strategy** and roadmap
- Have clear **success criteria** (not just completion criteria)
## Feature Description Best Practices
### Market Problem
Every feature should clearly state:
- **What customer/business problem** does this solve?
- **Who** is affected by this problem?
- **Why** is solving this problem important now?
- **What happens** if we don't solve it?
**Good example:**
```
h2. Market Problem
Enterprise customers managing multiple ROSA HCP clusters (10+) struggle with operational visibility and control. They must navigate between separate dashboards for each cluster, making it difficult to:
- Identify issues across their cluster fleet
- Track resource utilization trends
- Respond quickly to incidents
- Optimize costs across clusters
This leads to increased operational overhead, slower incident response, and higher support costs. Without a unified observability solution, customers face scalability challenges as their cluster count grows.
```
**Bad example:**
```
We need better observability.
```
### Strategic Value
Explain why this feature matters to the business:
- **Business impact:** Revenue, cost reduction, market differentiation
- **Customer value:** What do customers gain?
- **Competitive advantage:** How does this position us vs competitors?
- **Strategic alignment:** How does this support company/product strategy?
**Example:**
```
h2. Strategic Value
h3. Customer Value
- 60% reduction in time spent on cluster management
- Faster incident detection and response (10min → 2min)
- Better resource optimization across cluster fleet
- Improved operational confidence at scale
h3. Business Impact
- Supports enterprise expansion (critical for deals >100 clusters)
- Reduces support burden (fewer escalations, faster resolution)
- Competitive differentiator (no competitor offers unified HCP observability)
- Enables upsell opportunities (advanced monitoring add-ons)
h3. Strategic Alignment
- Aligns with "Enterprise-First" product strategy for FY2025
- Prerequisite for multi-cluster management capabilities in roadmap
- Supports OpenShift Hybrid Cloud Platform vision
```
### Success Criteria
Define how you'll measure success (not just completion):
- **Adoption metrics:** How many customers will use this?
- **Usage metrics:** How will it be used?
- **Outcome metrics:** What improves as a result?
- **Business metrics:** Revenue, cost, satisfaction impact
**Example:**
```
h2. Success Criteria
h3. Adoption
- 50% of customers with 10+ clusters adopt within 6 months of GA
- Feature enabled by default for new cluster deployments
h3. Usage
- Average of 5 dashboard views per day per customer
- Alert configuration adoption >30% of customers
- API usage growing 20% month-over-month
h3. Outcomes
- 40% reduction in time-to-detect incidents (measured via support metrics)
- Customer satisfaction (CSAT) improvement from 7.2 to 8.5 for multi-cluster users
- 25% reduction in cluster management support tickets
h3. Business
- Closes 10+ enterprise deals blocked by observability gap
- Reduces support costs by $200K annually
- Enables $500K in advanced monitoring upsell revenue
```
## Interactive Feature Collection Workflow
When creating a feature, guide the user through strategic thinking:
### 1. Market Problem
**Prompt:** "What customer or market problem does this feature solve? Be specific about who is affected and why it matters."
**Probing questions:**
- Who has this problem? (customer segment, user type)
- What pain do they experience today?
- What is the impact of not solving this?
- Why is solving this important now?
**Example response:**
```
Enterprise customers with large ROSA HCP deployments (50+ clusters) struggle with operational visibility. They must manage each cluster separately, leading to slow incident response, difficulty tracking compliance, and high operational overhead. This is blocking large enterprise deals and causing customer escalations.
```
### 2. Proposed Solution
**Prompt:** "How will this feature solve the problem? What capability will be delivered?"
**Example response:**
```
Deliver a unified observability platform for ROSA HCP that aggregates metrics, logs, and events across all clusters in a customer's fleet. Provide centralized dashboards, fleet-wide alerting, and compliance reporting.
```
### 3. Strategic Value
**Prompt:** "Why is this strategically important? What business value does it deliver?"
**Helpful questions:**
- What business impact will this have? (revenue, cost, market position)
- How does this align with product strategy?
- What competitive advantage does this provide?
- What customer value is delivered?
**Example response:**
```
Customer value: 50% reduction in cluster management time
Business impact: Unblocks $5M in enterprise deals, reduces support costs
Competitive advantage: No competitor offers unified HCP observability
Strategic alignment: Critical for enterprise market expansion
```
### 4. Success Criteria
**Prompt:** "How will you measure success? What metrics will tell you this feature achieved its goals?"
**Categories to consider:**
- Adoption (who/how many use it)
- Usage (how they use it)
- Outcomes (what improves)
- Business (revenue, cost, satisfaction)
**Example response:**
```
Adoption: 50% of enterprise customers within 6 months
Usage: Daily active usage by SREs in 80% of adopting customers
Outcomes: 40% faster incident detection
Business: Closes 15+ blocked enterprise deals
```
### 5. Scope and Epics
**Prompt:** "What are the major components or epics within this feature?"
**Identify 3-8 major work streams:**
**Example response:**
```
1. Multi-cluster metrics aggregation
2. Unified observability dashboard
3. Fleet-wide alerting and automation
4. Compliance and audit reporting
5. API and CLI for programmatic access
6. Documentation and enablement
```
### 6. Timeline and Milestones
**Prompt:** "What is the timeline? What are key milestones?"
**Example response:**
```
Timeline: 9 months (3 releases)
Milestones:
- Q1 2025: MVP metrics aggregation (Epic 1)
- Q2 2025: Dashboard and alerting (Epics 2-3)
- Q3 2025: Compliance, API, GA (Epics 4-6)
```
## Field Validation
Before submitting the feature, validate:
### Required Fields
- ✅ Summary clearly states the strategic objective
- ✅ Description includes market problem
- ✅ Strategic value articulated
- ✅ Success criteria defined (measurable)
- ✅ Component is specified (if required by project)
- ✅ Target version/release is set (if required)
### Feature Quality
- ✅ Addresses a real market problem
- ✅ Strategic value is clear
- ✅ Success criteria are measurable
- ✅ Scope is larger than an epic (multi-epic)
- ✅ Timeline is realistic (1-3 releases)
- ✅ Aligns with product strategy
### Security
- ✅ No credentials, API keys, or secrets in any field
- ✅ No confidential business information (if public project)
## MCP Tool Parameters
### Basic Feature Creation
```python
mcp__atlassian__jira_create_issue(
project_key="<PROJECT_KEY>",
summary="<feature summary>",
issue_type="Feature",
description="""
<Brief overview of the feature>
h2. Market Problem
<Describe the customer/business problem this solves>
h2. Proposed Solution
<Describe the capability/solution being delivered>
h2. Strategic Value
h3. Customer Value
* <Customer benefit 1>
* <Customer benefit 2>
h3. Business Impact
* <Business impact 1>
* <Business impact 2>
h3. Strategic Alignment
<How this aligns with product strategy>
h2. Success Criteria
h3. Adoption
* <Adoption metric 1>
h3. Outcomes
* <Outcome metric 1>
h3. Business
* <Business metric 1>
h2. Scope
h3. Epics (Planned)
* Epic 1: <epic name>
* Epic 2: <epic name>
* Epic 3: <epic name>
h2. Timeline
* Target: <release/timeframe>
* Key milestones: <major deliverables>
""",
components="<component name>", # if required
additional_fields={
# Add project-specific fields
}
)
```
### With Project-Specific Fields (e.g., CNTRLPLANE)
```python
mcp__atlassian__jira_create_issue(
project_key="CNTRLPLANE",
summary="Advanced observability for hosted control planes",
issue_type="Feature",
description="""
Deliver unified observability capabilities for ROSA and ARO hosted control planes, enabling enterprise customers to manage large cluster fleets with centralized monitoring, alerting, and compliance reporting.
h2. Market Problem
Enterprise customers managing multiple ROSA HCP clusters (50+) face significant operational challenges:
* Must navigate separate dashboards for each cluster (time-consuming, error-prone)
* Cannot track compliance posture across cluster fleet
* Slow incident detection and response (10-30 minutes to identify cross-cluster issues)
* Difficulty optimizing resources and costs across clusters
* High operational overhead preventing scaling to larger deployments
This problem affects our largest customers and is blocking expansion into enterprise segments. Competitors are beginning to offer fleet management capabilities, creating competitive pressure.
h2. Proposed Solution
Build a comprehensive observability platform for hosted control planes that provides:
* Centralized metrics aggregation across all customer clusters
* Unified dashboards for cluster health, performance, and capacity
* Fleet-wide alerting with intelligent cross-cluster correlation
* Compliance and audit reporting across cluster fleet
* APIs and CLI for programmatic access and automation
* Integration with existing customer monitoring tools
h2. Strategic Value
h3. Customer Value
* 60% reduction in time spent on cluster operational tasks
* 80% faster incident detection and response (30min → 6min)
* Improved compliance posture with automated reporting
* Confidence to scale to 100+ clusters
* Better resource optimization (20% cost savings through right-sizing)
h3. Business Impact
* Unblocks $5M in enterprise pipeline (15+ deals require this capability)
* Reduces support escalations by 40% (better self-service visibility)
* Competitive differentiator (no competitor offers unified HCP observability at this level)
* Enables $500K annual upsell revenue (advanced monitoring add-ons)
* Improves customer retention (reducing churn in enterprise segment)
h3. Competitive Advantage
* First-to-market with truly unified HCP observability
* Deep integration with OpenShift ecosystem
* AI-powered insights (future capability)
h3. Strategic Alignment
* Aligns with "Enterprise-First" product strategy for FY2025
* Supports "Hybrid Cloud Platform" vision
* Prerequisite for future multi-cluster management capabilities on roadmap
* Enables shift to "fleet management" business model
h2. Success Criteria
h3. Adoption
* 50% of customers with 10+ clusters adopt within 6 months of GA
* Feature enabled by default for all new ROSA HCP deployments
* 30% adoption in ARO HCP customer base within 9 months
h3. Usage
* Daily active usage by SREs in 80% of adopting customers
* Average 10+ dashboard views per customer per day
* Alert configuration adoption >40% of customers
* API usage growing 25% month-over-month
h3. Outcomes
* 40% reduction in time-to-detect incidents (measured via support metrics)
* 50% reduction in time-to-resolve incidents (via support ticket analysis)
* Customer satisfaction (CSAT) improvement from 7.2 to 8.5 for multi-cluster customers
* 30% reduction in cluster management support tickets
h3. Business Metrics
* Close 15 blocked enterprise deals ($5M+ in ARR)
* Reduce support costs by $250K annually
* Generate $500K in upsell revenue (advanced monitoring)
* Improve enterprise customer retention by 15%
h2. Scope
h3. Epics (Planned)
* Epic 1: Multi-cluster metrics aggregation infrastructure
* Epic 2: Unified observability dashboard and visualization
* Epic 3: Fleet-wide alerting and intelligent correlation
* Epic 4: Compliance and audit reporting
* Epic 5: API and CLI for programmatic access
* Epic 6: Customer monitoring tool integrations (Datadog, Splunk)
* Epic 7: Documentation, training, and customer enablement
h3. Out of Scope (Future Considerations)
* Log aggregation (separate feature planned for 2026)
* AI-powered predictive analytics (follow-on feature)
* Support for standalone OpenShift clusters (not HCP)
* Cost optimization recommendations (different feature)
h2. Timeline
* Total duration: 9 months (3 releases)
* Target GA: Q3 2025 (OpenShift 4.23)
h3. Milestones
* Q1 2025 (4.21): MVP metrics aggregation, basic dashboard (Epics 1-2)
* Q2 2025 (4.22): Alerting, compliance reporting (Epics 3-4)
* Q3 2025 (4.23): API, integrations, GA (Epics 5-7)
h2. Dependencies
* Centralized metrics storage infrastructure ([CNTRLPLANE-50])
* Cluster registration and inventory service ([CNTRLPLANE-75])
* Identity and access management for multi-cluster ([CNTRLPLANE-120])
h2. Risks and Mitigation
h3. Risks
* Performance degradation with >500 clusters (scalability testing needed)
* Integration complexity with third-party monitoring tools
* Customer adoption if migration from existing tools is complex
h3. Mitigation
* Performance benchmarking sprint in Epic 1
* Partner early with Datadog/Splunk on integration design
* Provide migration tools and dedicated customer success support
""",
components="HyperShift",
additional_fields={
"customfield_12319940": "openshift-4.21", # target version (initial)
"labels": ["ai-generated-jira", "observability", "enterprise"],
"security": {"name": "Red Hat Employee"}
}
)
```
## Jira Description Formatting
Use Jira's native formatting (Wiki markup):
### Feature Template Format
```
<Brief feature overview>
h2. Market Problem
<Detailed description of customer/business problem>
<Who is affected, what pain they experience, impact of not solving>
h2. Proposed Solution
<Description of the capability/solution being delivered>
h2. Strategic Value
h3. Customer Value
* <Benefit 1>
* <Benefit 2>
h3. Business Impact
* <Impact 1>
* <Impact 2>
h3. Competitive Advantage
<How this differentiates us>
h3. Strategic Alignment
<How this supports product/company strategy>
h2. Success Criteria
h3. Adoption
* <Adoption metrics>
h3. Usage
* <Usage metrics>
h3. Outcomes
* <Customer outcome metrics>
h3. Business Metrics
* <Revenue, cost, satisfaction metrics>
h2. Scope
h3. Epics (Planned)
* Epic 1: <name>
* Epic 2: <name>
* Epic 3: <name>
h3. Out of Scope
* <Related work NOT in this feature>
h2. Timeline
* Total duration: <timeframe>
* Target GA: <date/release>
h3. Milestones
* <Quarter/Release>: <deliverable>
* <Quarter/Release>: <deliverable>
h2. Dependencies (if any)
* [PROJ-XXX] - <dependency description>
h2. Risks and Mitigation (optional)
h3. Risks
* <Risk 1>
* <Risk 2>
h3. Mitigation
* <Mitigation strategy 1>
* <Mitigation strategy 2>
```
## Error Handling
### Feature Too Small
**Scenario:** Feature could be accomplished as a single epic.
**Action:**
1. Suggest creating as Epic instead
2. Explain feature should be multi-epic effort
**Example:**
```
This feature seems small enough to be a single Epic (1-2 months, single capability).
Features should typically:
- Contain 3-8 epics
- Span multiple releases (6-12 months)
- Address strategic market problem
Would you like to create this as an Epic instead? (yes/no)
```
### Missing Strategic Context
**Scenario:** User doesn't provide market problem or strategic value.
**Action:**
1. Explain importance of strategic framing
2. Ask probing questions
3. Help articulate business case
**Example:**
```
For a feature, we need to understand the strategic context:
1. What market problem does this solve?
2. Why is this strategically important to the business?
3. What value do customers get?
These help stakeholders understand why we're investing in this feature.
Let's start with: What customer problem does this solve?
```
### Vague Success Criteria
**Scenario:** Success criteria are vague or not measurable.
**Action:**
1. Identify vague criteria
2. Ask for specific metrics
3. Suggest measurable alternatives
**Example:**
```
Success criteria should be measurable. "Feature is successful" is too vague.
Instead, consider metrics like:
- Adoption: "50% of enterprise customers within 6 months"
- Usage: "10+ daily dashboard views per customer"
- Outcomes: "40% faster incident response time"
- Business: "Close 10 blocked deals worth $3M"
What specific metrics would indicate success for this feature?
```
### No Epic Breakdown
**Scenario:** User doesn't identify component epics.
**Action:**
1. Explain features are delivered through epics
2. Help identify major work streams
3. Suggest 3-8 epic areas
**Example:**
```
Features are typically delivered through 3-8 epics. What are the major components or work streams?
For observability, typical epics might be:
1. Metrics collection infrastructure
2. Dashboard and visualization
3. Alerting system
4. Reporting capabilities
5. API development
6. Documentation
What would be the major components for your feature?
```
### Security Validation Failure
**Scenario:** Sensitive data detected in feature content.
**Action:**
1. STOP submission
2. Inform user what type of data was detected
3. Ask for redaction
**Example:**
```
I detected confidential business information (customer names, revenue figures).
If this is a public Jira project, please sanitize:
- Use "Enterprise Customer A" instead of actual customer names
- Use ranges ($1-5M) instead of exact revenue figures
```
### MCP Tool Error
**Scenario:** MCP tool returns an error when creating the feature.
**Action:**
1. Parse error message
2. Provide user-friendly explanation
3. Suggest corrective action
**Common errors:**
- **"Issue type 'Feature' not available"** → Check if project supports Features
- **"Field 'customfield_xyz' does not exist"** → Remove unsupported custom field
## Examples
### Example 1: Complete Feature
**Input:**
```bash
/jira:create feature CNTRLPLANE "Advanced hosted control plane observability"
```
**Interactive prompts collect:**
- Market problem (enterprise customer pain)
- Strategic value (business impact, customer value)
- Success criteria (measurable metrics)
- Epic breakdown (7 major components)
- Timeline (9 months, 3 releases)
**Result:**
- Complete feature with strategic framing
- All CNTRLPLANE conventions applied
- Ready for epic planning
### Example 2: Feature with Component Detection
**Input:**
```bash
/jira:create feature CNTRLPLANE "Multi-cloud cost optimization for ROSA and ARO HCP"
```
**Auto-detected:**
- Component: HyperShift (affects both ROSA and ARO)
- Target version: openshift-4.21
**Result:**
- Feature with appropriate component
- Multi-platform scope
## Best Practices Summary
1. **Strategic framing:** Always articulate market problem and business value
2. **Measurable success:** Define specific metrics for adoption, usage, outcomes, business
3. **Multi-epic scope:** Feature should contain 3-8 epics
4. **Customer-focused:** Describe value from customer perspective
5. **Business case:** Clear ROI or strategic justification
6. **Realistic timeline:** 1-3 releases (6-12 months typical)
7. **Risk awareness:** Identify and mitigate known risks
## Anti-Patterns to Avoid
❌ **Feature is actually an epic**
```
"Multi-cluster dashboard" (single capability, 1 epic)
```
✅ Too small, create as Epic
❌ **No strategic context**
```
"Build monitoring system"
```
✅ Must explain market problem and business value
❌ **Vague success criteria**
```
"Feature is successful when customers like it"
```
✅ Use measurable metrics: "50% adoption, 8.5 CSAT score, $2M revenue"
❌ **Technical implementation as feature**
```
"Migrate to Kubernetes operator pattern"
```
✅ Technical work should be epic/task. Features describe customer-facing value.
## Workflow Summary
1. ✅ Parse command arguments (project, summary)
2. 🔍 Auto-detect component from summary keywords
3. ⚙️ Apply project-specific defaults
4. 💬 Interactively collect market problem
5. 💬 Interactively collect strategic value
6. 💬 Interactively collect success criteria
7. 💬 Collect epic breakdown and timeline
8. 🔒 Scan for sensitive data
9. ✅ Validate feature quality and scope
10. 📝 Format description with Jira markup
11. ✅ Create feature via MCP tool
12. 📤 Return issue key and URL
## See Also
- `/jira:create` - Main command that invokes this skill
- `create-epic` skill - For epics within features
- `cntrlplane` skill - CNTRLPLANE specific conventions
- Product management and roadmap planning resources

808
skills/create-release-note/SKILL.md Normal file
View File

@@ -0,0 +1,808 @@
---
name: Create Release Note
description: Detailed implementation guide for generating bug fix release notes from Jira and GitHub PRs
---
# Create Release Note
This skill provides detailed step-by-step implementation guidance for the `/jira:create-release-note` command, which automatically generates bug fix release notes by analyzing Jira bug tickets and their linked GitHub pull requests.
## When to Use This Skill
This skill is automatically invoked by the `/jira:create-release-note` command and should not be called directly by users.
## Prerequisites
- MCP Jira server configured and accessible
- GitHub CLI (`gh`) installed and authenticated
- User has read access to the Jira bug
- User has write access to Release Note fields in Jira
- User has read access to linked GitHub repositories
## Implementation Steps
### Step 1: Fetch and Validate Jira Bug
**Objective**: Retrieve the bug ticket and validate it's appropriate for release note generation.
**Actions**:
1. **Fetch the bug using MCP**:
```
mcp__atlassian__jira_get_issue(
issue_key=<issue-key>,
fields="summary,description,issuetype,status,issuelinks,customfield_12320850,customfield_12317313,comment"
)
```
2. **Parse the response**:
- Extract `issuetype.name` - verify it's "Bug"
- Extract `description` - full bug description text
- Extract `issuelinks` - array of linked issues
- Extract `customfield_12320850` - current Release Note Type (if already set)
- Extract `customfield_12317313` - current Release Note Text (if already set)
- Extract `comment.comments` - array of comment objects
3. **Validate issue type**:
- If `issuetype.name != "Bug"`, show warning:
```
Warning: {issue-key} is not a Bug (it's a {issuetype.name}).
Release notes are typically for bugs. Continue anyway? (yes/no)
```
- If user says no, exit gracefully
4. **Check if release note already exists**:
- If `customfield_12317313` is not empty, show warning:
```
This bug already has a release note:
---
{existing release note}
---
Do you want to regenerate it? (yes/no)
```
- If user says no, exit gracefully
### Step 2: Parse Bug Description for Cause and Consequence
**Objective**: Extract the required Cause and Consequence sections from the bug description.
**Bug Description Format**:
Jira bug descriptions often follow this structure:
```
Description of problem:
{code:none}
<problem description>
{code}
Cause:
{code:none}
<root cause>
{code}
Consequence:
{code:none}
<impact>
{code}
Version-Release number of selected component (if applicable):
...
How reproducible:
...
Steps to Reproduce:
...
Actual results:
...
Expected results:
...
```
**Parsing Strategy**:
1. **Look for "Cause:" section**:
- Search for the string "Cause:" (case-insensitive)
- Extract text between "Cause:" and the next major section
- Remove Jira markup: `{code:none}`, `{code}`, etc.
- Trim whitespace
2. **Look for "Consequence:" section**:
- Search for the string "Consequence:" (case-insensitive)
- Extract text between "Consequence:" and the next major section
- Remove Jira markup
- Trim whitespace
3. **Alternative patterns**:
- Some bugs may use "Root Cause:" instead of "Cause:"
- Some bugs may use "Impact:" instead of "Consequence:"
- Try variations if exact match not found
4. **Handle missing sections**:
- If Cause is missing:
```
Bug description is missing the "Cause" section.
Would you like to:
1. Provide the Cause interactively
2. Update the bug description in Jira first
3. Cancel
```
- If Consequence is missing:
```
Bug description is missing the "Consequence" section.
Would you like to:
1. Provide the Consequence interactively
2. Update the bug description in Jira first
3. Cancel
```
5. **Interactive input** (if user chooses option 1):
- Prompt: "What is the root cause of this bug?"
- Collect user input
- Use as Cause value
- Repeat for Consequence if needed
**Example Parsing**:
Input:
```
Description of problem:
{code:none}
The control plane operator crashes when CloudProviderConfig.Subnet is not specified
{code}
Cause:
{code:none}
hostedcontrolplane controller crashes when hcp.Spec.Platform.AWS.CloudProviderConfig.Subnet.ID is undefined
{code}
Consequence:
{code:none}
control-plane-operator enters a crash loop
{code}
```
Output:
```
Cause: "hostedcontrolplane controller crashes when hcp.Spec.Platform.AWS.CloudProviderConfig.Subnet.ID is undefined"
Consequence: "control-plane-operator enters a crash loop"
```
### Step 3: Extract Linked GitHub PRs
**Objective**: Find all GitHub PR URLs associated with this bug.
**Sources to check** (in priority order):
1. **Remote Links** (Primary source - web links in Jira):
- Check the Jira issue response for web links
- Field name varies: `remotelinks`, or `issuelinks` with outward GitHub PR links
- Extract GitHub PR URLs matching pattern: `https://github\.com/[\w-]+/[\w-]+/pull/\d+`
- **IMPORTANT**: Never use `gh issue view {JIRA-KEY}` - Jira keys are NOT GitHub issue numbers
2. **Bug Description**:
- Scan the `description` field for GitHub PR URLs
- Use regex: `https://github\.com/([\w-]+)/([\w-]+)/pull/(\d+)`
- Extract and parse all matches
- **IMPORTANT**: Only extract full PR URLs, not issue references
3. **Bug Comments**:
- Iterate through `comment.comments` array
- For each comment, scan `body` field for GitHub PR URLs
- Use same regex pattern
- Extract all matches
4. **Search by bug number** (Fallback if no PR URLs found):
- If no PRs found via links, search GitHub for PRs mentioning the bug
- **For OCPBUGS**: Try common OpenShift repos:
```bash
for repo in "openshift/hypershift" "openshift/cluster-api-provider-aws" "openshift/origin"; do
gh pr list --repo "$repo" --search "{issue-key} in:title,body" --state all --limit 10 --json number,url,title
done
```
- Display found PRs and ask user to confirm which are relevant:
```
Found PRs mentioning {issue-key}:
1. openshift/hypershift#4567 - Fix panic when CloudProviderConfig.Subnet is undefined
2. openshift/hypershift#4568 - Add tests for Subnet validation
Which PRs should be included in the release note? (enter numbers separated by commas, or 'all')
```
- **IMPORTANT**: Never use `gh issue view {JIRA-KEY}` - this will fail
**URL Parsing**:
For each found URL `https://github.com/openshift/hypershift/pull/4567`:
- Extract `org`: "openshift"
- Extract `repo`: "hypershift"
- Extract `pr_number`: "4567"
- Store as: `{"url": "...", "repo": "openshift/hypershift", "number": "4567"}`
**Deduplication**:
- Keep only unique PR URLs
- If same PR is mentioned multiple times, include it only once
**Validation**:
- If no PRs found after all attempts:
```
No GitHub PRs found linked to {issue-key}.
Please link at least one PR to generate release notes.
How to link PRs in Jira:
1. Edit the bug in Jira
2. Add a web link to the GitHub PR URL
3. Or mention the PR URL in a comment
4. Then run this command again
```
Exit without updating the ticket.
**Example**:
Found PRs:
```
[
{
"url": "https://github.com/openshift/hypershift/pull/4567",
"repo": "openshift/hypershift",
"number": "4567"
},
{
"url": "https://github.com/openshift/hypershift/pull/4568",
"repo": "openshift/hypershift",
"number": "4568"
}
]
```
### Step 4: Analyze Each GitHub PR
**Objective**: Extract Fix, Result, and Workaround information from each linked PR.
**For each PR in the list**:
#### 4.1: Fetch PR Details
**Command**:
```bash
gh pr view {number} --json body,title,commits,url,state --repo {repo}
```
**Error handling**:
```bash
if ! gh pr view {number} --json body,title,commits,url,state --repo {repo} 2>/dev/null; then
echo "Warning: Unable to access PR {url}"
echo "Verify the PR exists and you have permissions."
# Skip this PR, continue with next
fi
```
**Expected output** (JSON):
```json
{
"body": "This PR fixes the panic when CloudProviderConfig.Subnet is not specified...",
"title": "Fix panic when CloudProviderConfig.Subnet is not specified",
"commits": [
{
"messageHeadline": "Add nil check for Subnet field",
"messageBody": "This prevents the controller from crashing..."
}
],
"url": "https://github.com/openshift/hypershift/pull/4567",
"state": "MERGED"
}
```
**Parse and store**:
- `title`: PR title (short summary)
- `body`: Full PR description
- `commits`: Array of commit objects with messages
- `state`: PR state (MERGED, OPEN, CLOSED)
#### 4.2: Fetch PR Diff
**Command**:
```bash
gh pr diff {number} --repo {repo}
```
**Purpose**: Understand what code was actually changed
**Analysis strategy**:
- Look for added lines (starting with `+`)
- Identify key changes:
- New error handling (`if err != nil`)
- New validation checks (`if x == nil`)
- New return statements
- New error messages
- Don't include the entire diff in the release note
- Summarize the nature of changes
**Example diff analysis**:
```diff
+if hcp.Spec.Platform.AWS.CloudProviderConfig.Subnet == nil {
+ return fmt.Errorf("Subnet configuration is required")
+}
```
**Summary**: "Added nil check for CloudProviderConfig.Subnet field"
#### 4.3: Fetch PR Comments
**Command**:
```bash
gh pr view {number} --json comments --repo {repo}
```
**Expected output** (JSON):
```json
{
"comments": [
{
"author": {"login": "reviewer1"},
"body": "This looks good. The nil check will prevent the crash."
},
{
"author": {"login": "author"},
"body": "Yes, and I also added a more descriptive error message."
}
]
}
```
**Analysis strategy**:
- Look for mentions of:
- "workaround"
- "temporary fix"
- "until this is merged"
- "users can work around this by..."
- Extract workaround information if found
- Look for clarifications about the fix
- Ignore unrelated discussion
#### 4.4: Synthesize PR Analysis
**Combine all sources** (title, body, commits, diff, comments) to extract:
**Fix** (what was changed):
- Prefer: PR body description of the fix
- Fallback: PR title + commit message summaries
- Focus on: What code/configuration was modified
- Keep concise: 1-3 sentences
- Avoid: Implementation details (specific function names, line numbers)
**Example Fix**:
```
Added nil check for CloudProviderConfig.Subnet before accessing Subnet.ID field to prevent nil pointer dereference
```
**Result** (outcome after the fix):
- Prefer: PR body description of expected behavior
- Fallback: Inverse of the bug's "Actual results"
- Focus on: What changed for users
- Keep concise: 1-2 sentences
**Example Result**:
```
The control-plane-operator no longer crashes when CloudProviderConfig.Subnet is not specified
```
**Workaround** (temporary solution before fix):
- Only include if explicitly mentioned in PR or comments
- Look for keywords: "workaround", "temporary", "manually"
- If not found: Omit this section entirely
**Example Workaround** (if found):
```
Users can manually specify a Subnet value in the HostedCluster spec to avoid the crash
```
### Step 5: Combine Multiple PRs
**Objective**: If multiple PRs are linked, synthesize them into a single coherent release note.
**Scenarios**:
#### Scenario A: Multiple PRs with different fixes
Example:
- PR #123: Fixes nil pointer crash
- PR #456: Adds better error message
- PR #789: Adds validation tests
**Strategy**: Combine all fixes into a narrative
```
Fix: Added nil check for CloudProviderConfig.Subnet field (PR #123), improved error messaging for missing configuration (PR #456), and added validation tests to prevent regression (PR #789)
```
#### Scenario B: Multiple PRs for same fix (backports)
Example:
- PR #123: Fix for main branch
- PR #456: Backport to release-4.20
- PR #789: Backport to release-4.19
**Strategy**: Mention the fix once, note the backports
```
Fix: Added nil check for CloudProviderConfig.Subnet field (backported to 4.20 and 4.19)
```
#### Scenario C: Multiple PRs with conflicting descriptions
Example:
- PR #123 says: "Fixed by adding validation"
- PR #456 says: "Fixed by removing the field access"
**Strategy**: Analyze the code diffs to determine what actually happened, or ask user:
```
Found multiple PRs with different fix descriptions:
- PR #123: "Fixed by adding validation"
- PR #456: "Fixed by removing the field access"
Which description is more accurate, or should I combine them?
```
### Step 6: Format Release Note
**Objective**: Create the final release note text following the standard template.
**Template**:
```
Cause: {cause from Jira}
Consequence: {consequence from Jira}
Fix: {synthesized from PRs}
Result: {synthesized from PRs}
Workaround: {synthesized from PRs - optional}
```
**Formatting rules**:
- Each line starts with the field name followed by a colon and space
- No blank lines between fields
- Workaround field is optional - omit if no workaround exists
- Keep each field concise but complete
- Use proper capitalization and punctuation
**Example output**:
```
Cause: hostedcontrolplane controller crashes when hcp.Spec.Platform.AWS.CloudProviderConfig.Subnet.ID is undefined
Consequence: control-plane-operator enters a crash loop
Fix: Added nil check for CloudProviderConfig.Subnet before accessing Subnet.ID field
Result: The control-plane-operator no longer crashes when CloudProviderConfig.Subnet is not specified
```
### Step 7: Security Validation
**Objective**: Scan the release note text for sensitive data before submission.
**Patterns to detect**:
1. **API Tokens and Keys**:
- Pattern: `(sk|pk)_[a-zA-Z0-9]{20,}`
- Pattern: `ghp_[a-zA-Z0-9]{36}`
- Pattern: `gho_[a-zA-Z0-9]{36}`
- Pattern: `github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59}`
2. **AWS Credentials**:
- Pattern: `AKIA[0-9A-Z]{16}`
- Pattern: `aws_access_key_id\s*=\s*[A-Z0-9]+`
- Pattern: `aws_secret_access_key\s*=\s*[A-Za-z0-9/+=]+`
3. **Passwords in URLs**:
- Pattern: `https?://[^:]+:[^@]+@`
- Example: `https://user:password@example.com`
4. **JWT Tokens**:
- Pattern: `eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+`
5. **SSH Private Keys**:
- Pattern: `-----BEGIN (RSA|OPENSSH|DSA|EC|PGP) PRIVATE KEY-----`
6. **Kubernetes Secrets**:
- Pattern: `[a-zA-Z0-9+/]{40,}==?` (base64 encoded secrets)
- Context: If appears after "token:", "secret:", "password:"
**Validation logic**:
```python
sensitive_patterns = {
"API Token": r"(sk|pk)_[a-zA-Z0-9]{20,}",
"GitHub Token": r"gh[po]_[a-zA-Z0-9]{36}",
"AWS Access Key": r"AKIA[0-9A-Z]{16}",
"URL with credentials": r"https?://[^:]+:[^@]+@",
"JWT Token": r"eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+",
"Private Key": r"-----BEGIN .* PRIVATE KEY-----"
}
for name, pattern in sensitive_patterns.items():
if re.search(pattern, release_note_text):
print(f"Security validation failed!")
print(f"Detected what appears to be {name} in the release note text.")
print(f"Please review the source PRs and remove any credentials.")
exit(1)
```
**If validation fails**:
```
Security validation failed!
Detected what appears to be an API token in the release note text.
This may have come from:
- PR description
- Commit messages
- Code changes (diff)
- PR comments
Please review the source PRs and remove any credentials before proceeding.
Use placeholder values instead:
- YOUR_API_KEY
- <redacted>
- ********
Aborting release note creation.
```
### Step 8: Select Release Note Type
**Objective**: Determine the appropriate Release Note Type for this bug.
**Available types** (from Jira dropdown):
1. Bug Fix
2. Release Note Not Required
3. Known Issue
4. Enhancement
5. Rebase
6. Technology Preview
7. Deprecated Functionality
8. CVE
**Auto-detection strategy**:
1. **For OCPBUGS**: Default suggestion is "Bug Fix" (most common)
2. **Check for CVE references**:
- If bug description or PRs mention "CVE-" → Suggest "CVE"
3. **Check for deprecation**:
- If PRs mention "deprecated", "deprecating", "removing" → Suggest "Deprecated Functionality"
4. **Check for new features**:
- If PRs add significant new functionality → Suggest "Enhancement"
- Though typically bugs should be "Bug Fix"
5. **Check for known issues**:
- If PRs don't actually fix the issue, just document it → Suggest "Known Issue"
**User interaction**:
Use the `AskUserQuestion` tool:
```
questions = [{
"question": "What type of release note is this?",
"header": "Type",
"multiSelect": false,
"options": [
{
"label": "Bug Fix",
"description": "Fix for a defect (most common)"
},
{
"label": "Known Issue",
"description": "Documents a known problem without a fix"
},
{
"label": "Enhancement",
"description": "New feature or improvement"
},
{
"label": "CVE",
"description": "Security vulnerability fix"
}
]
}]
```
**Store selection** for use in the next step.
### Step 9: Update Jira Ticket
**Objective**: Write the release note to the Jira ticket.
**MCP tool call**:
```
mcp__atlassian__jira_update_issue(
issue_key=<issue-key>,
fields={
"customfield_12320850": {"value": "<selected_type>"},
"customfield_12317313": "<formatted_release_note_text>"
}
)
```
**Field details**:
- `customfield_12320850`: Release Note Type (must be exact match from dropdown)
- `customfield_12317313`: Release Note Text (plain text)
**Error handling**:
1. **Permission denied**:
```
Failed to update {issue-key}.
Error: You do not have permission to edit Release Note fields
Please contact your Jira administrator or manually add the release note.
Generated release note (for manual entry):
---
{release_note_text}
---
```
2. **Invalid field value**:
```
Failed to update Release Note Type field.
Error: Value "{selected_type}" is not valid
Please select a different type or manually update in Jira.
```
3. **Field not found**:
```
Failed to update {issue-key}.
Error: Field customfield_12320850 not found
This may indicate a different Jira instance or configuration.
Please manually add the release note.
```
**Success response**:
```
{
"success": true,
"issue": {
"key": "OCPBUGS-38358",
"fields": {
"customfield_12320850": {"value": "Bug Fix"},
"customfield_12317313": "Cause: ... Consequence: ... Fix: ... Result: ..."
}
}
}
```
### Step 10: Display Results
**Objective**: Show the user what was created and provide next steps.
**Output format**:
```
✓ Release Note Created for {issue-key}
Type: {Release Note Type}
Text:
---
{Release Note Text with proper formatting}
---
Updated: https://issues.redhat.com/browse/{issue-key}
Next steps:
- Review the release note in Jira
- Edit manually if any adjustments are needed
- The release note will be included in the next release
```
**Example**:
```
✓ Release Note Created for OCPBUGS-38358
Type: Bug Fix
Text:
---
Cause: hostedcontrolplane controller crashes when hcp.Spec.Platform.AWS.CloudProviderConfig.Subnet.ID is undefined
Consequence: control-plane-operator enters a crash loop
Fix: Added nil check for CloudProviderConfig.Subnet before accessing Subnet.ID field
Result: The control-plane-operator no longer crashes when CloudProviderConfig.Subnet is not specified
---
Updated: https://issues.redhat.com/browse/OCPBUGS-38358
Next steps:
- Review the release note in Jira
- Edit manually if any adjustments are needed
- The release note will be included in the next release
```
## Error Recovery Strategies
### PR Analysis Failures
**Problem**: Some PRs can't be accessed or analyzed
**Recovery**:
1. Log warning for each failed PR
2. Continue with successfully analyzed PRs
3. If all PRs fail, treat as "No PRs linked" error
4. Show summary of what was analyzed:
```
Analyzed 2 of 3 linked PRs:
✓ PR #123
✓ PR #456
✗ PR #789 (access denied)
```
### Incomplete Bug Description
**Problem**: Missing Cause or Consequence sections
**Recovery**:
1. Offer interactive input option
2. Provide template for user
3. Allow user to update bug and retry
4. Don't proceed without both fields
### Ambiguous PR Content
**Problem**: PRs don't clearly explain the fix
**Recovery**:
1. Use PR title as fallback
2. Analyze code diff more carefully
3. Ask user for clarification:
```
The linked PR doesn't clearly describe the fix.
Based on code analysis, it appears to:
{best guess from diff}
Is this correct? If not, please describe the fix:
```
### Conflicting Information
**Problem**: Multiple PRs describe different fixes
**Recovery**:
1. Present both descriptions to user
2. Ask which is correct or how to combine
3. Use AI to attempt intelligent synthesis
4. If synthesis fails, escalate to user
## Best Practices for Implementation
1. **Always validate inputs**: Check that issue exists, PRs are accessible, fields are present
2. **Fail gracefully**: Provide helpful error messages with recovery instructions
3. **Be defensive**: Handle missing data, API errors, permission issues
4. **Log progress**: Show user what's happening at each step
5. **Preserve data**: If update fails, show generated content so it's not lost
6. **Security first**: Always validate before updating Jira
7. **User in control**: Confirm selections, allow overrides
## Testing Checklist
- [ ] Bug with single linked PR
- [ ] Bug with multiple linked PRs
- [ ] Bug with no linked PRs (error case)
- [ ] Bug with inaccessible PR (warning case)
- [ ] Bug missing Cause section (error case)
- [ ] Bug missing Consequence section (error case)
- [ ] Bug with existing release note (warning case)
- [ ] Bug that's not a Bug type (warning case)
- [ ] Release note with detected credentials (security failure)
- [ ] Different Release Note Type selections
- [ ] Update permission denied (error case)
- [ ] MCP server not configured (error case)
- [ ] gh CLI not authenticated (error case)

764
skills/create-story/SKILL.md Normal file
View File

@@ -0,0 +1,764 @@
---
name: Create Jira Story
description: Implementation guide for creating well-formed Jira user stories with acceptance criteria
---
# Create Jira Story
This skill provides implementation guidance for creating well-structured Jira user stories following agile best practices, including proper user story format and comprehensive acceptance criteria.
## When to Use This Skill
This skill is automatically invoked by the `/jira:create story` command to guide the story creation process.
## Prerequisites
- MCP Jira server configured and accessible
- User has permissions to create issues in the target project
- Understanding of the user story and acceptance criteria to be created
## ⚠️ Summary vs Description: CRITICAL DISTINCTION
**This is the #1 mistake when creating stories. The summary field and description field serve different purposes:**
### Summary Field (Issue Title)
- **SHORT, concise title** (5-10 words maximum)
- Action-oriented, describes WHAT will be done
- **Does NOT contain the full "As a... I want... So that..." format**
- Think of it as a newspaper headline
**Good summary examples:**
- ✅ "Enable ImageTagMirrorSet configuration in HostedCluster CRs"
- ✅ "Add automatic node pool scaling for ROSA HCP"
- ✅ "Implement webhook validation for HostedCluster resources"
**Bad summary examples:**
- ❌ "As a cluster admin, I want to configure ImageTagMirrorSet in HostedCluster CRs so that I can enable tag-based image proxying" (Full user story - belongs in description!)
- ❌ "As a developer, I want to view metrics so that I can debug issues" (User story format - belongs in description!)
### Description Field (Issue Body)
- Contains the **FULL user story format**: "As a... I want... So that..."
- Includes **acceptance criteria**
- Includes **additional context**
- Can be lengthy and detailed
**Correct usage:**
```
Summary: "Enable ImageTagMirrorSet configuration in HostedCluster CRs"
Description:
As a cluster admin, I want to configure ImageTagMirrorSet in HostedCluster CRs,
so that I can enable tag-based image proxying for my workloads.
Acceptance Criteria:
- Test that ImageTagMirrorSet can be specified...
```
### When Collecting Story Information
1. First collect the full user story (As a... I want... So that...)
2. Then extract/generate a concise summary title from that story
3. Present both to user for confirmation
4. Summary goes in `summary` parameter, full story goes in `description`
## User Story Best Practices
### What is a User Story?
A user story:
- Describes product functionality from a customer's perspective
- Is a collaboration tool - a reminder to have a conversation
- Shifts focus from writing documentation to talking with stakeholders
- Describes concrete business scenarios in shared language
- Is the right size for planning - level of detail based on implementation horizon
### The 3 Cs of User Stories
Every user story should have three components:
1. **Card** - The story itself (As a... I want... So that...)
2. **Conversation** - Discussion between team and stakeholders about implementation
3. **Confirmation** - Acceptance criteria that define "done"
## User Story Template
### Standard Format
```
As a <User/Who>, I want to <Action/What>, so that <Purpose/Why>.
```
**Components:**
- **Who (User/Role):** The person, device, or system that will benefit from or use the output
- Examples: "cluster admin", "developer", "end user", "monitoring system", "CI pipeline"
- **What (Action):** What they can do with the system
- Examples: "configure automatic scaling", "view cluster metrics", "deploy applications"
- **Why (Purpose):** Why they want to do the activity, the value they gain
- Examples: "to handle traffic spikes", "to identify performance issues", "to reduce deployment time"
### Good Examples
```
As a cluster admin, I want to configure automatic node pool scaling based on CPU utilization, so that I can handle traffic spikes without manual intervention.
```
```
As a developer, I want to view real-time cluster metrics in the web console, so that I can quickly identify performance issues before they impact users.
```
```
As an SRE, I want to set up alerting rules for control plane health, so that I can be notified immediately when issues occur.
```
### Bad Examples (and why)
❌ "Add scaling feature"
- **Why bad:** No user, no value statement, too vague
❌ "As a user, I want better performance"
- **Why bad:** Not actionable, no specific action, unclear benefit
❌ "Implement autoscaling API"
- **Why bad:** Technical task, not user-facing value
✅ **Convert to:** "As a cluster admin, I want to configure autoscaling policies via the API, so that I can automate cluster capacity management"
## Acceptance Criteria
Acceptance criteria:
- Express conditions that need to be satisfied for the customer
- Provide context and details for the team
- Help the team know when they are done
- Provide testing point of view
- Are written by Product Owner or dev team members
- Are refined during backlog grooming and iteration planning
### Formats for Acceptance Criteria
Choose the format that best fits the story:
#### Format 1: Test-Based
```
- Test that <criteria>
```
**Example:**
```
- Test that node pools scale up when CPU exceeds 80%
- Test that node pools scale down when CPU drops below 30%
- Test that scaling respects configured min/max node limits
```
#### Format 2: Demonstration-Based
```
- Demonstrate that <this happens>
```
**Example:**
```
- Demonstrate that scaling policies can be configured via CLI
- Demonstrate that scaling events appear in the audit log
- Demonstrate that users receive notifications when scaling occurs
```
#### Format 3: Verification-Based
```
- Verify that when <a role> does <some action> they get <this result>
```
**Example:**
```
- Verify that when a cluster admin sets max nodes to 10, the node pool never exceeds 10 nodes
- Verify that when scaling is disabled, node count remains constant regardless of load
```
#### Format 4: Given-When-Then (BDD)
```
- Given <a context> when <this event occurs> then <this happens>
```
**Example:**
```
- Given CPU utilization is at 85%, when the scaling policy is active, then a new node is provisioned within 2 minutes
- Given the node pool is at maximum capacity, when scaling is triggered, then an alert is raised and no nodes are added
```
### How Much Acceptance Criteria is Enough?
You have enough AC when:
- ✅ You have enough to size/estimate the story
- ✅ The testing approach is clear but not convoluted
- ✅ You've made 2-3 revisions of the criteria
- ✅ The story is independently testable
**If you need more AC:**
- Consider splitting the story into multiple smaller stories
- Each story should be completable in one sprint
**If AC is too detailed:**
- Move implementation details to subtasks or technical design docs
- Keep AC focused on user-observable behavior
## Interactive Story Collection Workflow
When creating a story, guide the user through the process:
### 1. Collect User Story Statement
**Prompt:** "Let's create the user story. I can help you format it properly."
**Ask three questions:**
1. **Who benefits?**
```
Who is the user or role that will benefit from this feature?
Examples: cluster admin, developer, SRE, end user, system administrator
```
2. **What action?**
```
What do they want to be able to do?
Examples: configure autoscaling, view metrics, set up alerts
```
3. **What value/why?**
```
Why do they want this? What value does it provide?
Examples: to handle traffic spikes, to improve visibility, to reduce downtime
```
**Construct the story:**
```
As a <answer1>, I want to <answer2>, so that <answer3>.
```
**Present to user and ask for confirmation:**
```
Here's the user story:
As a cluster admin, I want to configure automatic node pool scaling, so that I can handle traffic spikes without manual intervention.
Does this look correct? (yes/no/modify)
```
### 2. Collect Acceptance Criteria
**Prompt:** "Now let's define the acceptance criteria. These help the team know when the story is complete."
**Approach 1: Guided Questions**
Ask probing questions:
```
1. What are the key behaviors that must work?
2. What are the edge cases or boundaries?
3. How will this be tested?
4. What shouldn't happen?
```
**Approach 2: Template Assistance**
Offer format templates:
```
Which format would you like to use for acceptance criteria?
1. Test that... (test-based)
2. Verify that when... they get... (verification-based)
3. Given... when... then... (BDD)
4. I'll write them in my own format
```
**Approach 3: Free-Form**
```
Please provide the acceptance criteria (one per line, or I can help you structure them):
```
**Validate AC:**
- At least 2-3 criteria provided
- Criteria are specific and testable
- Criteria cover happy path and edge cases
- Criteria are user-observable (not implementation details)
### 3. Collect Additional Context (Optional)
**Prompt:** "Any additional context for the team? (Optional)"
**Helpful additions:**
- Background: Why is this needed now?
- Dependencies: What must exist before this can be done?
- Constraints: Any technical or business constraints?
- Out of scope: What is explicitly not included?
- References: Links to designs, docs, related issues
**Example:**
```
Additional Context:
- This builds on the existing monitoring infrastructure introduced in PROJ-100
- Must integrate with Prometheus metrics
- Out of scope: Custom metrics (will be separate story)
- Design doc: https://docs.example.com/autoscaling-design
```
## Story Sizing and Splitting
### Right-Sized Stories
A well-sized story:
- Can be completed in one sprint (typically 1-2 weeks)
- Can be demonstrated as working software
- Delivers incremental value
- Has clear acceptance criteria
### When to Split Stories
Split a story if:
- It would take more than one sprint
- It has too many acceptance criteria (>7-8)
- It contains multiple distinct features
- It has hard dependencies that could be separate
- Testing becomes too complex
### Splitting Techniques
**By workflow steps:**
```
Original: As a user, I want to manage my account settings
Split:
- As a user, I want to view my account settings
- As a user, I want to update my account settings
- As a user, I want to delete my account
```
**By acceptance criteria:**
```
Original: Complex story with 10 AC
Split:
- Story 1: AC 1-4 (core functionality)
- Story 2: AC 5-7 (edge cases)
- Story 3: AC 8-10 (advanced features)
```
**By platform/component:**
```
Original: Add feature to all platforms
Split:
- Add feature to web interface
- Add feature to CLI
- Add feature to API
```
## Field Validation
Before submitting the story, validate:
### Required Fields
- ✅ Summary is concise title (5-10 words), NOT full user story (see "Summary vs Description" section above)
- ✅ Description contains full user story in "As a... I want... So that..." format
- ✅ Acceptance criteria are present (at least 2)
- ✅ Component is specified (if required by project)
- ✅ Target version is set (if required by project)
### Story Quality
- ✅ Story describes user-facing value (not implementation)
- ✅ Acceptance criteria are testable
- ✅ Acceptance criteria are specific (not vague)
- ✅ Story is sized appropriately (can fit in one sprint)
### Security
- ✅ No credentials, API keys, or secrets in any field
- ✅ No sensitive customer data in examples
## MCP Tool Parameters
### Basic Story Creation
```python
mcp__atlassian__jira_create_issue(
project_key="<PROJECT_KEY>",
summary="<concise title>", # 5-10 words, NOT full user story
issue_type="Story",
description="""
As a <user>, I want to <action>, so that <value>.
h2. Acceptance Criteria
* Test that <criteria 1>
* Test that <criteria 2>
* Verify that <criteria 3>
h2. Additional Context
<context if provided>
""",
components="<component name>", # if required
additional_fields={
# Add project-specific fields
}
)
```
### With Project-Specific Fields (e.g., CNTRLPLANE)
```python
mcp__atlassian__jira_create_issue(
project_key="CNTRLPLANE",
summary="Enable automatic node pool scaling for ROSA HCP",
issue_type="Story",
description="""
As a cluster admin, I want to configure automatic node pool scaling based on CPU utilization, so that I can handle traffic spikes without manual intervention.
h2. Acceptance Criteria
* Test that node pools scale up when average CPU exceeds 80% for 5 minutes
* Test that node pools scale down when average CPU drops below 30% for 10 minutes
* Test that scaling respects configured min/max node limits
* Verify that when scaling is disabled, node count remains constant regardless of load
* Verify that scaling events are logged to the cluster audit trail
* Demonstrate that scaling policies can be configured via rosa CLI
h2. Additional Context
This builds on the existing monitoring infrastructure. Must integrate with Prometheus metrics for CPU utilization data.
Out of scope: Custom metrics-based scaling (will be separate story CNTRLPLANE-457)
""",
components="HyperShift / ROSA",
additional_fields={
"labels": ["ai-generated-jira"],
"security": {"name": "Red Hat Employee"}
# Note: Target version omitted (optional in CNTRLPLANE)
# Note: Epic link handled separately - see CNTRLPLANE skill for details
}
)
```
**Note:** For epic linking, parent field handling, and other project-specific requirements, refer to the appropriate project-specific skill (e.g., CNTRLPLANE, OCPBUGS).
## Jira Description Formatting
Use Jira's native formatting (Wiki markup):
### Story Template Format
```
As a <user>, I want to <action>, so that <value>.
h2. Acceptance Criteria
* Test that <criteria 1>
* Verify that <criteria 2>
* Given <context> when <event> then <outcome>
h2. Additional Context
<optional context>
h3. Dependencies
* [PROJ-123] - Parent epic or related story
h3. Out of Scope
* Feature X (will be separate story)
* Platform Y support (future release)
```
### Formatting Elements
**Headings:**
```
h1. Main Heading
h2. Subheading
h3. Sub-subheading
```
**Lists:**
```
* Bullet item 1
* Bullet item 2
** Nested bullet
# Numbered item 1
# Numbered item 2
```
**Text Formatting:**
```
*bold text*
_italic text_
{{monospace}}
```
**Code Blocks:**
```
{code}
rosa create cluster --autoscaling-min 3 --autoscaling-max 10
{code}
```
**Links:**
```
[Design doc|https://docs.example.com/design]
[PROJ-123] // Auto-links to Jira issue
```
## Error Handling
### Invalid Story Format
**Scenario:** User provides a story that doesn't follow the template.
**Action:**
1. Identify the issue (missing "Who", "What", or "Why")
2. Explain the user story format
3. Ask questions to extract missing components
4. Reconstruct the story properly
**Example:**
```
The story "Add autoscaling" doesn't follow the user story format.
Let me help you structure it:
- Who will use this feature? (e.g., cluster admin, developer)
- What do they want to do? (e.g., configure autoscaling)
- Why do they want it? (e.g., to handle traffic spikes)
```
### Missing Acceptance Criteria
**Scenario:** User doesn't provide acceptance criteria.
**Action:**
1. Explain importance of AC
2. Offer to help create them
3. Ask probing questions about expected behavior
4. Suggest format that fits the story
**Example:**
```
Acceptance criteria help define when this story is complete. Let's add some.
What are the key behaviors that must work for this story?
For example:
- What actions should users be able to perform?
- What should happen in edge cases?
- How will you know the feature works correctly?
```
### Story Too Large
**Scenario:** Story has too many acceptance criteria or sounds too complex.
**Action:**
1. Suggest the story might be too large for one sprint
2. Identify potential split points
3. Offer to create multiple stories
4. Create parent epic if multiple related stories
**Example:**
```
This story has 12 acceptance criteria, which suggests it might be too large for one sprint.
I can help split this into smaller stories:
1. Core functionality (AC 1-4)
2. Advanced features (AC 5-8)
3. Edge cases and validation (AC 9-12)
Would you like me to create these as separate stories under an epic?
```
### Vague Acceptance Criteria
**Scenario:** AC is too vague or not testable.
**Action:**
1. Identify vague criteria
2. Ask for specifics
3. Suggest more concrete phrasing
**Example:**
```
This acceptance criteria is a bit vague: "Test that it works well"
Can you be more specific? For example:
- What does "works well" mean? (fast response time? handles errors?)
- How would you test this? (what specific behavior would you verify?)
Suggested revision: "Verify that API response time is under 100ms for 95% of requests"
```
### Security Validation Failure
**Scenario:** Sensitive data detected in story content.
**Action:**
1. STOP submission
2. Inform user what type of data was detected
3. Ask for redaction or placeholder values
**Example:**
```
I detected what appears to be API credentials in the acceptance criteria.
Please use placeholder values like "YOUR_API_KEY" instead of real credentials.
```
### MCP Tool Error
**Scenario:** MCP tool returns an error when creating the story.
**Action:**
1. Parse error message
2. Provide user-friendly explanation
3. Suggest corrective action
4. Offer to retry
**Common errors:**
- **"Field 'parent' does not exist"** → Remove parent link or verify epic exists
- **"Invalid issue type"** → Verify project supports "Story" issue type
- **"Component not found"** → List available components, ask user to select
## Examples
### Example 1: Interactive Story Creation
**Input:**
```bash
/jira:create story MYPROJECT "Add user dashboard"
```
**Conversation:**
```
Let's create the user story. I'll ask a few questions:
Who is the user or role that will benefit from this feature?
> End users
What do they want to be able to do?
> View their activity dashboard with recent actions and notifications
Why do they want this? What value does it provide?
> To quickly see what's happened in their account without navigating multiple pages
Great! Here's the user story:
As an end user, I want to view my activity dashboard with recent actions and notifications, so that I can quickly see what's happened in my account without navigating multiple pages.
Does this look correct?
> Yes
Now let's define acceptance criteria. What are the key behaviors that must work?
> 1. Dashboard shows last 10 actions
> 2. Dashboard shows unread notifications
> 3. Dashboard updates in real-time
> 4. Users can filter by action type
Excellent. I'll format these as test-based criteria:
* Test that dashboard displays the last 10 user actions
* Test that dashboard displays all unread notifications
* Test that dashboard updates in real-time when new actions occur
* Verify that users can filter actions by type (login, purchase, settings change)
Any additional context?
> This is part of the Q1 user experience improvements
Perfect! Creating the story now...
```
**Result:**
```
Created: MYPROJECT-123
Title: Add user dashboard
URL: https://jira.example.com/browse/MYPROJECT-123
```
### Example 2: Story with Auto-Detection (CNTRLPLANE)
**Input:**
```bash
/jira:create story CNTRLPLANE "Enable pod disruption budgets for ROSA HCP control plane"
```
**Auto-applied (via cntrlplane skill):**
- 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 (Who/What/Why)
- Acceptance criteria
**Result:**
- Full story created with CNTRLPLANE conventions
### Example 3: Story with Parent Epic
**Input:**
```bash
/jira:create story CNTRLPLANE "Add scaling metrics to observability dashboard" --parent CNTRLPLANE-100
```
**Result:**
- Story created
- Linked to epic CNTRLPLANE-100
- All standard fields applied
## Best Practices Summary
1. **User-focused:** Always describe value from user perspective
2. **Specific actions:** Clear what the user can do
3. **Clear value:** Explicit why (benefit to user)
4. **Testable AC:** Specific, observable criteria
5. **Right-sized:** Can complete in one sprint
6. **Conversational:** Story prompts discussion, not full spec
7. **Independent:** Story can be implemented standalone
8. **Valuable:** Delivers user value when complete
## Anti-Patterns to Avoid
❌ **Technical tasks disguised as stories**
```
As a developer, I want to refactor the database layer
```
✅ Use a Task instead, or reframe with user value
❌ **Too many stories in one**
```
As a user, I want to create, edit, delete, and share documents
```
✅ Split into 4 separate stories
❌ **Vague acceptance criteria**
```
- Test that it works correctly
- Verify good performance
```
✅ Be specific: "Response time under 200ms", "Handles 1000 concurrent users"
❌ **Implementation details in AC**
```
- Test that the function uses Redis cache
- Verify that the API calls the UserService.get() method
```
✅ Focus on user-observable behavior, not implementation
## Workflow Summary
1. ✅ Parse command arguments (project, summary, flags)
2. 🔍 Auto-detect component from summary keywords
3. ⚙️ Apply project-specific defaults
4. 💬 Interactively collect user story (Who/What/Why)
5. 💬 Interactively collect acceptance criteria
6. 💬 Optionally collect additional context
7. 🔒 Scan for sensitive data
8. ✅ Validate story quality and completeness
9. 📝 Format description with Jira markup
10. ✅ Create story via MCP tool
11. 📤 Return issue key and URL
## See Also
- `/jira:create` - Main command that invokes this skill
- `cntrlplane` skill - CNTRLPLANE specific conventions
- Agile Alliance: User Story resources
- Mike Cohn: User Stories Applied

650
skills/create-task/SKILL.md Normal file
View File

@@ -0,0 +1,650 @@
---
name: Create Jira Task
description: Implementation guide for creating Jira tasks for technical and operational work
---
# Create Jira Task
This skill provides implementation guidance for creating Jira tasks, which are used for technical or operational work that doesn't necessarily deliver direct user-facing value.
## When to Use This Skill
This skill is automatically invoked by the `/jira:create task` command to guide the task creation process.
## Prerequisites
- MCP Jira server configured and accessible
- User has permissions to create issues in the target project
- Understanding of the technical work to be performed
## Tasks vs Stories
### When to Use a Task
Use a **Task** when the work is:
- **Technical/operational** - Infrastructure, refactoring, configuration
- **Not user-facing** - No direct end-user functionality
- **Internal improvement** - Code quality, performance, maintenance
- **Enabler work** - Supports future stories but isn't user-visible
**Examples of tasks:**
- "Update scaling documentation"
- "Refactor authentication utility package"
- "Configure CI pipeline for integration tests"
- "Upgrade dependency X to version Y"
- "Investigate performance regression in component Z"
### When to Use a Story Instead
Use a **Story** when the work:
- Delivers user-facing functionality
- Can be expressed as "As a... I want... so that..."
- Has business value to end users
- Is part of a user workflow
**If in doubt:** Ask "Would an end user notice or care about this change?"
- **Yes** → Story
- **No** → Task
## Task Best Practices
### Clear Summary
The summary should:
- Be concise (one sentence)
- Use action verbs (Update, Refactor, Configure, Investigate, Fix)
- Identify what is being changed
- Optionally include "why" if not obvious
**Good examples:**
- "Update autoscaling documentation for 4.21 release"
- "Refactor scaling controller to reduce code duplication"
- "Configure Prometheus alerts for control plane memory usage"
- "Investigate intermittent timeout in etcd health checks"
**Bad examples:**
- "Do some work on docs" (too vague)
- "Technical debt" (not specific)
- "Various improvements" (not actionable)
### Detailed Description
The description should include:
1. **What needs to be done** - Clear statement of the work
2. **Why it's needed** - Context or motivation
3. **Acceptance criteria** (optional but recommended) - How to know it's done
4. **Technical details** (if helpful) - Specific files, commands, approaches
**Example:**
```
Update the autoscaling documentation to reflect changes in the 4.21 release.
Why: The autoscaling API changed in 4.21 with new fields and behavior. Documentation currently reflects 4.20 and will confuse users.
Acceptance Criteria:
- All autoscaling examples updated to use 4.21 API
- New fields documented with descriptions and examples
- Deprecated fields marked as deprecated
- Documentation builds without warnings
Files to update:
- docs/content/how-to/autoscaling.md
- docs/content/reference/api.md
```
## Task Description Template
Use this structure for consistency:
```
<What needs to be done>
h2. Why
<Context, motivation, or reason this is needed>
h2. Acceptance Criteria
* <Criterion 1>
* <Criterion 2>
* <Criterion 3>
h2. Technical Details (optional)
* Files to modify: <list>
* Dependencies: <related issues or work>
* Approach: <suggested implementation approach>
```
## Interactive Task Collection Workflow
When creating a task, collect necessary information:
### 1. Task Description
**Prompt:** "What work needs to be done? Be specific about what you'll change or update."
**Helpful questions:**
- What component or area is being worked on?
- What specific changes will be made?
- What's the end state after this task is complete?
**Example response:**
```
Refactor the scaling controller to extract common validation logic into a shared utility package. Currently, validation code is duplicated across three controller files.
```
### 2. Motivation/Context
**Prompt:** "Why is this task needed? What problem does it solve?"
**Helpful questions:**
- What prompted this work?
- What will improve after this is done?
- Is this addressing a specific issue or enabling future work?
**Example response:**
```
Code duplication makes maintenance difficult. When validation logic changes, we have to update it in three places, which is error-prone. Consolidating into a shared utility will make the code easier to maintain and reduce bugs.
```
### 3. Acceptance Criteria (Optional but Recommended)
**Prompt:** "How will you know this task is complete? (Optional: skip if obvious)"
**For technical tasks, AC might include:**
- Tests passing
- Documentation updated
- Code review completed
- Specific functionality working
**Example response:**
```
- Validation logic extracted to support/validation package
- All three controllers updated to use shared validation
- Existing tests pass
- New unit tests added for validation utility
- Code review approved
```
### 4. Parent Link (Optional)
**Prompt:** "Is this task part of a larger story or epic? (Optional)"
**If yes:**
- Collect parent issue key
- Verify parent exists
- Link task to parent
### 5. Additional Technical Details (Optional)
**Prompt:** "Any technical details to include? (files to change, dependencies, approach)"
**Example response:**
```
Files to modify:
- hypershift/operator/controllers/nodepool/autoscaling.go
- hypershift/operator/controllers/hostedcluster/autoscaling.go
- hypershift/operator/controllers/manifests/autoscaling.go
- hypershift/support/validation/autoscaling.go (new)
Dependencies:
- Must complete after PROJ-100 (validation refactor epic)
Approach:
- Extract common validation functions to support/validation
- Add comprehensive unit tests for new package
- Update controllers to import and use new package
- Remove duplicated code
```
## Field Validation
Before submitting the task, validate:
### Required Fields
- ✅ Summary is clear and specific
- ✅ Description explains what needs to be done
- ✅ Description includes why (motivation)
- ✅ Component is specified (if required by project)
- ✅ Target version is set (if required by project)
### Task Quality
- ✅ Summary uses action verb (Update, Refactor, Configure, etc.)
- ✅ Work is technical/operational (not user-facing functionality)
- ✅ Description is detailed enough for someone else to understand
- ✅ Acceptance criteria present (if work is non-trivial)
- ✅ Task is sized appropriately (can complete in reasonable time)
### Security
- ✅ No credentials, API keys, or secrets in any field
- ✅ No sensitive technical details that shouldn't be public
## MCP Tool Parameters
### Basic Task Creation
```python
mcp__atlassian__jira_create_issue(
project_key="<PROJECT_KEY>",
summary="<task summary>",
issue_type="Task",
description="""
<What needs to be done>
h2. Why
<Context and motivation>
h2. Acceptance Criteria
* <Criterion 1>
* <Criterion 2>
h2. Technical Details
<Optional technical details>
""",
components="<component name>", # if required
additional_fields={
# Add project-specific fields
}
)
```
### With Project-Specific Fields (e.g., CNTRLPLANE)
```python
mcp__atlassian__jira_create_issue(
project_key="CNTRLPLANE",
summary="Update autoscaling documentation for 4.21 release",
issue_type="Task",
description="""
Update the autoscaling documentation to reflect API changes in the 4.21 release.
h2. Why
The autoscaling API changed in 4.21 with new fields (maxNodeGracePeriod, scaleDownDelay) and modified behavior. Current documentation reflects 4.20 API and will confuse users upgrading to 4.21.
h2. Acceptance Criteria
* All autoscaling examples updated to use 4.21 API syntax
* New fields (maxNodeGracePeriod, scaleDownDelay) documented with descriptions and examples
* Deprecated fields marked as deprecated with migration guidance
* Documentation builds successfully without warnings or broken links
* Changes reviewed by docs team
h2. Technical Details
Files to update:
* docs/content/how-to/cluster-autoscaling.md
* docs/content/reference/api/nodepool.md
* docs/content/tutorials/autoscaling-rosa.md
Reference: API changes introduced in PR #1234
""",
components="HyperShift",
additional_fields={
"customfield_12319940": "openshift-4.21", # target version
"labels": ["ai-generated-jira", "documentation"],
"security": {"name": "Red Hat Employee"}
}
)
```
### With Parent Link
```python
mcp__atlassian__jira_create_issue(
project_key="MYPROJECT",
summary="Add unit tests for scaling validation",
issue_type="Task",
description="<task content>",
additional_fields={
"parent": {"key": "MYPROJECT-100"} # link to story or epic
}
)
```
## Jira Description Formatting
Use Jira's native formatting (Wiki markup):
### Task Template Format
```
<Brief description of what needs to be done>
h2. Why
<Context, motivation, or problem this solves>
h2. Acceptance Criteria
* <Criterion 1>
* <Criterion 2>
* <Criterion 3>
h2. Technical Details
h3. Files to Modify
* {{path/to/file1.go}}
* {{path/to/file2.go}}
h3. Dependencies
* Must complete after [PROJ-100]
* Requires library X version Y
h3. Approach
<Suggested implementation approach or technical notes>
h2. Additional Context
<Optional: Links to designs, related issues, background>
```
### Formatting Elements
**Headings:**
```
h1. Main Heading
h2. Subheading
h3. Sub-subheading
```
**Lists:**
```
* Bullet item 1
* Bullet item 2
# Numbered item 1
# Numbered item 2
```
**Code/Paths:**
```
{{path/to/file.go}}
{{package.function()}}
{code}
make test
make build
{code}
```
**Links:**
```
[Design doc|https://docs.example.com/design]
[PROJ-123] // Auto-links to Jira issue
```
## Error Handling
### Task vs Story Confusion
**Scenario:** User tries to create a task for user-facing functionality.
**Action:**
1. Detect user-facing language in summary/description
2. Ask if this should be a story instead
3. Explain the difference
4. Offer to create as story if appropriate
**Example:**
```
This sounds like it might deliver user-facing functionality. The summary mentions "users can configure autoscaling".
Should this be a Story instead of a Task?
- Story: For user-facing features (visible to end users)
- Task: For internal/technical work (not visible to end users)
Would you like me to create this as a Story? (yes/no)
```
### Missing Context
**Scenario:** User provides minimal description without context.
**Action:**
1. Ask for more details
2. Prompt for "why" if missing
3. Suggest adding acceptance criteria if non-trivial
**Example:**
```
The description "Update docs" is a bit brief. Can you provide more detail?
- Which documentation needs updating?
- Why does it need updating? (new features, corrections, clarifications?)
- What specific changes should be made?
```
### Parent Not Found
**Scenario:** User specifies `--parent` but issue doesn't exist.
**Action:**
1. Attempt to fetch parent issue
2. If not found, inform user
3. Offer options: proceed without parent, specify different parent, cancel
**Example:**
```
Parent issue PROJ-999 not found.
Options:
1. Proceed without parent link
2. Specify different parent
3. Cancel task creation
What would you like to do?
```
### Security Validation Failure
**Scenario:** Sensitive data detected in task content.
**Action:**
1. STOP submission
2. Inform user what type of data was detected
3. Ask for redaction
**Example:**
```
I detected what appears to be an API key in the technical details section.
Please use placeholder values like "YOUR_API_KEY" instead of real credentials.
```
### MCP Tool Error
**Scenario:** MCP tool returns an error when creating the task.
**Action:**
1. Parse error message
2. Provide user-friendly explanation
3. Suggest corrective action
**Common errors:**
- **"Field 'component' is required"** → Prompt for component
- **"Invalid parent"** → Verify parent issue exists and is correct type
- **"Permission denied"** → User may lack project permissions
## Examples
### Example 1: Documentation Task
**Input:**
```bash
/jira:create task CNTRLPLANE "Update autoscaling documentation for 4.21 release"
```
**Interactive prompts:**
```
What work needs to be done?
> Update the autoscaling documentation to include new fields added in 4.21
Why is this task needed?
> API changed in 4.21, docs need updating to match
How will you know this is complete?
> All examples work with 4.21, new fields documented, no build warnings
Any technical details?
> Files: docs/content/how-to/autoscaling.md, docs/content/reference/api.md
```
**Result:**
- Task created with complete description
- Target version: 4.21
- Component: HyperShift (or auto-detected)
### Example 2: Refactoring Task
**Input:**
```bash
/jira:create task MYPROJECT "Refactor validation logic to reduce duplication"
```
**Interactive prompts:**
```
What work needs to be done?
> Extract common validation code from three controller files into shared utility
Why is this needed?
> Code duplication makes maintenance difficult and error-prone
Acceptance criteria?
> - Validation extracted to support/validation package
> - All controllers use shared validation
> - Tests pass
> - New unit tests for validation utility
Any technical details?
> Files to modify:
> - controllers/nodepool/autoscaling.go
> - controllers/hostedcluster/autoscaling.go
> - controllers/manifests/autoscaling.go
> New file: support/validation/autoscaling.go
```
**Result:**
- Task with detailed technical plan
- Clear acceptance criteria
- Ready for implementation
### Example 3: Task with Parent
**Input:**
```bash
/jira:create task CNTRLPLANE "Add integration tests for node autoscaling" --parent CNTRLPLANE-100
```
**Auto-applied:**
- Linked to parent story CNTRLPLANE-100
- Inherits component from parent (if applicable)
- CNTRLPLANE conventions applied
**Result:**
- Task created under parent story
- All fields properly set
### Example 4: Investigation Task
**Input:**
```bash
/jira:create task CNTRLPLANE "Investigate intermittent timeouts in etcd health checks"
```
**Description pattern for investigation tasks:**
```
Investigate intermittent timeout errors occurring in etcd health checks on ROSA HCP clusters.
h2. Why
Users report clusters occasionally showing unhealthy status despite normal operation. Logs show intermittent timeout errors from etcd health checks.
h2. Acceptance Criteria
* Root cause identified and documented
* Recommendation provided (fix, workaround, or "no action needed")
* Findings shared with team in investigation summary
h2. Technical Details
Error pattern:
{code}
etcd health check failed: context deadline exceeded (timeout: 2s)
{code}
Frequency: ~5% of health checks
Affected clusters: ROSA HCP in us-east-1
Logs to review: control-plane-operator, etcd-operator
Related issues: OCPBUGS-1234 (similar symptoms)
```
**Result:**
- Investigation task with clear scope
- Defined outcome (root cause + recommendation)
- Context for debugging
## Best Practices Summary
1. **Specific summaries:** Use action verbs, identify what's changing
2. **Explain why:** Always include motivation/context
3. **Add AC:** Even for tasks, AC helps define "done"
4. **Technical details:** Include file paths, commands, approaches when helpful
5. **Right size:** Task should be completable in reasonable time (days, not weeks)
6. **Link to parent:** If task supports a story/epic, link it
7. **Not a story:** If it's user-facing, create a story instead
## Anti-Patterns to Avoid
❌ **Vague summaries**
```
"Update stuff"
"Fix things"
```
✅ Be specific: "Update autoscaling documentation for 4.21 API changes"
❌ **User-facing work as tasks**
```
"Add user dashboard feature"
```
✅ Should be a Story if it delivers user value
❌ **Too large**
```
"Refactor entire codebase"
"Update all documentation"
```
✅ Break into smaller, focused tasks
❌ **No context**
```
Summary: "Update docs"
Description: <empty>
```
✅ Always explain why and what specifically
## Workflow Summary
1. ✅ Parse command arguments (project, summary, flags)
2. 🔍 Auto-detect component from summary keywords
3. ⚙️ Apply project-specific defaults
4. 💬 Interactively collect task description and context
5. 💬 Interactively collect acceptance criteria (optional)
6. 💬 Optionally collect technical details
7. 🔒 Scan for sensitive data
8. ✅ Validate task is appropriate (not a story)
9. 📝 Format description with Jira markup
10. ✅ Create task via MCP tool
11. 📤 Return issue key and URL
## See Also
- `/jira:create` - Main command that invokes this skill
- `create-story` skill - For user-facing functionality
- `cntrlplane` skill - CNTRLPLANE specific conventions
- Agile task management best practices

344
skills/hypershift/SKILL.md Normal file
View File

@@ -0,0 +1,344 @@
---
name: HyperShift Jira Conventions
description: HyperShift team-specific Jira requirements for component selection and conventions
---
# 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_12319940):
- **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_12319940):
- **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
### For HyperShift Stories/Tasks in CNTRLPLANE
```python
mcp__atlassian__jira_create_issue(
project_key="CNTRLPLANE",
summary="<issue summary>",
issue_type="Story" | "Task" | "Epic" | "Feature",
description="<formatted description>",
components="HyperShift / ARO" | "HyperShift / ROSA" | "HyperShift",
additional_fields={
"customfield_12319940": "openshift-4.21", # target version
"labels": ["ai-generated-jira"],
"security": {"name": "Red Hat Employee"}
}
)
```
### For HyperShift Bugs in OCPBUGS
```python
mcp__atlassian__jira_create_issue(
project_key="OCPBUGS",
summary="<bug summary>",
issue_type="Bug",
description="<formatted bug template>",
components="HyperShift / ARO" | "HyperShift / ROSA" | "HyperShift",
additional_fields={
"versions": [{"name": "4.21"}], # affects version
"customfield_12319940": "4.21", # target version
"labels": ["ai-generated-jira"],
"security": {"name": "Red Hat Employee"}
}
)
```
## Examples
### Example 1: ROSA HCP Story (Auto-Detection)
**Input:**
```bash
/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:**
```bash
/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:**
```bash
/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:**
```bash
/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:**
```bash
/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:
```bash
# 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

318
skills/jira-validate-blockers/SKILL.md Normal file
View File

@@ -0,0 +1,318 @@
---
name: JIRA Release Blocker Validator
description: Detailed implementation guide for validating proposed release blockers
command: /jira:validate-blockers
---
# JIRA Release Blocker Validator - Implementation Guide
This skill provides detailed implementation guidance for the `/jira:validate-blockers` command, which helps release managers make data-driven blocker approval/rejection decisions.
## When to Use This Skill
This skill is invoked automatically when the `/jira:validate-blockers` command is executed. It provides step-by-step implementation details for:
- Querying JIRA for proposed release blockers (Release Blocker = Proposed)
- Scoring blockers against Red Hat OpenShift release blocker criteria
- Generating APPROVE/REJECT/DISCUSS recommendations
## Prerequisites
- Jira MCP server must be configured (see plugin README)
- MCP tools available: `mcp__atlassian__jira_*`
- Read-only access to JIRA APIs (no credentials required for public Red Hat JIRA issues)
- For single bug mode: bug must be accessible and exist
## Detailed Implementation Steps
### Phase 1: Parse Arguments
**Parse command-line arguments:**
- Extract target version from $1 (optional, format: X.Y like "4.21")
- Extract component filter from $2 (optional, supports comma-separated values)
- Extract `--bug` flag value (optional, for single bug validation mode)
**Project:**
- Hardcoded to "OCPBUGS" project
**Validate inputs:**
- If neither `--bug` nor `target-version` is provided, error out with message: "Error: Either target-version or --bug must be provided. Usage: /jira:validate-blockers [target-version] [component-filter] [--bug issue-key]"
- If target version provided, verify it matches pattern X.Y (e.g., "4.21", "4.22")
- If component filter provided without target version and without --bug, error out
### Phase 2: Build JQL Query for Proposed Blockers
**Determine query mode:**
1. **Single bug mode** (if `--bug` is provided):
- Skip JQL query construction
- Use `mcp__atlassian__jira_get_issue` to fetch the single bug
- Target version and component filter are ignored in this mode
- Proceed to analysis with single bug only
2. **Version + component mode** (if both target version and component are provided):
- Build JQL query for proposed blockers matching target version and component filter
- Continue with query construction below
3. **Version only mode** (if only target version provided):
- Build JQL query for all proposed blockers for the target version
- Continue with query construction below
**Base JQL for proposed blockers:**
```jql
project = OCPBUGS AND type = Bug AND "Release Blocker" = Proposed
```
**IMPORTANT**: Use `"Release Blocker" = Proposed` NOT `cf[12319743]`. The field ID `customfield_12319743` is the Release Blocker field, but in JQL use the field name.
**Version filter construction:**
When target version is provided (e.g., "4.21"), expand to search for both X.Y and X.Y.0:
```jql
AND ("Target Version" in (4.21, 4.21.0) OR "Target Backport Versions" in (4.21, 4.21.0) OR affectedVersion in (4.21, 4.21.0))
```
**Status exclusion filter:**
Always exclude already-fixed bugs:
```jql
AND status not in (Closed, "Release Pending", Verified, ON_QA)
```
**Component filter construction:**
**No component specified:**
- Query all components (no component filter in JQL)
**Single component:**
```jql
AND component = "{COMPONENT}"
```
**Multiple components (comma-separated):**
```jql
AND component IN ({COMPONENT_LIST})
```
**Final JQL examples:**
**Version only (4.21):**
```jql
project = OCPBUGS AND type = Bug AND "Release Blocker" = Proposed AND ("Target Version" in (4.21, 4.21.0) OR "Target Backport Versions" in (4.21, 4.21.0) OR affectedVersion in (4.21, 4.21.0)) AND status not in (Closed, "Release Pending", Verified, ON_QA)
```
**Version + component (4.21, "Hypershift"):**
```jql
project = OCPBUGS AND type = Bug AND "Release Blocker" = Proposed AND ("Target Version" in (4.21, 4.21.0) OR "Target Backport Versions" in (4.21, 4.21.0) OR affectedVersion in (4.21, 4.21.0)) AND status not in (Closed, "Release Pending", Verified, ON_QA) AND component = "Hypershift"
```
**Version + multiple components (4.21, "Hypershift,CVO"):**
```jql
project = OCPBUGS AND type = Bug AND "Release Blocker" = Proposed AND ("Target Version" in (4.21, 4.21.0) OR "Target Backport Versions" in (4.21, 4.21.0) OR affectedVersion in (4.21, 4.21.0)) AND status not in (Closed, "Release Pending", Verified, ON_QA) AND component IN ("Hypershift", "Cluster Version Operator")
```
### Phase 3: Query Proposed Blockers
**Use MCP tools to fetch proposed blockers:**
For version/component mode, use `mcp__atlassian__jira_search`:
- **jql**: The constructed JQL query from Phase 2
- **fields**: "key,summary,priority,severity,status,assignee,created,updated,labels,components,description,reporter,customfield_12319743,customfield_12319940"
- **expand**: "renderedFields" (to get comments for workaround analysis)
- **limit**: 1000 (adjust based on expected results)
Parse the response to extract:
- Total count of proposed blockers
- List of bug objects with all required fields
Custom fields to include:
- `customfield_12319743` - Release Blocker status (should be "Proposed")
- `customfield_12319940` - Target Version
For single bug mode (`--bug` flag), use `mcp__atlassian__jira_get_issue`:
- **issue_key**: The bug key provided by user
- **fields**: Same fields as above plus custom fields
- **expand**: "renderedFields"
- **comment_limit**: 100 (need to check for workaround mentions)
**Handle query results:**
- If total is 0, display message: "✅ No proposed blockers found" with filter summary
- If total > 20, show progress indicator
- Cache all bug data for analysis (avoid re-querying)
### Phase 4: Analyze Each Proposed Blocker
Analyze each proposed blocker using Red Hat OpenShift release blocker criteria.
**Red Hat OpenShift Release Blocker Criteria:**
Based on the official OpenShift blocker definition, bugs should be approved as release blockers when they meet these criteria:
**Automatic/Strong Blockers (Recommend APPROVE):**
- **Component Readiness regressions** (label: ComponentReadinessRegression) - even tech-preview jobs, unless covered by approved exceptions
- **Service Delivery blockers** (label: ServiceDeliveryBlocker) - most bugs with this label are blockers
- **Data loss, service unavailability, or data corruption** - most bugs in this category are blockers
- **Install/upgrade failures** - may be blockers based on scope (all platforms vs specific form-factor)
- **Perception of failed upgrade** - bugs that appear as upgrade failures to users
- **Regressions from previous release** - most regressions are blockers (e.g., from Layered Product Testing)
- **Bugs severely impacting Service Delivery** - regressions/bugs in default ROSA/OSD/ARO fleet features without acceptable workaround
**Never Blockers (Recommend REJECT):**
- **Severity below Important** - no bugs with Low/Medium severity are blockers
- **New features without regressions** - most new feature bugs are NOT blockers unless they regress existing functionality
- **CI-only issues** - bugs that only affect CI infrastructure/jobs and don't impact product functionality are NOT release blockers
- Look for labels: `ci-fail`, `ci-only`, `test-flake`
- Check summary/description for keywords: "CI job", "test failure", "rehearsal", "periodic job", "e2e test"
- Check comments for explicit statements like "Won't affect the product", "CI-only", "infrastructure issue"
- Even if the bug describes install/upgrade failures, if it only manifests in CI environments, recommend REJECT
**Workaround Assessment (may affect recommendation):**
An acceptable workaround must meet ALL three criteria:
1. **Idempotent** - can be applied repeatedly without resulting change
2. **Safe at scale** - can be safely deployed to 1000's of clusters without material risk via automation
3. **Timely** - SD can implement before release is pushed to more Cincinnati channels (candidate, fast, stable)
If a workaround doesn't meet all three criteria, it's NOT an acceptable workaround.
**For each proposed blocker:**
1. **Fetch bug details** including summary, description, labels, priority, severity, comments
2. **Check for CI-only indicators** (REJECT criteria):
- Check labels: `ci-fail`, `ci-only`, `test-flake`
- Check summary/description for CI-specific keywords:
- "CI job", "test failure", "rehearsal", "periodic job", "e2e test", "periodic-ci-"
- Check comments for explicit CI-only statements:
- "Won't affect the product"
- "CI-only"
- "infrastructure issue"
- "only affects CI"
- **If CI-only indicators found, recommend REJECT regardless of severity or failure type**
3. **Analyze blocker criteria** (if not CI-only):
- Check labels: ComponentReadinessRegression, ServiceDeliveryBlocker, UpgradeBlocker
- Check severity: Must be Important or higher (Critical/Urgent)
- Analyze summary/description for keywords:
- Data loss, corruption, service unavailable
- Install failure, upgrade failure
- Regression
- Identify scope: All platforms vs specific form-factor/configuration
4. **Check for acceptable workarounds**:
- Use `expand="renderedFields"` to get comment text
- Search for keywords: "workaround", "work around", "alternative", "bypass"
- Assess if workaround meets all 3 criteria (idempotent, safe at scale, timely)
5. **Generate recommendation**:
- ✅ **APPROVE** - Meets automatic/strong blocker criteria, no acceptable workaround
- ❌ **REJECT** - CI-only issue, OR severity below Important, OR new feature without regression, OR has acceptable workaround
- ⚠️ **DISCUSS** - Edge cases requiring team discussion
**Use MCP tools:**
- `mcp__atlassian__jira_get_issue` with expand="renderedFields" to get comments
- Analyze comment text for workaround mentions
### Phase 5: Generate Validation Report
Create comprehensive Markdown report with all blocker validation results.
**Report Structure:**
```markdown
# 🚫 Release Blocker Validation Report
**Components**: {component list or "All"} | **Project**: OCPBUGS | **Proposed Blockers**: {count} | **Generated**: {timestamp}
## Summary
- ✅ **Recommend APPROVE**: X
- ❌ **Recommend REJECT**: Y
- ⚠️ **Needs DISCUSSION**: Z
---
## Blocker Analysis
### {BUG-KEY}: {Summary} {VERDICT}
**Recommendation**: {APPROVE/REJECT/DISCUSS} - {One-line justification}
**Criteria Matched**:
- {✅/❌} {Criterion name}
- {✅/❌} {Criterion name}
- ...
**Justification**:
{Detailed explanation of why this bug should or shouldn't be a blocker}
**Suggested Action**: {What to do next}
---
[Repeat for each proposed blocker]
---
## Next Steps
1. Review APPROVE recommendations - add to blocker list
2. Review REJECT recommendations - remove blocker status
3. Discuss unclear cases in triage meeting
```
**Special case for single bug mode:**
When `--bug` flag is used, adapt the report to focus on a single bug:
- Summary shows single bug details (key, summary, verdict)
- Analysis section shows detailed criteria analysis for this specific bug
- Next Steps adapted for single bug action
### Phase 6: Error Handling
**Invalid issue ID (single bug mode):**
- Display error: "Could not find issue {issue-id}"
- Verify issue ID is correct format
- Check user has access to the issue
**Invalid arguments:**
- Invalid component name: Warn but continue (JIRA will return no results)
**No proposed blockers found:**
- Display success message: "✅ No proposed blockers found"
- Show filter summary (components, project: OCPBUGS)
- Confirm no blocker decisions needed
**MCP tool errors:**
- If `mcp__atlassian__jira_search` fails, display JQL query and error message
- If `mcp__atlassian__jira_get_issue` fails:
1. **Fallback to WebFetch**: Try fetching via `https://issues.redhat.com/browse/{issue-key}`
2. **If WebFetch succeeds**: Parse the web page to extract bug details (summary, severity, description) and continue with validation
3. **If WebFetch also fails**: Display clear error indicating bug doesn't exist or isn't accessible
- Provide troubleshooting guidance (check MCP server, verify credentials)
**Large result sets (>50 blockers):**
- Show progress indicators during analysis
- Consider warning user: "Found {count} proposed blockers. This may take a moment to analyze."
## Performance Considerations
- **Query optimization**: Only fetch proposed blockers (cf[12319940] = "Proposed")
- **Component scoping**: Use component filters to reduce result set size
- **Batch operations**: Use `mcp__atlassian__jira_search` with appropriate limits (avoid pagination when possible)
- **Caching**: Store bug data in memory during execution to avoid re-querying JIRA
## JQL Query Examples
**Version only (4.21):**
```jql
project = OCPBUGS AND type = Bug AND "Release Blocker" = Proposed AND ("Target Version" in (4.21, 4.21.0) OR "Target Backport Versions" in (4.21, 4.21.0) OR affectedVersion in (4.21, 4.21.0)) AND status not in (Closed, "Release Pending", Verified, ON_QA)
```
**Version + single component (4.21, "Hypershift"):**
```jql
project = OCPBUGS AND type = Bug AND "Release Blocker" = Proposed AND ("Target Version" in (4.21, 4.21.0) OR "Target Backport Versions" in (4.21, 4.21.0) OR affectedVersion in (4.21, 4.21.0)) AND status not in (Closed, "Release Pending", Verified, ON_QA) AND component = "Hypershift"
```
**Version + multiple components (4.21, multiple):**
```jql
project = OCPBUGS AND type = Bug AND "Release Blocker" = Proposed AND ("Target Version" in (4.21, 4.21.0) OR "Target Backport Versions" in (4.21, 4.21.0) OR affectedVersion in (4.21, 4.21.0)) AND status not in (Closed, "Release Pending", Verified, ON_QA) AND component IN ("Hypershift", "Cluster Version Operator")
```
**Field IDs Reference:**
- Release Blocker field: `customfield_12319743` (use `"Release Blocker"` in JQL)
- Target Version field: `customfield_12319940` (use `"Target Version"` in JQL)

258
skills/ocpbugs/SKILL.md Normal file
View File

@@ -0,0 +1,258 @@
---
name: OCPBUGS Jira Conventions
description: Jira conventions and bug templates for the OCPBUGS project
---
# OCPBUGS Jira Conventions
This skill provides conventions and requirements for creating bug reports in the OCPBUGS project, which is used by all OpenShift product teams for bug tracking.
## When to Use This Skill
Use this skill when creating bugs in the OCPBUGS project:
- **Project: OCPBUGS** - OpenShift Bugs
- **Issue Type: Bug** - Bug reports only
This skill is automatically invoked by the `/jira:create` command when the project_key is "OCPBUGS" or when issue type is "bug" without a project specified.
## Project Information
### OCPBUGS Project
**Full name:** OpenShift Bugs
**Key:** OCPBUGS
**Used for:** Bugs only
**Used by:** All OpenShift product teams
## 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.
### Affects Version/s (`versions`)
**Purpose:** Version where the bug was found
**Common values:** `4.19`, `4.20`, `4.21`, `4.22`, etc.
**Handling:**
- User should specify the version where they encountered the bug
- If not specified, prompt user: "Which version did you encounter this bug in?"
- Multiple versions can be specified if bug affects multiple releases
### Target Version (customfield_12319940)
**Purpose:** Version where the fix is targeted
**Common default:** `openshift-4.21` (or current development release)
**Override:** May be different based on:
- Severity (critical bugs may target earlier releases)
- Backport requirements
- Release schedule
**Never set:**
- Fix Version/s (`fixVersions`) - This is managed by the release team
### Version Override Handling
When user specifies a different version:
1. Accept the version as provided
2. Validate version exists using MCP tool `jira_get_project_versions` if needed
3. If version doesn't exist, suggest closest match or ask user to confirm
## Component Requirements
**IMPORTANT:** Component requirements are **team-specific**.
Some teams require specific components, while others do not. The OCPBUGS 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 bug require a component? (optional)"
- If yes, ask user to specify component name
- If no, proceed without component
## Bug Description Template
**Note:** Bug template structure and sections are defined in the `create-bug` skill.
**OCPBUGS-specific:**
- All bugs must follow the bug template format
- Version-Release number field may differ from Affects Version (can be more specific)
**Note:** Security validation (credential scanning) is defined in the `/jira:create` command and automatically applied to all tickets.
## MCP Tool Integration
### For OCPBUGS Bugs
```python
mcp__atlassian__jira_create_issue(
project_key="OCPBUGS",
summary="<bug summary>",
issue_type="Bug",
description="<formatted bug template>",
components="<component name>", # if required by team
additional_fields={
"versions": [{"name": "4.21"}], # affects version (user-specified)
"customfield_12319940": "openshift-4.21", # target version (default or user-specified)
"labels": ["ai-generated-jira"],
"security": {"name": "Red Hat Employee"}
}
)
```
### Field Mapping Reference
| Requirement | MCP Parameter | Value |
|-------------|---------------|-------|
| Project | `project_key` | `"OCPBUGS"` |
| Issue Type | `issue_type` | `"Bug"` |
| Summary | `summary` | User-provided text |
| Description | `description` | Formatted bug template |
| Component | `components` | Team-specific (optional) |
| Affects Version | `additional_fields.versions` | `[{"name": "4.21"}]` (user-specified) |
| Target Version | `additional_fields.customfield_12319940` | `"openshift-4.21"` (default or user-specified) |
| Labels | `additional_fields.labels` | `["ai-generated-jira"]` (required) |
| Security Level | `additional_fields.security` | `{"name": "Red Hat Employee"}` (required) |
## Interactive Prompts
**Note:** Detailed bug template prompts are defined in the `create-bug` skill.
**OCPBUGS-specific prompts:**
- **Affects Version** (required): "Which version did you encounter this bug in?"
- Show common versions: 4.19, 4.20, 4.21, 4.22
- **Target Version** (optional): "Which version should this be fixed in? (default: openshift-4.21)"
- **Component** (if required by team): Defer to team-specific skills
## Examples
**Note:** All examples automatically apply universal requirements (Security: Red Hat Employee, Labels: ai-generated-jira) as defined in `/jira:create` command.
### Create Bug with Minimal Info
```bash
/jira:create bug "Control plane pods crash on upgrade from 4.20 to 4.21"
```
**OCPBUGS-specific defaults:**
- Project: OCPBUGS (default for bugs)
- Target Version: openshift-4.21 (default)
**Prompts:** See `create-bug` skill for bug template prompts, plus Affects Version
### Create Bug with Full Details
```bash
/jira:create bug OCPBUGS "API server returns 500 error when creating namespaces" --component "API" --version "4.21"
```
**OCPBUGS-specific defaults:**
- Affects Version: 4.21 (from --version flag)
- Target Version: openshift-4.21 (default)
- Component: API (from --component flag)
**Prompts:** See `create-bug` skill for bug template 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 '4.21.5' not found. Did you mean '4.21.0'?"
3. Show available versions: "Available: 4.20.0, 4.21.0, 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 bug 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 bug description or logs.
**Action:**
1. STOP issue creation immediately
2. Inform user: "I detected potential credentials in the bug report."
3. Show general location: "Found in: Additional info section"
4. Do NOT echo the sensitive data back
5. Suggest: "Please sanitize logs and use placeholder values like 'YOUR_API_KEY'"
6. Wait for user to provide sanitized content
### 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 to create bugs in OCPBUGS
- **"Version not found"** → Use version error handling above
3. Provide clear next steps
4. Offer to retry after corrections
### Wrong Issue Type
**Scenario:** User tries to create a story/task/epic in OCPBUGS.
**Action:**
1. Inform user: "OCPBUGS is for bugs only. Stories/Tasks/Epics should be created in CNTRLPLANE."
2. Suggest: "Would you like to create a bug instead, or change the project to CNTRLPLANE?"
3. Wait for user decision
**Note:** Jira description formatting (Wiki markup) is defined in the `/jira:create` command.
## Team-Specific Extensions
Teams using OCPBUGS 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 bug` is invoked:
1. ✅ **OCPBUGS skill loaded:** Applies project-specific conventions
2. ⚙️ **Apply OCPBUGS defaults:**
- Project: OCPBUGS (default for bugs)
- Target version: openshift-4.21 (default)
3. 🔍 **Check for team-specific skills:** If team keywords detected, invoke team skill (e.g., `hypershift`)
4. 💬 **Interactive prompts:**
- Affects version (required)
- Bug template sections (see `create-bug` skill)
- Component (if required by team)
**Note:** Universal requirements (security, labels), security validation, and issue creation handled by `/jira:create` command.
## Best Practices
1. **Version specificity:** Use exact versions (4.21.0) not just major versions (4.21) for Affects Version
2. **Template adherence:** Defer to `create-bug` skill for bug template best practices
3. **Link related issues:** Reference related bugs, PRs, or stories
**Note:** Universal best practices (security, credential sanitization, formatting) are defined in the `/jira:create` command.
## See Also
- `/jira:create` - Main command that invokes this skill
- `cntrlplane` skill - For CNTRLPLANE stories/epics/features/tasks
- Team-specific skills (e.g., `hypershift`) - For team-specific conventions
- `create-bug` skill - General bug report best practices