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

14
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,14 @@
{
"name": "jira",
"description": "A plugin to automate tasks with Jira",
"version": "0.0.1",
"author": {
"name": "github.com/openshift-eng"
},
"skills": [
"./skills"
],
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# jira
A plugin to automate tasks with Jira

599
commands/backlog.md Normal file
View File

@@ -0,0 +1,599 @@
---
description: Find suitable JIRA tickets from the backlog to work on based on priority and activity
argument-hint: [project-key] [--assignee username] [--days-inactive N]
---
## Name
jira:backlog
## Synopsis
```
/jira:backlog [project-key] [--assignee username] [--days-inactive N]
```
## Description
The `jira:backlog` command helps identify suitable tickets from the JIRA backlog to work on by **intelligently analyzing** unassigned tickets and bot-assigned tickets. Unlike simple filtering, this command reads ticket descriptions, comments, and activity patterns to recommend the best candidates for work.
**Key Feature:** The command selects **2 tickets from each priority level** (Critical, High, Normal, Low) that are **actually available to pick up** (unassigned or assigned to bots only), giving you a balanced view across all priorities so you can choose based on your expertise and preference.
**Important:** This command only recommends tickets that are **unassigned** or **assigned to bots** (like "OCP DocsBot"). Tickets assigned to real people are excluded, even if they have no recent activity, because they may already be claimed by someone.
This command is particularly useful for:
- Finding tickets to work on when you have available capacity
- Identifying unassigned or abandoned tickets that need attention
- Getting a mix of priorities to choose from (not just critical)
- Understanding ticket context before starting work
How it works:
- Searches for unassigned tickets or tickets with no activity for 28+ days (configurable)
- **Filters for availability** - keeps only unassigned or bot-assigned tickets
- **Analyzes ticket content** - reads descriptions, comments, and activity patterns
- **Evaluates suitability** - identifies tickets that are ready vs. need verification vs. may be abandoned
- **Selects intelligently** - chooses the most suitable 2 tickets from each priority level
- Provides comprehensive summaries with recommendations for each ticket
## Prerequisites
This command requires JIRA credentials to be configured via the JIRA MCP server setup, even though it uses direct API calls instead of MCP commands.
### 1. Install the Jira Plugin
If you haven't already installed the Jira plugin, see the [Jira Plugin README](../README.md#installation) for installation instructions.
### 2. Configure JIRA Credentials via MCP Configuration File
**⚠️ Important:** While this command does NOT use MCP commands to query JIRA, it DOES read credentials from the MCP server configuration file. You must configure the MCP server settings even if you're only using this command.
**Why not use MCP commands?** The MCP approach has performance issues when fetching large datasets:
- Each MCP response must be processed by Claude, consuming tokens
- Large result sets (even with pagination) cause 413 errors from Claude due to tool result size limits
- Processing hundreds of tickets through MCP commands creates excessive context usage
- Direct API calls allow us to stream data to disk without intermediate processing
**Solution:** This command uses `curl` to fetch data directly from JIRA and save to disk, then processes it with Python. It reads JIRA credentials from `~/.config/claude-code/mcp.json` - the same file used by the MCP server.
**Required Configuration File Format:**
Create or edit `~/.config/claude-code/mcp.json`:
```json
{
"mcpServers": {
"atlassian": {
"command": "npx",
"args": ["mcp-atlassian"],
"env": {
"JIRA_URL": "https://issues.redhat.com",
"JIRA_USERNAME": "your-email@redhat.com",
"JIRA_API_TOKEN": "your-atlassian-api-token-here",
"JIRA_PERSONAL_TOKEN": "your-redhat-jira-personal-token-here"
}
}
}
}
```
**Field Descriptions:**
- `JIRA_URL`: Your JIRA instance URL (e.g., `https://issues.redhat.com` for Red Hat JIRA)
- `JIRA_USERNAME`: Your JIRA username/email address
- `JIRA_API_TOKEN`: Atlassian API token from [Atlassian API Token Management Page](https://id.atlassian.com/manage-profile/security/api-tokens)
- `JIRA_PERSONAL_TOKEN`: Red Hat JIRA Personal Access Token from [Red Hat Jira PAT Management Page](https://issues.redhat.com/secure/ViewProfile.jspa?selectedTab=com.atlassian.pats.pats-plugin:jira-user-personal-access-tokens)
**Note:** The command will use `JIRA_PERSONAL_TOKEN` if available (preferred for Red Hat JIRA), otherwise falls back to `JIRA_API_TOKEN`.
### 3. Start Local MCP Server with Podman
**⚠️ Recommended Setup:** Use the podman containerized approach. We tested npx methods on October 31, 2025, and encountered 404 errors and missing dependencies. The containerized setup works reliably.
**Steps:**
1. **First, ensure your `~/.config/claude-code/mcp.json` is created with credentials** (see example above)
2. **Start the MCP server container using credentials from mcp.json:**
```bash
# Extract credentials from your mcp.json file
JIRA_URL=$(jq -r '.mcpServers.atlassian.env.JIRA_URL' ~/.config/claude-code/mcp.json)
JIRA_USERNAME=$(jq -r '.mcpServers.atlassian.env.JIRA_USERNAME' ~/.config/claude-code/mcp.json)
JIRA_API_TOKEN=$(jq -r '.mcpServers.atlassian.env.JIRA_API_TOKEN' ~/.config/claude-code/mcp.json)
JIRA_PERSONAL_TOKEN=$(jq -r '.mcpServers.atlassian.env.JIRA_PERSONAL_TOKEN' ~/.config/claude-code/mcp.json)
# Start the container
podman run -d --name mcp-atlassian -p 8080:8080 \
-e "JIRA_URL=${JIRA_URL}" \
-e "JIRA_USERNAME=${JIRA_USERNAME}" \
-e "JIRA_API_TOKEN=${JIRA_API_TOKEN}" \
-e "JIRA_PERSONAL_TOKEN=${JIRA_PERSONAL_TOKEN}" \
-e "JIRA_SSL_VERIFY=true" \
ghcr.io/sooperset/mcp-atlassian:latest --transport sse --port 8080 -vv
```
3. **Verify the container is running:**
```bash
podman ps | grep mcp-atlassian
```
4. **Restart Claude Code** to ensure it reads the mcp.json configuration
**Managing the Container:**
```bash
# Check if container is running
podman ps | grep mcp-atlassian
# View logs
podman logs mcp-atlassian
# Stop the container
podman stop mcp-atlassian
# Start the container again
podman start mcp-atlassian
# Remove the container (you'll need to run 'podman run' again)
podman rm mcp-atlassian
```
### 4. Verify MCP Server Configuration
To verify your MCP server is properly configured and can connect to JIRA, you can test it with a simple JIRA query in Claude Code:
```bash
Ask Claude Code to run: "Use the mcp__atlassian__jira_get_issue tool to fetch OCPBUGS-1"
```
If the MCP server is properly configured, you should see issue details returned. If you see an error:
- **"Tool not found"**: The MCP server is not properly registered with Claude Code. Re-run the `claude mcp add` command.
- **"Authentication failed"** or **401/403 errors**: Check your `JIRA_PERSONAL_TOKEN` and `JIRA_USERNAME` are correct.
- **"Connection refused"**: If using a local MCP server, ensure the podman container is running (`podman ps`).
- **"Could not find issue"**: Your authentication works! This just means the specific issue doesn't exist or you don't have access.
See the [full JIRA Plugin README](../README.md) for complete setup instructions and troubleshooting.
## Implementation
The command executes the following workflow:
1. **Extract Credentials from MCP Configuration File**
- Read credentials from `~/.config/claude-code/mcp.json`
- Extract from the `atlassian` MCP server configuration:
```bash
MCP_CONFIG="$HOME/.config/claude-code/mcp.json"
JIRA_URL=$(jq -r '.mcpServers.atlassian.env.JIRA_URL' "$MCP_CONFIG")
JIRA_EMAIL=$(jq -r '.mcpServers.atlassian.env.JIRA_USERNAME // .mcpServers.atlassian.env.JIRA_EMAIL' "$MCP_CONFIG")
JIRA_PERSONAL_TOKEN=$(jq -r '.mcpServers.atlassian.env.JIRA_PERSONAL_TOKEN' "$MCP_CONFIG")
JIRA_API_TOKEN=$(jq -r '.mcpServers.atlassian.env.JIRA_API_TOKEN' "$MCP_CONFIG")
# Use JIRA_PERSONAL_TOKEN if available, otherwise fall back to JIRA_API_TOKEN
AUTH_TOKEN="${JIRA_PERSONAL_TOKEN:-$JIRA_API_TOKEN}"
```
- If any required credentials are missing or the file doesn't exist, display error:
```bash
Error: JIRA credentials not configured.
This command requires JIRA credentials from the MCP server configuration file.
Please create or edit ~/.config/claude-code/mcp.json with your JIRA credentials.
See Prerequisites section for the required mcp.json format and setup instructions.
```
2. **Parse Arguments and Set Defaults**
- Parse project key from $1 (required): "OCPBUGS", "JIRA", "HYPE", etc.
- Parse optional --assignee filter (defaults to "Unassigned")
- Parse optional --days-inactive (defaults to 28 days)
- Validate project key format (uppercase, may contain hyphens)
- Create working directory: `mkdir -p .work/jira-backlog/{project-key}/`
3. **Construct JQL Query**
- Build base JQL query:
```jql
project = {project-key}
AND status NOT IN (Closed, Resolved, Done, Verified, Release Pending, ON_QA)
AND (
assignee IS EMPTY
OR updated <= -{days-inactive}d
)
ORDER BY priority DESC, updated ASC
```
- If --assignee provided, replace assignee filter with: `AND assignee = {username} AND updated <= -{days-inactive}d`
- URL-encode the JQL query for use in API requests
4. **Fetch All Backlog Tickets Using curl with Pagination**
**Fetch Strategy:**
- Fetch 1000 tickets per request (JIRA's maximum `maxResults` value)
- Use pagination (`startAt` parameter) to fetch all tickets
- Save each batch directly to disk to avoid memory issues
- Continue until all tickets are fetched
**Authentication:**
- For Red Hat JIRA (Data Center): Use Bearer token with `JIRA_PERSONAL_TOKEN` (recommended)
- For JIRA Cloud: Can use Basic Auth with `email:api_token`, but Bearer token also works
**Important API Details:**
- Use `/rest/api/2/search` endpoint (API v2 works reliably with Red Hat JIRA)
- Use `Authorization: Bearer ${JIRA_PERSONAL_TOKEN}` header for authentication
- Check HTTP response code to detect authentication failures
**Batch Processing Loop:**
```bash
START_AT=0
BATCH_NUM=0
TOTAL_FETCHED=0
while true; do
# Construct API URL with pagination
API_URL="${JIRA_URL}/rest/api/2/search?\
jql=${ENCODED_JQL}&\
startAt=${START_AT}&\
maxResults=1000&\
fields=summary,status,priority,assignee,reporter,created,updated,description,labels,components,watches,comment"
# Fetch batch using curl with Bearer token authentication
HTTP_CODE=$(curl -s -w "%{http_code}" \
-o "batch-${BATCH_NUM}.json" \
-H "Authorization: Bearer ${AUTH_TOKEN}" \
-H "Accept: application/json" \
"${API_URL}")
# Check HTTP response code
if [ "$HTTP_CODE" -ne 200 ]; then
echo "Error: HTTP $HTTP_CODE received"
cat "batch-${BATCH_NUM}.json"
exit 1
fi
# Parse response to check if more results exist
BATCH_SIZE=$(jq '.issues | length' "batch-${BATCH_NUM}.json")
TOTAL=$(jq '.total' "batch-${BATCH_NUM}.json")
TOTAL_FETCHED=$((TOTAL_FETCHED + BATCH_SIZE))
echo "✓ Fetched ${BATCH_SIZE} tickets (${TOTAL_FETCHED}/${TOTAL} total)"
# Check if done
if [ ${TOTAL_FETCHED} -ge ${TOTAL} ] || [ ${BATCH_SIZE} -eq 0 ]; then
break
fi
# Move to next batch
START_AT=$((START_AT + 1000))
BATCH_NUM=$((BATCH_NUM + 1))
done
echo ""
echo "✓ Fetching complete: ${TOTAL_FETCHED} tickets downloaded in $((BATCH_NUM + 1)) batch(es)"
```
**Why curl instead of MCP:**
- Direct file streaming avoids Claude's tool result size limits (413 errors)
- Can handle thousands of tickets without token consumption
- Faster - no intermediate serialization through MCP protocol
- More reliable for large datasets
5. **Process Batches with Python to Filter and Group by Priority**
Create a Python script (`.work/jira-backlog/{project-key}/process_batches.py`) that:
**Inputs:**
- All batch files: `.work/jira-backlog/{project-key}/batch-*.json`
**Processing Logic:**
```python
import json
import glob
from collections import defaultdict
# Load all batches
all_tickets = []
for batch_file in sorted(glob.glob('.work/jira-backlog/{project-key}/batch-*.json')):
with open(batch_file) as f:
data = json.load(f)
all_tickets.extend(data['issues'])
# Filter for available tickets
available_tickets = []
for ticket in all_tickets:
assignee = ticket['fields'].get('assignee')
# Include if unassigned
if assignee is None:
available_tickets.append(ticket)
continue
# Include if assigned to a bot
assignee_name = assignee.get('displayName', '').lower()
if 'bot' in assignee_name:
available_tickets.append(ticket)
continue
# Otherwise exclude (assigned to real person)
# Group by priority
priority_buckets = defaultdict(list)
for ticket in available_tickets:
priority_name = ticket['fields']['priority']['name']
# Normalize priority names
if priority_name in ['Critical', 'Blocker']:
priority_buckets['Critical'].append(ticket)
elif priority_name in ['High', 'Major']:
priority_buckets['High'].append(ticket)
elif priority_name in ['Normal', 'Medium']:
priority_buckets['Normal'].append(ticket)
elif priority_name in ['Low', 'Minor', 'Trivial']:
priority_buckets['Low'].append(ticket)
# Save filtered results
with open('.work/jira-backlog/{project-key}/filtered.json', 'w') as f:
json.dump(priority_buckets, f, indent=2)
# Save statistics
stats = {p: len(tickets) for p, tickets in priority_buckets.items()}
with open('.work/jira-backlog/{project-key}/stats.json', 'w') as f:
json.dump(stats, f, indent=2)
print(f"Filtered {len(available_tickets)} available tickets from {len(all_tickets)} total")
print(f"Priority distribution: {stats}")
```
**Outputs:**
- `.work/jira-backlog/{project-key}/filtered.json` - All filtered tickets grouped by priority
- `.work/jira-backlog/{project-key}/stats.json` - Priority distribution statistics
**Run the script:**
```bash
python .work/jira-backlog/${PROJECT_KEY}/process_batches.py
```
6. **Intelligently Analyze and Select Best Tickets from Each Priority**
**CRITICAL:** This is NOT a mechanical selection process. You must read and analyze ticket content to make intelligent decisions.
**Load Filtered Data:**
- Read filtered tickets from `.work/jira-backlog/{project-key}/filtered.json`
- Data is already grouped by priority level (Critical, High, Normal, Low)
For each priority level (Critical, High, Normal, Low):
**Step 6a: Extract Tickets for Human-Readable Analysis**
- Take the first 10 tickets from each priority bucket (or all available if fewer than 10)
- For each ticket, format in a readable way showing:
- Key, summary, status, assignee, reporter
- Days since last update, number of comments, watchers
- Description preview (first 300-400 characters)
- Last 1-3 comments (author, date, first 200 characters of body)
- Components and labels
- **Output this formatted data** so you can read and analyze it
- DO NOT analyze inside Python/bash - extract the data in readable format first
**Step 6b: Analyze Ticket Suitability**
Read the formatted data and evaluate each ticket for:
**Age Classifications (consider when prioritizing):**
- **Very Fresh (< 30 days):** Highest priority - likely still relevant and active
- **Recent (30-60 days):** Good candidates - still relatively fresh
- **Getting Stale (60-90 days):** Verify still relevant before recommending
- **Old (90-120 days):** Lower priority - may need verification/grooming
- **Very Old (120+ days):** Lowest priority - likely needs re-evaluation before work
**Disqualifying Factors (skip these tickets):**
- **Assigned to real people (non-bots)** - these tickets should have been filtered out in Step 3, but double-check
- Status is "Verified", "Release Pending", "ON_QA", "Done" (already complete)
- Zero comments AND very old (120+ days) - likely abandoned
- Comments indicate "duplicate", "won't fix", "closed as"
- Comments show work is blocked or waiting on external dependencies
**Positive Indicators (prioritize these):**
- **Unassigned or bot-assigned** - available for anyone to pick up
- **Recency matters:** Fresher tickets (< 60 days) should be weighted higher
- Active discussion in comments showing real investigation (but not claimed by someone)
- Clear, reproducible issue with steps to reproduce
- Recent comments (< 30 days) saying "needs investigation", "looking for owner", "ready for work"
- Has must-gather, logs, or reproduction environment attached/linked
- Well-defined scope and acceptance criteria
- Clear description with some comments showing interest
**Step 6c: Select Best 2 from Each Priority**
- Based on your analysis, select the 2 MOST SUITABLE tickets from each priority level
- **Selection Criteria (in order of importance):**
1. **Recency:** Fresher tickets (< 60 days) strongly preferred to ensure relevance
2. **Clarity:** Clear reproduction steps, well-defined scope, available resources (must-gather, logs)
3. **Impact:** User-facing issues, customer cases, or significant system problems
4. **Activity:** Active discussion/comments showing the issue is real and being tracked
- If a priority level has fewer than 2 suitable tickets, include what's available
- Document WHY each ticket was selected (your reasoning, including age classification)
- Flag tickets that need verification before work can start
- In your recommendation, mention the ticket age using the classifications above
7. **Format Output Report**
Generate a formatted report organized by priority:
```bash
# Backlog Tickets for {project-key}
## Search Criteria
- Project: {project-key}
- Assignee: {assignee or "Unassigned"}
- Days Inactive: {days-inactive}+
- Total Tickets Found: {count}
---
## Critical Priority ({count} tickets)
### 1. {ISSUE-KEY}: {Summary}
**Status:** {status} | **Updated:** {days} days ago | **Reporter:** {name}
**Components:** {components} | **Labels:** {labels}
**Watchers:** {count} | **Comments:** {count}
**Context:**
{2-3 sentence summary of the ticket}
**Recent Activity:**
- {Most recent comment summary or "No recent comments"}
- {Status change or "No status changes"}
- {Blocker/Question if identified}
**Recommendation:** {Why this ticket is suitable to work on or what's needed before starting}
---
### 2. {ISSUE-KEY}: {Summary}
...
---
## High Priority ({count} tickets)
...
## Normal Priority ({count} tickets)
...
## Low Priority ({count} tickets)
...
---
## Summary
- Critical: {count} tickets available
- High: {count} tickets available
- Normal: {count} tickets available
- Low: {count} tickets available
**Suggested Next Steps:**
1. Review the tickets above and select one that matches your expertise
2. Check if the ticket has clear acceptance criteria - if not, consider grooming it first using `/jira:grooming {issue-key}`
3. Use `/jira:solve {issue-key} {remote}` to start working on the ticket
```
8. **Display Report to User**
- Show the formatted report
- Provide guidance on next steps
- Suggest using `/jira:grooming` for tickets lacking clarity
- Suggest using `/jira:solve` to start working on selected ticket
9. **Save Report (Optional)**
- Offer to save report to `.work/jira-backlog/{project-key}-{timestamp}.md`
- Useful for tracking backlog trends over time
**Error Handling:**
- **Missing credentials file**: If `~/.config/claude-code/mcp.json` doesn't exist, display:
```bash
Error: JIRA credentials not configured.
This command requires JIRA credentials from the MCP server configuration file.
File not found: ~/.config/claude-code/mcp.json
Please create this file with your JIRA credentials.
See Prerequisites section for the required mcp.json format and setup instructions.
```
- **Invalid credentials in file**: If credentials are missing from mcp.json, display:
```bash
Error: JIRA credentials incomplete in ~/.config/claude-code/mcp.json
Required fields in .mcpServers.atlassian.env:
- JIRA_URL (e.g., https://issues.redhat.com)
- JIRA_USERNAME (your JIRA email/username)
- JIRA_PERSONAL_TOKEN (preferred) or JIRA_API_TOKEN
See Prerequisites section for the required mcp.json format.
```
- **Authentication failure**: If curl returns 401/403, display:
```bash
Error: JIRA authentication failed (HTTP 401/403)
Please verify your JIRA credentials in ~/.config/claude-code/mcp.json:
1. Check that JIRA_PERSONAL_TOKEN is correct and not expired
2. Verify JIRA_USERNAME matches your JIRA account
3. Ensure JIRA_URL is correct (e.g., https://issues.redhat.com)
4. Test authentication: curl -H "Authorization: Bearer YOUR_TOKEN" YOUR_JIRA_URL/rest/api/2/myself
To regenerate your token, visit:
https://issues.redhat.com/secure/ViewProfile.jspa?selectedTab=com.atlassian.pats.pats-plugin:jira-user-personal-access-tokens
```
- **Invalid project key**: Display error with example format (e.g., "OCPBUGS", "JIRA", "HYPE")
- **No tickets found**:
- Explain why (e.g., all tickets have assignees and recent activity)
- Suggest relaxing search criteria (lower --days-inactive threshold)
- Suggest trying different project or removing assignee filter
- **curl errors**: Check exit code and display helpful error message
- **jq not found**: Inform user to install jq (`brew install jq` on macOS, `apt-get install jq` on Linux)
- **Rate limiting**: If API returns 429, implement exponential backoff (wait 60s, retry)
**Performance Considerations:**
- **Large batch size:** Fetch 1000 tickets per request (JIRA's maximum) for efficiency
- **Direct file storage:** Stream responses directly to disk, avoid loading into memory
- **No token consumption:** Using curl avoids Claude's context/token limits
- **Parallel-safe:** Can process very large backlogs (10,000+ tickets) without issues
- **Field filtering:** Only request needed fields to minimize response size
- **Python processing:** All filtering/analysis happens in Python, not in Claude context
- **Minimal Claude interaction:** Only present final filtered/analyzed results to user
## Return Value
- **Console Output**: Formatted report showing suggested tickets organized by priority
- **Intermediate Files** (created during processing):
- `.work/jira-backlog/{project-key}/batch-*.json` - Raw JIRA API responses (one per 1000 tickets)
- `.work/jira-backlog/{project-key}/process_batches.py` - Python script for filtering
- `.work/jira-backlog/{project-key}/filtered.json` - All filtered tickets grouped by priority
- `.work/jira-backlog/{project-key}/stats.json` - Priority distribution statistics
- **Optional Final Report**: `.work/jira-backlog/{project-key}-{timestamp}.md` containing the full report
- **Summary Statistics**: Count of available tickets per priority level
## Examples
**Note:** All examples require JIRA credentials to be configured in `~/.config/claude-code/mcp.json` (see Prerequisites section). The command uses curl to fetch data directly from JIRA's REST API, bypassing MCP commands to avoid 413 errors with large datasets.
1. **Find unassigned tickets in OCPBUGS project**:
```bash
/jira:backlog OCPBUGS
```
Output: Intelligently analyzes tickets and shows 2 recommended tickets from each priority level (Critical, High, Normal, Low)
Example performance (tested October 31, 2025):
- Fetched 2,535 tickets in 3 batches
- Found 817 available tickets (unassigned or bot-assigned)
- No 413 errors or token limit issues
2. **Find stale tickets with custom inactivity threshold**:
```bash
/jira:backlog OCPBUGS --days-inactive 14
```
Output: Report showing tickets with no activity for 14+ days, 2 per priority level
3. **Find tickets assigned to a specific user that are stale**:
```bash
/jira:backlog OCPBUGS --assignee jsmith --days-inactive 30
```
Output: Report showing tickets assigned to jsmith with 30+ days of inactivity, 2 per priority level
4. **Find tickets in Hypershift project**:
```bash
/jira:backlog HYPE
```
Output: Analyzes backlog and shows best 2 tickets from each priority in HYPE project
5. **Find tickets in CNV project**:
```bash
/jira:backlog CNV
```
Output: Report showing available backlog tickets across all priorities in CNV project
**Performance Note:** The curl-based approach can handle large backlogs efficiently. In testing with OCPBUGS (2,535 tickets), the command successfully fetched and processed all tickets without hitting Claude's token limits or encountering 413 errors.
## Arguments
- **project-key** (required): JIRA project key to search (e.g., OCPBUGS, JIRA, HYPE, CNV)
- Must be uppercase
- May contain hyphens (e.g., "MY-PROJECT")
- If not provided, will prompt user to specify
- `--assignee` (optional): Filter by assignee username
- Default: Search for unassigned tickets (assignee IS EMPTY)
- If username provided: Find tickets assigned to that user with stale activity
- Example: `--assignee jsmith` finds jsmith's stale tickets
- `--days-inactive` (optional): Number of days of inactivity to consider a ticket stale
- Default: 28 days
- Lower values find more recently inactive tickets
- Example: `--days-inactive 14` finds tickets with 14+ days of no activity

564
commands/create-release-note.md Normal file
View File

@@ -0,0 +1,564 @@
---
description: Generate bug fix release notes from Jira tickets and linked GitHub PRs
argument-hint: <issue-key>
---
## Name
jira:create-release-note
## Synopsis
```
/jira:create-release-note <issue-key>
```
## Description
The `jira:create-release-note` command automatically generates bug fix release notes by analyzing Jira bug tickets and their linked GitHub pull requests, then updates the Jira ticket with the generated release note content.
This command is particularly useful for:
- Creating consistent, well-formatted release notes across all bugs
- Automatically extracting information from multiple sources (Jira + GitHub)
- Saving time by analyzing PR code changes, commits, and descriptions
- Ensuring complete release notes with Cause, Consequence, Fix, Result, and Workaround
The command follows the standard release note template format and populates both the Release Note Type and Release Note Text fields in Jira.
## Implementation
The `jira:create-release-note` command runs in multiple phases:
### 🎯 Phase 1: Fetch and Validate Jira Bug
1. **Fetch bug ticket** using `mcp__atlassian__jira_get_issue` MCP tool:
- Request all fields to ensure we have complete data
- Verify the issue is a Bug type
- Extract issue description, links, and custom fields
2. **Validate issue type**:
- If not a Bug, warn user and ask if they want to continue
- Release notes are typically for bugs, but may apply to other types
3. **Parse bug description** to extract required sections:
- **Cause**: The root cause of the problem
- **Consequence**: The impact or effect of the problem
4. **Handle missing sections**:
- If Cause or Consequence sections are missing, inform the user
- Provide template format and ask user to update the bug description
- Optionally, allow user to provide Cause/Consequence interactively
### 🔗 Phase 2: Extract Linked GitHub PRs
Extract all linked GitHub PR URLs from multiple sources:
1. **Remote links** (Primary source - web links in Jira):
- Check the Jira issue response for web links/remote links
- Common field names: `remotelinks`, `issuelinks` with `outwardIssue.fields.issuetype.name == "GitHub PR"`
- Look for GitHub PR URLs in remote link objects
- Pattern: `https://github.com/{org}/{repo}/pull/{number}`
- Extract PR URLs and parse into `{org}/{repo}` and `{number}`
2. **Description text**: Scan bug description for GitHub PR URLs
- Use regex pattern to find PR URLs: `https://github\.com/[\w-]+/[\w-]+/pull/\d+`
- Extract and parse all matches
- **IMPORTANT**: Do NOT use `gh issue view {JIRA-KEY}` - Jira keys are not GitHub issues
3. **Comments**: Scan bug comments for GitHub PR URLs
- Iterate through comments
- Extract PR URLs using same regex pattern
- **IMPORTANT**: Only look for full GitHub PR URLs, not issue references
4. **Deduplicate**: Create unique set of PR URLs
5. **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**: Search common repos (openshift/hypershift, openshift/cluster-api-provider-*):
```bash
# Try common OpenShift repos
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
```
- Ask user to confirm which PRs are relevant
- **IMPORTANT**: Never use `gh issue view {JIRA-KEY}` - this will fail because Jira keys are not GitHub issue numbers
6. **Validate**: Ensure at least one PR is found
- If no PRs found after all attempts, show error: "No GitHub PRs found linked to {issue-key}. Please link at least one PR to generate release notes."
- Provide instructions on how to link PRs in Jira
### 📊 Phase 3: Analyze Each GitHub PR
For each linked PR, analyze multiple sources to extract Fix, Result, and Workaround information:
1. **Extract repository and PR number** from URL:
- Parse: `https://github.com/{org}/{repo}/pull/{number}`
- Store: `{org}/{repo}` as `REPO`, `{number}` as `PR_NUMBER`
2. **Fetch PR details** using `gh` CLI:
```bash
gh pr view {PR_NUMBER} --json body,title,commits,url,state --repo {REPO}
```
- Extract: title, body/description, commits array, state
- Handle errors: If PR is inaccessible, log warning and skip
3. **Fetch PR diff** using `gh` CLI:
```bash
gh pr diff {PR_NUMBER} --repo {REPO}
```
- Analyze code changes to understand what was fixed
- Look for key changes in error handling, validation, etc.
4. **Fetch PR comments** using `gh` CLI:
```bash
gh pr view {PR_NUMBER} --json comments --repo {REPO}
```
- Extract reviewer comments and author responses
- Look for clarifications about the fix or workarounds
5. **Analyze all sources**:
- **PR Title**: Often summarizes the fix
- **PR Body/Description**: Usually contains detailed explanation
- **Commit Messages**: May provide step-by-step implementation details
- **Code Changes**: Shows exactly what was modified
- **PR Comments**: May contain clarifications or additional context
6. **Extract key information**:
- **Fix**: What code/configuration changes were made to address the problem
- **Result**: What behavior changed after the fix
- **Workaround**: If mentioned, any temporary solutions before the fix
### 🤖 Phase 4: Synthesize Release Note Content
Combine information from all analyzed PRs into a cohesive release note:
1. **Combine Cause/Consequence** from Jira bug:
- Use the extracted Cause and Consequence sections
- Clean up formatting (remove Jira markup if needed)
2. **Synthesize Fix** from all PRs:
- If single PR: Use the PR's fix description
- If multiple PRs: Combine into coherent narrative
- Focus on "what was changed" rather than "how it was coded"
- Keep it concise but complete
3. **Synthesize Result** from all PRs:
- Describe the outcome after the fix is applied
- Focus on user-visible changes
- Example: "The control plane operator no longer crashes when..."
4. **Extract Workaround** (if applicable):
- Check if PRs mention temporary solutions
- Only include if a workaround was documented
- Omit this section if no workaround exists
5. **Format according to template**:
```
Cause: <extracted from bug description>
Consequence: <extracted from bug description>
Fix: <synthesized from PR analysis>
Result: <synthesized from PR analysis>
Workaround: <synthesized from PR analysis if applicable>
```
### 🔒 Phase 5: Security Validation
Scan the generated release note text for sensitive data before submission:
1. **Prohibited content patterns**:
- Credentials: Passwords, API tokens, access keys
- Cloud keys: AWS access keys (AKIA...), GCP service accounts, Azure credentials
- Kubeconfigs: Cluster credentials, service account tokens
- SSH keys: Private keys, authorized_keys content
- Certificates: PEM files, private key content
- URLs with credentials: `https://user:pass@example.com`
2. **Scanning approach**:
- Use regex patterns to detect common credential formats
- Check for base64-encoded secrets
- Look for common secret prefixes (sk_, ghp_, etc.)
3. **Action if detected**:
- STOP release note creation immediately
- Inform user what type of data was detected (without showing it)
- Example: "Detected what appears to be an API token in the release note text."
- Ask user to review PR content and redact sensitive information
- Provide guidance on safe alternatives (use placeholders like `<redacted>`, `YOUR_API_KEY`, etc.)
### 📝 Phase 6: Select Release Note Type
Prompt user to select the appropriate Release Note Type:
1. **Available options** (from Jira dropdown):
- Bug Fix (most common for OCPBUGS)
- Release Note Not Required
- Known Issue
- Enhancement
- Rebase
- Technology Preview
- Deprecated Functionality
- CVE
2. **Auto-detection** (optional):
- For OCPBUGS: Default to "Bug Fix"
- Check PR titles/descriptions for keywords
- Suggest type based on content analysis
3. **User confirmation**:
- Show suggested type
- Allow user to override
- Use `AskUserQuestion` tool for interactive selection
### ✅ Phase 7: Update Jira Ticket
Update the Jira bug ticket with generated release note:
1. **Prepare fields** for update:
```
{
"customfield_12320850": {"value": "<Release Note Type>"},
"customfield_12317313": "<Release Note Text>"
}
```
2. **Update using MCP tool**:
```
mcp__atlassian__jira_update_issue(
issue_key=<issue-key>,
fields={
"customfield_12320850": {"value": "Bug Fix"},
"customfield_12317313": "<formatted release note text>"
}
)
```
3. **Handle update errors**:
- Permission denied: User may not have rights to update these fields
- Invalid field value: Release Note Type value not in allowed list
- Field not found: Custom field IDs may be different in different Jira instances
### 📤 Phase 8: Display Results
Show the user what was created:
1. **Display generated release note**:
```
Release Note Created for {issue-key}
Type: Bug Fix
Text:
---
Cause: ...
Consequence: ...
Fix: ...
Result: ...
Workaround: ...
---
Updated: https://issues.redhat.com/browse/{issue-key}
```
2. **Provide next steps**:
- Link to the updated Jira ticket
- Suggest reviewing the release note in Jira
- Mention that the release note can be edited manually if needed
## Arguments
- **$1 – issue-key** *(required)*
Jira issue key for the bug (e.g., `OCPBUGS-12345`).
Must be a valid bug ticket with linked GitHub PRs.
## Return Value
- **Issue Key**: The Jira issue that was updated
- **Release Note Type**: The selected release note type
- **Release Note Text**: The generated release note content
- **Issue URL**: Direct link to the updated Jira ticket
## Examples
### Basic Usage
Create release note for a bug with linked PRs:
```
/jira:create-release-note OCPBUGS-38358
```
The command will:
1. Fetch the bug from Jira
2. Extract Cause and Consequence from the description
3. Find and analyze all linked GitHub PRs
4. Generate the release note
5. Prompt for Release Note Type selection
6. Update the Jira ticket
7. Display the results
### Example Output
```
Analyzing OCPBUGS-38358...
Found bug: "hostedcontrolplane controller crashes when hcp.Spec.Platform.AWS.CloudProviderConfig.Subnet.ID is undefined"
Extracted from bug description:
Cause: hostedcontrolplane controller crashes when hcp.Spec.Platform.AWS.CloudProviderConfig.Subnet.ID is undefined
Consequence: control-plane-operator enters a crash loop
Found 1 linked GitHub PR:
- https://github.com/openshift/hypershift/pull/4567
Analyzing PR #4567...
Title: "Fix panic when CloudProviderConfig.Subnet is not specified"
Commits: 2
Files changed: 3
Synthesizing release note...
Select Release Note Type:
1. Bug Fix
2. Release Note Not Required
3. Known Issue
4. Enhancement
5. CVE
Selection: 1 (Bug Fix)
Updating Jira ticket...
✓ 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
```
## Error Handling
### No GitHub PRs Linked
**Scenario**: Bug ticket has no linked GitHub PRs.
**Error Message**:
```
No GitHub PRs found linked to OCPBUGS-12345.
To generate a release note, please link at least one GitHub PR to this bug.
How to link PRs:
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
```
**Action**: Exit without updating the ticket.
### PR Not Accessible
**Scenario**: One or more linked PRs cannot be accessed.
**Warning Message**:
```
Warning: Unable to access PR https://github.com/org/repo/pull/123
Verify the PR exists and you have permissions.
Continuing with remaining PRs...
```
**Action**: Skip the inaccessible PR, continue with others. If all PRs are inaccessible, treat as "No PRs" error.
### Missing Cause or Consequence
**Scenario**: Bug description doesn't contain required Cause and/or Consequence sections.
**Error Message**:
```
Bug description is missing required sections:
- Missing: Cause
- Missing: Consequence
Please update the bug description to include these sections.
Template format:
---
Description of problem:
<problem description>
Cause:
<root cause of the problem>
Consequence:
<impact or effect of the problem>
Steps to Reproduce:
1. ...
---
Would you like to provide Cause and Consequence interactively? (yes/no)
```
**Action**:
- If user says yes: Prompt for Cause and Consequence
- If user says no: Exit and ask them to update the bug
### Security Validation Failure
**Scenario**: Generated release note contains potential credentials or secrets.
**Error Message**:
```
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
- 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.
```
**Action**: Stop immediately, do not update Jira ticket.
### Update Permission Denied
**Scenario**: User doesn't have permission to update Release Note fields.
**Error Message**:
```
Failed to update OCPBUGS-12345.
Error: You do not have permission to edit field 'Release Note Type'
This may require specific Jira permissions. Please contact your Jira administrator or use the Jira web UI to add the release note manually.
Generated release note (for manual entry):
---
Cause: ...
Consequence: ...
...
---
```
**Action**: Display the generated release note so user can manually copy it.
### Invalid Release Note Type
**Scenario**: Selected release note type is not valid for this Jira instance.
**Error Message**:
```
Failed to update Release Note Type field.
Error: Value "Bug Fix" is not valid for field customfield_12320850
This may indicate a Jira configuration issue. Please verify the allowed values for Release Note Type in your Jira instance.
```
**Action**: Ask user to select a different type or manually update in Jira.
### Multiple PRs with Conflicting Information
**Scenario**: Multiple PRs describe different fixes or contradictory information.
**Warning Message**:
```
Found 3 linked PRs with different fix descriptions:
- PR #123: Fix A
- PR #456: Fix B
- PR #789: Fix C
Combining all fixes into a single release note...
```
**Action**: Use AI to synthesize a coherent narrative combining all fixes. If truly contradictory, ask user for clarification.
## Best Practices
1. **Link PRs early**: Add GitHub PR links to bugs as soon as PRs are created
2. **Use structured bug descriptions**: Always include Cause and Consequence sections
3. **Review before submission**: Check the generated release note before confirming
4. **Sanitize PR content**: Don't include credentials in PR descriptions or commits
5. **One release note per bug**: Don't run this command multiple times for the same bug
6. **Update if needed**: Release notes can be manually edited in Jira after creation
## Prerequisites
### Required Tools
1. **MCP Jira Server**: Must be configured and accessible
- See [Jira Plugin README](../README.md) for setup instructions
- Requires read/write permissions for bugs
2. **GitHub CLI (`gh`)**: Must be installed and authenticated
- Install: `brew install gh` (macOS) or see [GitHub CLI docs](https://cli.github.com/)
- Authenticate: `gh auth login`
- Verify: `gh auth status`
3. **Access to GitHub Repositories**: Must have read access to repos where PRs are located
- PRs in private repos require appropriate GitHub permissions
- Public repos should work without additional configuration
### Required Permissions
1. **Jira Permissions**:
- Read access to bug tickets
- Write access to Release Note Type field (customfield_12320850)
- Write access to Release Note Text field (customfield_12317313)
2. **GitHub Permissions**:
- Read access to pull requests
- Read access to repository diffs and commits
## See Also
- `jira:solve` - Analyze and solve Jira issues
- `jira:create` - Create Jira issues with guided workflows
- `jira:generate-test-plan` - Generate test plans for PRs
- `jira:status-rollup` - Create status rollup reports
## Technical Notes
### Jira Custom Fields
The command uses these Jira custom field IDs:
- `customfield_12320850`: Release Note Type (dropdown)
- `customfield_12317313`: Release Note Text (text field)
These field IDs are specific to Red Hat's Jira instance. If using a different Jira instance, you may need to update the field IDs.
### GitHub CLI Rate Limits
The `gh` CLI is subject to GitHub API rate limits:
- Authenticated: 5,000 requests per hour
- This command typically uses 3-4 requests per PR (view, diff, comments)
- For bugs with many linked PRs, be aware of rate limits
### Release Note Template
The release note follows this structure:
- **Cause**: Root cause (from Jira)
- **Consequence**: Impact (from Jira)
- **Fix**: What was changed (from PRs)
- **Result**: Outcome after fix (from PRs)
- **Workaround**: Temporary solution (from PRs, optional)
This format is standard for Red Hat bug fix release notes.

579
commands/create.md Normal file
View File

@@ -0,0 +1,579 @@
---
description: Create Jira issues (story, epic, feature, task, bug, feature-request) with proper formatting
argument-hint: <type> [project-key] <summary> [--component <name>] [--version <version>] [--parent <key>]
---
## Name
jira:create
## Synopsis
```
/jira:create <type> [project-key] <summary> [options]
```
## Description
The `jira:create` command creates Jira issues following best practices and team-specific conventions. It supports creating stories, epics, features, tasks, bugs, and feature requests with intelligent defaults, interactive prompts, and validation.
This command is particularly useful for:
- Creating well-formed user stories with acceptance criteria
- Organizing epics and features with proper hierarchy
- Submitting bugs with complete reproduction steps
- Capturing customer-driven feature requests with business justification
- Maintaining consistency across team Jira practices
## Key Features
- **Multi-Type Support** - Create stories, epics, features, tasks, bugs, or feature requests from a single command
- **Smart Defaults** - Automatically applies project-specific conventions (e.g., CNTRLPLANE, OCPBUGS, RFE)
- **Interactive Guidance** - Prompts for missing information with helpful templates
- **Context Detection** - Analyzes summary text to suggest components (ARO, ROSA, HyperShift)
- **Security Validation** - Scans for credentials and secrets before submission
- **Template Support** - Provides user story templates, bug report templates, feature request workflows, acceptance criteria formats
## Implementation
The `jira:create` command runs in multiple phases:
### 🎯 Phase 1: Load Implementation Guidance
Invoke the appropriate skill based on issue type using the Skill tool:
- **Type: `story`** → Invoke `jira:create-story` skill
- Loads user story template guidance
- Provides acceptance criteria formats
- Offers story quality validation
- **Type: `epic`** → Invoke `jira:create-epic` skill
- Loads epic structure guidance
- Provides epic name field handling
- Offers parent feature linking workflow
- **Type: `feature`** → Invoke `jira:create-feature` skill
- Loads strategic planning guidance
- Provides market problem framework
- Offers success criteria templates
- **Type: `task`** → Invoke `jira:create-task` skill
- Loads technical task guidance
- Provides task vs story differentiation
- Offers acceptance criteria for technical work
- **Type: `bug`** → Invoke `jira:create-bug` skill
- Loads bug report template
- Provides structured reproduction steps
- Offers severity and reproducibility guidance
- **Type: `feature-request`** → Invoke `jira:create-feature-request` skill
- Loads customer-driven feature request guidance
- Provides 4-question workflow (title, description, business requirements, components)
- Offers component mapping from teams/operators
- Targets RFE project
### 🏢 Phase 2: Apply Project-Specific Conventions
Invoke project-specific and team-specific skills using the Skill tool as needed:
**Project-specific skills:**
- **CNTRLPLANE:** Invoke `cntrlplane` skill for CNTRLPLANE stories/epics/features/tasks
- **OCPBUGS:** Invoke `ocpbugs` skill for OCPBUGS bugs
- **Other projects:** Use only type-specific skills for best practices
**Team-specific skills:**
- Detected based on keywords in summary/description or component
- Apply team-specific conventions (component selection, custom fields, workflows)
- Layer on top of project-specific conventions
- Example: HyperShift team → invoke `hypershift` skill
**General projects** use only the type-specific skills (create-story, create-bug, etc.) for best practices.
### 📝 Phase 3: Parse Arguments & Detect Context
Parse command arguments:
- **Required:** `type`, `summary`
- **Optional:** `project_key` (may have project-specific defaults)
- **Optional flags:** `--component`, `--version`, `--parent`
Analyze summary text for context clues:
- Extract keywords that may indicate team, component, or platform
- Pass context to project-specific and team-specific skills for interpretation
- Skills handle keyword detection and component/field suggestions
### ⚙️ Phase 4: Apply Smart Defaults
**Universal requirements (MUST be applied to ALL tickets):**
- **Security level:** Red Hat Employee (required)
- **Labels:** ai-generated-jira (required)
**Project defaults:**
- May include default project for certain issue types
- Version defaults (if applicable)
- Additional labels (for tracking or automation)
**Team defaults:**
- Component selection (based on keywords or prompts)
- Custom field values
- Workflow-specific requirements
**General projects:**
- Use type-specific skills for issue structure
- Prompt for required fields as needed
### 💬 Phase 5: Interactive Prompts (Hybrid Approach)
Prompt for missing required information based on issue type:
**For Stories:**
- Offer user story template: "As a... I want... So that..."
- Collect acceptance criteria (suggest formats)
- Confirm auto-detected component
**For Epics:**
- Collect epic objective and scope
- Collect epic acceptance criteria
- Collect timeline/target release
- Set epic name field (same as summary)
- Optional parent feature link (via `--parent` or prompt)
**For Features:**
- Collect market problem description
- Collect strategic value and business impact
- Collect success criteria (adoption, usage, outcomes, business)
- Identify component epics (3-8 major work streams)
- Collect timeline and milestones
**For Tasks:**
- Collect task description (what needs to be done)
- Collect motivation/context (why it's needed)
- Optionally collect acceptance criteria
- Optionally collect technical details (files, approach)
**For Bugs:**
- Use bug template (interactive fill-in):
- Description of problem
- Version-Release number
- How reproducible (Always | Sometimes | Rarely)
- Steps to Reproduce (numbered list)
- Actual results (include error messages)
- Expected results (correct behavior)
- Additional info (logs, screenshots)
**For Feature Requests:**
- Use 4-question workflow:
1. Proposed title of feature request
2. Nature and description (current limitations, desired behavior, use case)
3. Business requirements (customer impact, regulatory drivers, justification)
4. Affected packages and components (teams, operators, component mapping)
### ✅ Phase 5.5: Summary Validation
Before security validation, validate the summary format to catch common mistakes:
**Check for anti-patterns:**
1. Summary starts with "As a" (user story format belongs in description)
2. Summary contains "I want" or "so that" (belongs in description)
3. Summary exceeds 100 characters (likely too long, may be full user story)
**Action if anti-pattern detected:**
1. Detect that user put full user story in summary field
2. Extract the key action/feature from the summary
3. Generate a concise alternative (5-10 words)
4. Prompt user for confirmation:
```
The summary looks like a full user story. Summaries should be concise titles.
Current: "As a cluster admin, I want to configure ImageTagMirrorSet in HostedCluster CRs so that I can enable tag-based image proxying"
Suggested: "Enable ImageTagMirrorSet configuration in HostedCluster CRs"
Use the suggested summary? (yes/no/edit)
```
5. If user says yes, use suggested summary
6. If user says edit, prompt for their preferred summary
7. If user says no, use their original summary (but warn it may be truncated in Jira)
**Note:** This validation should happen BEFORE creating the issue, to avoid having to update the summary afterward.
### 🔒 Phase 6: Security Validation
Scan all content (summary, description, comments) for sensitive data:
**Prohibited content:**
- Credentials (usernames/passwords, API tokens)
- Cloud keys (AWS access keys, GCP service accounts, Azure credentials)
- Kubeconfigs (cluster credentials, service account tokens)
- SSH keys (private keys, authorized_keys)
- Certificates (PEM files, private keys)
- URLs with embedded credentials (e.g., `https://user:pass@example.com`)
**Action if detected:**
- STOP issue creation immediately
- Inform user what type of data was detected (without exposing it)
- Ask user to redact sensitive information
- Provide guidance on safe alternatives (placeholder values)
### ✅ Phase 7: Create Issue via MCP
Use the `mcp__atlassian__jira_create_issue` MCP tool with collected parameters.
**Build additional_fields:**
**Required fields (MUST be included):**
- `security`: `{"name": "Red Hat Employee"}`
- `labels`: `["ai-generated-jira"]` (may be combined with additional labels)
**Project-specific and team-specific fields:**
- Custom field mappings
- Version fields
- Additional labels
- Parent links
- Component names
- Any other project/team-specific requirements
The MCP tool parameters come from the combined guidance of type-specific, project-specific, and team-specific skills, with universal requirements always applied.
**Note:** Project-specific skills (e.g., CNTRLPLANE) may implement fallback strategies for handling creation failures (such as epic linking). Refer to the project-specific skill documentation for these strategies.
### 📤 Phase 8: Return Result
Display to user:
- **Issue Key** (e.g., PROJECT-1234)
- **Issue URL** (direct link to created issue)
- **Summary of applied defaults** (any fields auto-populated by skills)
**Example output:**
```
Created: PROJECT-1234
Title: <issue summary>
URL: <issue URL>
Applied defaults:
- <Field>: <Value>
- <Field>: <Value>
(varies by project/team)
```
## Usage Examples
1. **Create a story with minimal info**:
```
/jira:create story MYPROJECT "Add user dashboard"
```
→ Prompts for user story format, acceptance criteria, and any required fields
2. **Create a story with options**:
```
/jira:create story MYPROJECT "Add search functionality" --component "Frontend" --version "2.5.0"
```
→ Uses provided component and version, prompts only for description and AC
3. **Create an epic with parent feature**:
```
/jira:create epic MYPROJECT "Mobile application redesign" --parent MYPROJECT-100
```
→ Links epic to parent feature, prompts for epic details
4. **Create a bug**:
```
/jira:create bug MYPROJECT "Login button doesn't work on mobile"
```
→ Prompts for bug template fields (description, steps, actual/expected results)
5. **Create a bug with component**:
```
/jira:create bug MYPROJECT "API returns 500 error" --component "Backend"
```
→ Uses specified component, prompts for bug details
6. **Create a task under a story**:
```
/jira:create task MYPROJECT "Update API documentation" --parent MYPROJECT-456
```
→ Links task to parent story, prompts for task description
7. **Create a feature**:
```
/jira:create feature MYPROJECT "Advanced search capabilities"
```
→ Prompts for market problem, strategic value, success criteria, epic breakdown
8. **Create a feature request**:
```
/jira:create feature-request RFE "Support custom SSL certificates for ROSA HCP"
```
→ Prompts for nature/description, business requirements, affected components (4-question workflow)
9. **Create with project-specific conventions** (examples vary by project):
```
/jira:create story SPECIALPROJECT "New capability"
```
→ Applies SPECIALPROJECT-specific skills and conventions automatically
## Arguments
- **$1 – type** *(required)*
Issue type to create.
**Options:** `story` | `epic` | `feature` | `task` | `bug` | `feature-request`
- **$2 – project-key** *(optional for bugs and feature-requests)*
JIRA project key (e.g., `CNTRLPLANE`, `OCPBUGS`, `RFE`, `MYPROJECT`).
**Default for bugs:** `OCPBUGS`
**Default for feature-requests:** `RFE`
**Required for:** stories, epics, features, tasks
- **$3 – summary** *(required)*
Issue title/summary text.
Use quotes for multi-word summaries: `"Enable automatic scaling"`
- **--component** *(optional)*
Component name (e.g., `"HyperShift / ROSA"`, `"Networking"`, `"API"`).
Auto-detected from summary context if not provided (for CNTRLPLANE/OCPBUGS).
- **--version** *(optional)*
Target version (e.g., `"4.21"`, `"4.22"`, `"2.5.0"`).
**Default varies by project:**
- CNTRLPLANE/OCPBUGS: `openshift-4.21`
- Other projects: Prompt or use project default
- **--parent** *(optional)*
Parent issue key for linking (e.g., `CNTRLPLANE-123`).
**Valid for:**
- Epics: Link to parent Feature
- Tasks: Link to parent Story or Epic
- Stories: Link to parent Epic (less common)
## Return Value
- **Issue Key**: The created Jira issue identifier (e.g., `CNTRLPLANE-1234`)
- **Issue URL**: Direct link to the created issue
- **Summary**: Confirmation of applied defaults and field values
## Configuration
### Project-Specific Skills
The command automatically detects and applies project-specific conventions:
- **CNTRLPLANE:** Uses `cntrlplane` skill for CNTRLPLANE stories/epics/features/tasks
- **OCPBUGS:** Uses `ocpbugs` skill for OCPBUGS bugs
- **Other projects:** Uses general best practices from type-specific skills
To add conventions for your project, create a skill at:
```
plugins/jira/skills/your-project-name/SKILL.md
```
Then update the command implementation to invoke your skill when the project is detected.
### Environment Variables
The command respects MCP Jira server configuration:
- **JIRA_PROJECTS_FILTER:** Filter which projects are accessible
- **JIRA_SERVER_URL:** Jira instance URL
- **JIRA_AUTH:** Authentication credentials
## Error Handling
### Invalid Issue Type
**Scenario:** User specifies invalid type.
**Action:**
```
Invalid issue type "stroy". Valid types: story, epic, feature, task, bug
Did you mean "story"?
```
### Missing Project Key
**Scenario:** Project key required but not provided.
**Action:**
```
Project key is required for stories/tasks/epics/features.
Usage: /jira:create story PROJECT-KEY "summary"
Example: /jira:create story CNTRLPLANE "Enable autoscaling"
```
### Component Required But Not Provided
**Scenario:** Project requires component, cannot auto-detect, user didn't specify.
**Action:**
```
Component is required for CNTRLPLANE issues. 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 a component (1-3):
```
### Parent Issue Not Found
**Scenario:** User specifies `--parent` but issue doesn't exist.
**Action:**
```
Parent issue CNTRLPLANE-999 not found.
Options:
1. Proceed without parent link
2. Specify different parent
3. Cancel creation
What would you like to do?
```
### Security Validation Failure
**Scenario:** Credentials or secrets detected.
**Action:**
```
I detected what appears to be an API token in the description.
Please review and redact before proceeding. Use placeholder values like:
- YOUR_API_KEY
- <redacted>
- ********
Would you like to edit the description?
```
### MCP Tool Error
**Scenario:** MCP tool returns an error.
**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"** → Fetch available versions, suggest closest match
- **"Permission denied"** → User may lack permissions, suggest contacting admin
- **"Issue type not available"** → Project may not support this issue type
### Epic Link Creation Failure
**Scenario:** Story/task creation fails when including epic link field.
**Action:**
Refer to project-specific skills for epic linking fallback strategies:
- **CNTRLPLANE:** See CNTRLPLANE skill "Epic Linking Implementation Strategy" section
- **Other projects:** Consult project-specific skill documentation
**General pattern:**
1. Detect error related to linking (error contains "epic", "parent", "link", or "customfield")
2. Check project-specific skill for recommended fallback approach
3. Typically: Create without link, then link via update
4. Inform user of outcome
5. **Last stand fallback:** If all strategies fail (including update-after-create), retry with absolute minimal fields:
- Remove ALL custom fields (epic link, target version, etc.)
- Keep only: project_key, summary, issue_type, description, assignee, components
- Log to console what was stripped out
- If this succeeds, inform user which fields need manual configuration in Jira
### Field Format Error
**Scenario:** Field provided in wrong format (e.g., Target Version as string instead of array).
**Common field format errors:**
1. **Target Version format**
- ❌ Wrong: `"customfield_12319940": "openshift-4.21"`
- ✅ Correct: `"customfield_12319940": [{"id": "12448830"}]`
- **Action:** Fetch version ID using `mcp__atlassian__jira_get_project_versions`, convert to correct format
2. **Epic Link format**
- ❌ Wrong: `"parent": {"key": "EPIC-123"}` (for stories)
- ✅ Correct: `"customfield_12311140": "EPIC-123"` (string, not object)
- **Action:** Convert to correct format and retry
3. **Component format**
- ❌ Wrong: `"components": "ComponentName"`
- ✅ Correct: `"components": ["ComponentName"]` (array) or just `"ComponentName"` (MCP accepts both)
- **Action:** Ensure consistent format
**Detection:**
- Parse error message for field names
- Check skill documentation for correct format
- Automatically convert and retry when possible
## Best Practices
1. **Use descriptive summaries:** Include relevant keywords for context and auto-detection
2. **Provide flags when known:** Use `--component` and `--version` to skip prompts
3. **Link related work:** Use `--parent` to maintain hierarchy
4. **Review before submit:** Check the formatted content before confirming creation
5. **Follow templates:** Use the provided templates for consistency
6. **Sanitize content:** Remove credentials before including logs or screenshots
## Anti-Patterns to Avoid
❌ **Wrong issue type**
```
/jira:create story MYPROJECT "Refactor database layer"
```
✅ This is technical work, use `task` instead
❌ **Vague summaries**
```
/jira:create bug "Something is broken"
```
✅ Be specific: "API server returns 500 error when creating namespaces"
❌ **Missing context**
```
/jira:create epic MYPROJECT "Improve things"
```
✅ Be descriptive: "Mobile application redesign"
❌ **Including credentials**
```
Steps to reproduce:
1. Export API_KEY=sk_live_abc123xyz
```
✅ Use placeholders: "Export API_KEY=YOUR_API_KEY"
## See Also
- `jira:solve` - Analyze and solve Jira issues
- `jira:grooming` - Generate grooming meeting agendas
- `jira:status-rollup` - Create status rollup reports
- `jira:generate-test-plan` - Generate test plans for PRs
## Skills Reference
The following skills are automatically invoked by this command:
**Type-specific skills:**
- **create-story** - User story creation guidance
- **create-epic** - Epic creation and structure
- **create-feature** - Feature planning and strategy
- **create-task** - Technical task creation
- **create-bug** - Bug report templates
- **create-feature-request** - Customer-driven feature request workflow for RFE project
**Project-specific skills:**
- **cntrlplane** - CNTRLPLANE project conventions (stories, epics, features, tasks)
- **ocpbugs** - OCPBUGS project conventions (bugs only)
**Team-specific skills:**
- **hypershift** - HyperShift team conventions (component selection for ARO/ROSA/HyperShift)
To view skill details:
```bash
ls plugins/jira/skills/
cat plugins/jira/skills/create-story/SKILL.md
cat plugins/jira/skills/create-feature-request/SKILL.md
cat plugins/jira/skills/cntrlplane/SKILL.md
cat plugins/jira/skills/ocpbugs/SKILL.md
cat plugins/jira/skills/hypershift/SKILL.md
```

186
commands/generate-test-plan.md Normal file
View File

@@ -0,0 +1,186 @@
---
description: Generate test steps for a JIRA issue
argument-hint: [JIRA issue key] [GitHub PR URLs]
---
## Name
jira:generate-test-plan
## Synopsis
/jira:generate-test-plan [JIRA issue key] [GitHub PR URLs]
## Description
The 'jira:generate-test-plan' command takes a JIRA issue key and optionally a list of PR URLs. It fetches the JIRA issue details, retrieves all related PRs (or uses the provided PR list), analyzes the changes, and generates a comprehensive manual testing guide.
**JIRA Issue Test Guide Generator**
## Implementation
- The command uses curl to fetch JIRA data via REST API: https://issues.redhat.com/rest/api/2/issue/{$1}
- Uses WebFetch to extract PR links from JIRA issue if no PRs provided
- Uses `gh pr view` to fetch PR details for each PR
- Analyzes changes across all PRs to understand implementation
- Generates comprehensive manual test scenarios
## Process Flow:
1. **JIRA Analysis**: Fetch and parse JIRA issue details:
- Use curl to fetch JIRA issue data: `curl -s "https://issues.redhat.com/rest/api/2/issue/{$1}"`
- Parse JSON response to extract:
- Issue summary and description
- Context and acceptance criteria
- Steps to reproduce (for bugs)
- Expected vs actual behavior
- Extract issue type (Story, Bug, Task, etc.)
2. **PR Discovery**: Get list of PRs to analyze:
- **If no PRs provided in arguments** ($2, $3, etc. are empty):
- Use WebFetch on https://issues.redhat.com/browse/{$1}
- Extract all GitHub PR links from:
- "Issue Links" section
- "Development" section
- PR links in comments
- **If PRs provided in arguments**:
- Use only the PRs provided in $2, $3, $4, etc.
- Ignore any other PRs linked to the JIRA
3. **PR Analysis**: For each PR, fetch and analyze:
- Use `gh pr view {PR_NUMBER} --repo <your repo> --json title,body,commits,files,labels`
- Extract:
- PR title and description
- Changed files and their diffs
- Commit messages
- PR status (merged, open, closed)
- Read changed files to understand implementation details
- Use Grep and Glob tools to:
- Find related test files
- Locate configuration or documentation
- Identify dependencies
4. **Change Analysis**: Understand what was changed across all PRs:
- Identify the overall objective (bug fix, feature, refactor)
- Determine affected components (API, CLI, operator, control-plane, etc.)
- Find platform-specific changes (AWS, Azure, KubeVirt, etc.)
- Map which PR addresses which aspect of the JIRA
- Identify any dependencies between PRs
5. **Test Scenario Generation**: Create comprehensive test plan:
- Map JIRA acceptance criteria to test scenarios
- For bugs: Use reproduction steps as test cases
- Generate test scenarios covering:
- Happy path scenarios (based on acceptance criteria)
- Edge cases and error handling
- Platform-specific variations if applicable
- Regression scenarios
- For multiple PRs:
- Create integrated test scenarios
- Verify PRs work correctly together
- Test each PR's contribution to the overall solution
6. **Test Guide Creation**: Generate detailed manual testing document:
- **Filename**: Always use JIRA key format: `test-{JIRA_KEY}.md`
- Convert JIRA key to lowercase
- Examples: `test-cntrlplane-205.md`, `test-ocpbugs-12345.md`
- **Structure**:
- **JIRA Summary**: Include JIRA key, title, description, acceptance criteria
- **PR Summary**: List all PRs with titles and how they relate to the JIRA
- **Prerequisites**:
- Required infrastructure and tools
- Environment setup requirements
- Access requirements
- **Test Scenarios**:
- Map each test to JIRA acceptance criteria
- Numbered test cases with clear steps
- Expected results with verification commands
- Platform-specific test variations
- **Regression Testing**:
- Related features to verify
- Areas that might be affected
- **Success Criteria**:
- Checklist mapping to JIRA acceptance criteria
- **Troubleshooting**:
- Common issues and debug steps
- **Notes**:
- Known limitations
- Links to JIRA and all PRs
- Critical test cases highlighted
7. **Exclusions**: Apply smart filtering:
- **Skip PRs that don't require testing**:
- PRs that only add documentation (.md files only)
- PRs that only add CI/tooling (.github/, .claude/ directories)
- PRs marked with labels like "skip-testing" or "docs-only"
- **Note skipped PRs** in the test guide with reasoning
- Focus test scenarios on PRs with actual code changes
8. **Output**: Display the testing guide:
- Show the file path where the guide was saved
- Provide a summary of:
- JIRA issue being tested
- Number of PRs included
- Number of test scenarios generated
- Critical test cases to focus on
- Highlight any PRs that were skipped and why
- Ask if the user would like any modifications to the test guide
## Examples:
1. **Generate test steps for JIRA with auto-discovered PRs**:
`/jira:generate-test-plan CNTRLPLANE-205`
2. **Generate test steps for JIRA with specific PRs only**:
`/jira:generate-test-plan CNTRLPLANE-205 https://github.com/openshift/hypershift/pull/6888`
3. **Generate test steps for multiple specific PRs**:
`/jira:generate-test-plan CNTRLPLANE-205 https://github.com/openshift/hypershift/pull/6888 https://github.com/openshift/hypershift/pull/6889`
## Arguments:
- **$1**: JIRA issue key (required) - e.g., CNTRLPLANE-205, OCPBUGS-12345
- **$2, $3, ..., $N**: Optional GitHub PR URLs
- If provided: Only these PRs will be analyzed
- If omitted: All PRs linked to the JIRA will be discovered and analyzed
## Smart Features:
1. **Automatic PR Discovery**:
- Scans JIRA issue for all related PRs
- Identifies PRs in "Issue Links", "Development" section, and comments
2. **Selective PR Testing**:
- Allows manual override to test specific PRs only
- Useful when JIRA has many PRs but only some need testing
3. **Context-Aware Test Generation**:
- Bug fixes: Focus on reproduction steps and verification
- Features: Focus on acceptance criteria and user workflows
- Refactors: Focus on regression and functional equivalence
4. **Multi-PR Integration**:
- Understands how multiple PRs work together
- Creates integration test scenarios
- Identifies dependencies and testing order
5. **Build/Deploy Section Exclusion**:
- Does NOT include build or deployment steps
- Assumes environment is already set up
- Focuses purely on testing procedures
6. **Cleanup Section Exclusion**:
- Does NOT include cleanup steps
- Focuses on test execution and verification
## Example Workflow:
```bash
# Auto-discover all PRs from JIRA
/jira:generate-test-plan CNTRLPLANE-205
# Test only specific PRs
/jira:generate-test-plan CNTRLPLANE-205 https://github.com/openshift/hypershift/pull/6888
# Test multiple specific PRs
/jira:generate-test-plan OCPBUGS-12345 https://github.com/openshift/hypershift/pull/1234 https://github.com/openshift/hypershift/pull/1235
```
The command will provide a comprehensive manual testing guide that QE or developers can use to thoroughly test the JIRA issue implementation.

200
commands/grooming.md Normal file
View File

@@ -0,0 +1,200 @@
---
description: Analyze new bugs and cards added over a time period and generate grooming meeting agenda
argument-hint: [project-filter] [time-period] [--component component-name] [--label label-name] [--type issue-type]
---
## Name
jira:grooming
## Synopsis
```
/jira:grooming [project-filter] [time-period] [--component component-name] [--label label-name] [--type issue-type]
```
## Description
The `jira:grooming` command helps teams prepare for backlog grooming meetings. It automatically collects bugs and user stories created within a specified time period OR assigned to a specific sprint, analyzes their priority, complexity, and dependencies, and generates structured grooming meeting agendas.
This command is particularly useful for:
- Backlog organization before sprint planning
- Sprint-specific grooming sessions
- Regular requirement grooming meetings
- Priority assessment of new bugs
- Technical debt organization and planning
## Key Features
- **Automated Data Collection** – Collect and categorize issues within specified time periods or sprints by type (Bug, Story, Task, Epic), extract key information (priority, components, labels), and identify unassigned or incomplete issues.
- **Intelligent Analysis** – Evaluate issue complexity based on historical data, identify related or duplicate issues, analyze business value and technical impact, and detect potential dependencies.
- **Agenda Generation** – Build a structured, actionable meeting outline organized by priority and type, with discussion points, decision recommendations, estimation references, and risk alerts.
## Implementation
The `jira:grooming` command runs in three main phases:
### 🧩 Phase 1: Data Collection
- Automatically queries JIRA for issues based on the provided time range or sprint name:
- **Time range mode**: Filters issues by creation date within the specified period (e.g., `last-week`, `2024-01-01:2024-01-31`)
- **Sprint mode**: Filters issues by JIRA Sprint without time constraints (e.g., `"OTA 277"`)
- Sprint detection: If the time-period parameter doesn't match known time range formats, it's treated as a sprint name
- Supports complex JQL filters, including multi-project, component-based, label-based, and issue-type queries.
- Extracts key fields such as title, type, priority, component, reporter, and assignee.
- Detects related or duplicate issues to provide better context.
### 🧠 Phase 2: Analysis & Processing
- Groups collected issues by type and priority (e.g., Critical Bugs, High Priority Stories).
- Identifies incomplete or unclear issues that need clarification.
- Estimates complexity and effort based on similar historical data.
- Highlights risks, dependencies, and recommended next actions.
### 📋 Phase 3: Report Generation
- Automatically generates a **structured grooming meeting agenda** in Markdown format.
- Includes discussion points, decision checklists, and action items.
- Output can be copied directly into Confluence or shared with the team.
## Usage Examples
1. **Single project weekly review**:
```
/jira:grooming OCPSTRAT last-week
```
2. **Multiple OpenShift projects**:
```
/jira:grooming "OCPSTRAT,OCPBUGS,HOSTEDCP" last-2-weeks
```
3. **Filter by component**:
```
/jira:grooming OCPSTRAT last-week --component "Control Plane"
```
4. **Custom date range**:
```
/jira:grooming OCPBUGS 2024-10-01:2024-10-15
```
5. **Filter by label**:
```
/jira:grooming OCPSTRAT last-week --label "technical-debt"
```
6. **Combine component and label filters**:
```
/jira:grooming OCPSTRAT last-week --component "Control Plane" --label "performance"
```
7. **Query sprint issues with component filter**:
```bash
/jira:grooming OCPBUGS "OTA 277" --component "Cluster Version Operator"
```
8. **Filter by issue type**:
```
/jira:grooming OCPSTRAT last-week --type Bug
```
9. **Filter by multiple issue types**:
```
/jira:grooming OCPSTRAT last-week --type "Bug,Epic"
```
10. **Combine all filters**:
```
/jira:grooming OCPSTRAT last-week --component "Control Plane" --label "performance" --type Story
```
## Output Format
### Grooming Meeting Agenda
The command outputs a ready-to-use Markdown document that can be copied into Confluence or shared with your team.
```markdown
# Backlog Grooming Agenda
**Project**: [project-key] | **Period**: [time-period] | **New Issues**: [count]
## 🚨 Critical Issues ([count])
- **[PROJ-1234]** System crashes on login - *Critical, needs immediate attention*
- **[PROJ-1235]** Performance degradation - *High, assign to team lead*
## 📈 High Priority Stories ([count])
- **[PROJ-1236]** User profile enhancement - *Ready for sprint*
- **[PROJ-1237]** Payment integration - *Needs design review*
## 📝 Needs Clarification ([count])
- **[PROJ-1238]** Missing acceptance criteria
- **[PROJ-1239]** Unclear technical requirements
## 📋 Action Items
- [ ] Assign PROJ-1234 to senior developer (immediate)
- [ ] Schedule design review for PROJ-1237 (this week)
- [ ] Clarify requirements for PROJ-1238,1239 (before next grooming)
```
## Configuration
### Default Query Configuration (.jira-grooming.json)
```json
{
"defaultProjects": ["OCPSTRAT", "OCPBUGS"],
"defaultLabels": [],
"priorityMapping": {
"Critical": "🚨 Critical",
"High": "📈 High Priority"
},
"estimationReference": {
"enableHistoricalComparison": true
}
}
```
## Arguments
- **$1 – project-filter**
JIRA project selector. Supports single or multiple projects (comma-separated).
Examples:
- `OCPSTRAT`
- `"OCPSTRAT,OCPBUGS,HOSTEDCP"`
- `"OpenShift Virtualization,Red Hat OpenShift Control Planes"`
Default: read from configuration file
- **$2 – time-period**
Time range for issue collection OR sprint name.
Options:
- Time ranges: `last-week` | `last-2-weeks` | `last-month` | `YYYY-MM-DD:YYYY-MM-DD`
- Sprint name: Any string that doesn't match time range formats (e.g., `"OTA 277"`)
Default: `last-week`
**Behavior:**
- If a time range is provided, filters issues by creation date within that range
- If a sprint name is provided, filters issues by JIRA Sprint WITHOUT applying time range constraints
- **--component** *(optional)*
Filter by JIRA component (single or comma-separated).
Examples:
- `--component "Networking"`
- `--component "Control Plane,Storage"`
- **--label** *(optional)*
Filter by JIRA labels (single or comma-separated).
Examples:
- `--label "technical-debt"`
- `--label "performance,security"`
- **--type** *(optional)*
Filter by JIRA issue type (single or comma-separated).
Examples:
- `--type Bug`
- `--type "Epic,Story"`
- `--type "Bug,Task,Feature"`
Common issue types: `Bug`, `Story`, `Task`, `Epic`, `Feature`, `Sub-task`
## Return Value
- **Markdown Report**: Ready-to-use grooming agenda with categorized issues and action items
## See Also
- `jira:status-rollup` - Status rollup reports
- `jira:solve` - Issue solution generation

133
commands/solve.md Normal file
View File

@@ -0,0 +1,133 @@
---
description: Analyze a JIRA issue and create a pull request to solve it.
---
## Name
jira:solve
## Synopsis
```
/jira:solve <jira-issue-id> [remote]
```
## Description
The `jira:solve` command analyzes a JIRA issue and creates a pull request to solve it.
This command takes a JIRA URL, fetches the issue description and requirements, analyzes the codebase to understand how to implement the solution, and creates a comprehensive pull request with the necessary changes.
**Usage Examples:**
1. **Solve a specific JIRA issue**:
```
/jira:solve OCPBUGS-12345 origin
```
## Implementation
- The command uses curl to fetch JIRA data via REST API: https://issues.redhat.com/rest/api/2/issue/{$1}
- Parses JSON response using jq or text processing
- Extracts key fields: summary, description, components, labels
- No authentication required for public Red Hat JIRA issues
- Creates a PR with the solution
### Process Flow
1. **Issue Analysis**: Parse JIRA URL and fetch issue details:
- Use curl to fetch JIRA issue data: curl -s "https://issues.redhat.com/rest/api/2/issue/{$1}"
- Parse JSON response to extract:
- Issue summary and description
- From within the description expect the following sections
- Required
- Context
- Acceptance criteria
- Optional
- Steps to reproduce (for bugs)
- Expected vs actual behavior
- Ask the user for further issue grooming if the requried sections are missing
2. **Codebase Analysis**: Search and analyze relevant code:
- Find related files and functions
- Understand current implementation
- Identify areas that need changes
- Use Grep and Glob tools to search for:
- Related function names mentioned in JIRA
- File patterns related to the component
- Similar existing implementations
- Test files that need updates
3. **Solution Implementation**:
- Think hard and create a detailed, step-by-step plan to implement this feature. Save it to spec-$1.md within the .work/jira/solve folder, for example .work/jira/solve/spec-OCPBUGS-12345.md
- Always ask the user to review the plan and give them the choice to modify it before start the implementation
- Implement the plan:
- Make necessary code changes using Edit/MultiEdit tools
- Follow existing code patterns and conventions
- Add or update tests as needed
- Update documentation if needed within the docs/ folder
- If the problem is too complex consider delegating to one of the SME agents.
- Ensure godoc comments are generated for any newly created public functions
- Use your best judgement if godoc comments are needed for private functions
- For example, a comment should not be generated for a simple function like func add(int a, b) int { return a + b}
- Create unit tests for any newly created functions
- After making code changes, verify the implementation based on the repository's tooling:
- **Check for Makefile**: Run `ls Makefile` to see if one exists
- **If Makefile exists**: Check available targets with `make help` or `grep '^[^#]*:' Makefile | head -20`
- **Run appropriate verification commands**:
- If `make lint-fix` exists: Run it to ensure imports are properly sorted and linting issues are fixed
- If `make verify`, `make build`, `make test` exist: Run these to ensure code builds and passes tests
- If no Makefile or make targets: Look for alternative commands:
- Go projects: `go fmt ./...`, `go vet ./...`, `go test ./...`, `go build ./...`
- Node.js: `npm test`, `npm run build`, `npm run lint`
- Python: `pytest`, `python -m unittest`, `pylint`, `black .`
- Other: Follow repository conventions in CI config files (.github/workflows/, .gitlab-ci.yml, etc.)
- **Never assume make targets exist** - always verify first
- **You must ensure verification passes** before proceeding to "Commit Creation"
4. **Commit Creation**:
- Create feature branch using the jira-key $1 as the branch name. For example: "git checkout -b fix-{jira-key}"
- Break commits into logical components based on the nature of the changes
- Each commit should honor https://www.conventionalcommits.org/en/v1.0.0/ and always include a commit message body articulating the "why"
- Use your judgment to organize commits in a way that makes them easy to review and understand
- Common logical groupings (use as guidance, not rigid rules):
- API changes: Changes in `api/` directory (types, CRDs)
- Example: `git commit -m"feat(api): Update HostedCluster API for X" -m"Add new fields to support Y functionality"`
- Vendor changes: Dependency updates in `vendor/` directory
- Example: `git commit -m"chore(vendor): Update dependencies for X" -m"Required to pick up bug fixes in upstream library Y"`
- Generated code: Auto-generated clients, informers, listers, and CRDs
- Example: `git commit -m"chore(generated): Regenerate clients and CRDs" -m"Regenerate after API changes to ensure client code is in sync"`
- CLI changes: User-facing command changes in `cmd/` directory
- Example: `git commit -m"feat(cli): Add support for X flag" -m"This allows users to configure Y behavior at cluster creation time"`
- Operator changes: Controller logic in `operator/` or `controllers/`
- Example: `git commit -m"feat(operator): Implement X controller logic" -m"Without this the controller won't reconcile when Y condition occurs"`
- Support/utilities: Shared code in `support/` directory
- Example: `git commit -m"refactor(support): Extract common X utility" -m"Consolidate duplicated logic from multiple controllers into shared helper"`
- Tests: Test additions or modifications
- Example: `git commit -m"test: Add tests for X functionality" -m"Ensure the new behavior is covered by unit tests to prevent regressions"`
- Documentation: Changes in `docs/` directory
- Example: `git commit -m"docs: Document X feature" -m"Help users understand how to configure and use the new capability"`
5. **PR Creation**:
- Push the branch with all commits against the remote specified in argument $2
- Create pull request with:
- Clear title referencing JIRA issue as a prefix. For example: "OCPBUGS-12345: ..."
- The PR description should satisfy the template within .github/PULL_REQUEST_TEMPLATE.md if the file exists
- The "🤖 Generated with Claude Code" sentence should include a reference to the slash command that triggered the execution, for example "via `/jira-solve OCPBUGS-12345 enxebre`"
- Always create as draft PR
- Always create the PR against the remote origin
- Use gh cli if you need to
6. **PR Description Review**:
- After creating the PR, display the PR URL and description to the user
- Ask the user: "Please review the PR description. Would you like me to update it? (yes/no)"
- If the user says yes or requests changes:
- Ask what changes they'd like to make
- Update the PR description using `gh pr edit {PR_NUMBER} --body "{new_description}"`
- Repeat this review step until the user is satisfied
- If the user says no or is satisfied, acknowledge and provide next steps
## Arguments:
- $1: The JIRA issue to solve (required)
- $2: The remote repository to push the branch. Defaults to "origin".
The command will provide progress updates and create a comprehensive solution addressing all requirements from the JIRA issue.

203
commands/status-rollup.md Normal file
View File

@@ -0,0 +1,203 @@
---
description: Generate a status rollup comment for any JIRA issue based on all child issues and a given date range
argument-hint: issue-id [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD]
---
## Name
jira:status-rollup
## Synopsis
```
/jira:status-rollup issue-id [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD]
```
## Description
The `jira:status-rollup` command generates a comprehensive status rollup for any JIRA issue (Feature, Epic, Story, etc.) by recursively analyzing all child issues and their activity within a specified date range. The command intelligently extracts insights from changelogs and comments to create a concise, well-formatted status summary that can be reviewed and refined before being posted to Jira.
This command is particularly useful for:
- Weekly status updates on Features or Epics
- Sprint retrospectives and planning
- Executive summaries of complex work hierarchies
- Identifying blockers and risks across multiple issues
Key capabilities:
- Recursively traverses entire issue hierarchies (any depth)
- Analyzes status transitions, assignee changes, and priority shifts
- Extracts blockers, risks, and completion insights from comments
- Generates properly formatted Jira wiki markup with nested bullets
- Caches all data in a temp file for fast iterative refinement
- Allows review and modification before posting to Jira
[Extended thinking: This command takes any JIRA issue ID (Feature, Epic, Story, etc.) and optional date range, recursively collects all descendant issues, analyzes their changes and comments within the date range, and generates a concise status summary rolled up to the parent issue level. The summary is presented to the user for review and refinement before being posted as a comment.]
## Implementation
The command executes the following workflow:
1. **Parse Arguments and Validate**
- Extract issue ID from $1
- Parse --start-date and --end-date if provided
- Validate date format (YYYY-MM-DD)
- Default to issue creation date if no start-date provided
- Default to today if no end-date provided
2. **Issue Validation**
- Use `mcp__atlassian__jira_get_issue` to fetch the issue
- Verify the issue exists and is accessible
- Extract issue key, summary, type, and basic info
- Works with any issue type (Feature, Epic, Story, Task, etc.)
3. **Data Collection - Build Issue Hierarchy**
- Find direct children using JQL: `parent = {issue-id}`
- Recursively find all descendant issues (any depth)
- Fetch detailed issue data for each issue (status, summary, assignee, etc.)
- Use `mcp__atlassian__jira_batch_get_changelogs` for all issue keys
- Filter changelog entries to date range (status transitions, assignee changes, etc.)
- Fetch comments using `expand=renderedFields`, filter by date range
- Save all data to temp file: `/tmp/jira-rollup-{issue-id}-{timestamp}.md`
4. **Data Analysis - Derive Status**
- Calculate completion metrics (total, done, in-progress, blocked, percentage)
- Identify issues completed/started/blocked within date range
- Extract significant status transitions and key changes
- Analyze comments for keywords:
- **Blockers**: "blocked", "waiting on", "stuck", "dependency"
- **Risks**: "risk", "concern", "problem", "at risk"
- **Completion**: "completed", "done", "merged", "delivered"
- **Progress**: "started", "working on", "implementing"
- **Help needed**: "need", "require", "help", "support"
- Extract entities: team mentions, dependencies, PR references, deadlines
- Prioritize comments (high/medium/low based on keywords)
- Cross-reference comments with status transitions
- Assess overall health (on track, at risk, blocked, complete)
- Append analysis results to temp file
5. **Generate Status Summary**
- Read from temp file (NO re-fetching from Jira)
- Create formatted summary in Jira wiki markup:
```
h2. Status Rollup From: {start-date} to {end-date}
*Overall Status:* [Clear statement about health and progress]
*This Week:*
* Completed:
*# [ISSUE-ID] - [Specific achievement from comments]
*# [ISSUE-ID] - [Specific achievement from comments]
* In Progress:
*# [ISSUE-ID] - [Current state and specific details]
* Blocked:
*# [ISSUE-ID] - [Specific reason for blocker]
*Next Week:*
* [Planned item based on analysis]
*Metrics:* X/Y issues complete (Z%)
```
- Use specific insights from comments (NOT vague phrases like "ongoing work")
- Include PR references, ticket numbers, specific tasks mentioned
- Add direct quotes when they provide critical context
- Use `*#` syntax for nested bullets (Jira wiki markup)
6. **Present to User for Review**
- Display temp file location for verification
- Show generated summary
- Ask if user wants changes
7. **Iterative Refinement**
- If user requests changes, read from temp file (don't re-fetch)
- Support refinement strategies:
- Focus more on blockers/risks/completion
- Add/remove technical details or quotes
- Change grouping (by epic, type, status, assignee)
- Adjust level of detail (high-level vs. detailed)
- Regenerate only affected sections
- Repeat until user satisfied
8. **Post Comment to Issue**
- Use `mcp__atlassian__jira_add_comment` to post to parent issue
- Append footer: "🤖 Generated with [Claude Code](https://claude.com/claude-code) via `/jira:status-rollup {issue-id} --start-date {date} --end-date {date}`"
- Confirm with user and provide issue URL
9. **Temp File Cleanup**
- Ask user if they want to keep `/tmp/jira-rollup-{issue-id}-{timestamp}.md`
- Delete if user says no, otherwise keep for reference
**Error Handling:**
- Invalid issue ID: Display error with verification instructions
- No child issues: Offer to generate summary for single issue
- No activity in date range: Generate summary based on current state
- Invalid date format: Display error with correct format example
- Large hierarchies (100+ issues): Show progress indicators
**Performance Considerations:**
- Use batch API endpoints where available
- Implement appropriate delays to respect rate limits
- Cache all data in temp file for instant refinement
## Return Value
- **Posted to Jira**: Formatted status comment on the parent issue
- **Temp file**: `/tmp/jira-rollup-{issue-id}-{timestamp}.md` containing:
- Parent issue details
- Complete issue hierarchy with counts by type
- Raw changelog data for all issues
- All comments with metadata (author, date, issue key)
- Comment analysis (keywords, priorities, cross-references)
- Metrics summary
## Examples
1. **Generate status for a Feature for a specific week**:
```
/jira:status-rollup FEATURE-123 --start-date 2025-01-06 --end-date 2025-01-13
```
Output: Weekly status comment posted to FEATURE-123
2. **Generate status for an Epic**:
```
/jira:status-rollup EPIC-456 --start-date 2025-01-06 --end-date 2025-01-13
```
Output: Epic status summary with all child stories analyzed
3. **Generate status for a Story with subtasks**:
```
/jira:status-rollup STORY-789
```
Output: Status from story creation date to today
4. **Generate status from a start date to now**:
```
/jira:status-rollup CNTRLPLANE-1234 --start-date 2025-01-06
```
Output: Status from Jan 6 to today
**Example Output:**
```
h2. Weekly Status: 2025-01-06 to 2025-01-13
*Overall Status:* Feature is on track. Core authentication work completed this week with 2 PRs merged. UI integration starting with design approved.
*This Week:*
* Completed:
*# AUTH-101 - OAuth2 implementation (PR #456 merged, all review feedback addressed)
*# AUTH-102 - OAuth2 token validation (unit tests added, edge cases handled)
* In Progress:
*# UI-201 - Login UI components (design review completed, implementing responsive layout for mobile)
*# AUTH-103 - Session handling (refactoring cookie storage mechanism, PR in draft)
* Blocked:
*# AUTH-104 - Azure AD integration (blocked on subscription approval, escalated to infrastructure team). Per Jane Doe: "Need Azure subscription approved before proceeding - submitted ticket #12345"
*Next Week:*
* Complete session handling refactor (AUTH-103) and submit for review
* Finish login UI responsive implementation (UI-201) once design assets are finalized
* Begin end-to-end testing (AUTH-107) if session handling is merged
*Metrics:* 8/15 issues complete (53%)
🤖 Generated with [Claude Code](https://claude.com/claude-code) via `/jira:status-rollup FEATURE-123 --start-date 2025-01-06 --end-date 2025-01-13`
```
## Arguments
- `issue-id` (required): The JIRA issue ID to analyze (e.g., FEATURE-123, EPIC-456, STORY-789, CNTRLPLANE-1234)
- `--start-date` (optional): Start date in YYYY-MM-DD format. Defaults to issue creation date if not provided
- `--end-date` (optional): End date in YYYY-MM-DD format. Defaults to today if not provided

197
commands/validate-blockers.md Normal file
View File

@@ -0,0 +1,197 @@
---
description: Validate proposed release blockers using Red Hat OpenShift release blocker criteria
argument-hint: [target-version] [component-filter] [--bug issue-key]
---
## Name
jira:validate-blockers
## Synopsis
```
/jira:validate-blockers [target-version] [component-filter] [--bug issue-key]
```
**Note**: `target-version` is required unless `--bug` is provided.
## Description
The `jira:validate-blockers` command helps release managers make data-driven decisions on proposed release blockers. It analyzes bugs with "Release Blocker = Proposed" status using Red Hat OpenShift release blocker criteria and provides clear APPROVE/REJECT/DISCUSS recommendations with detailed justification.
This command is essential for:
- Validating proposed release blockers
- Making blocker approval/rejection decisions
- Understanding why a bug should or shouldn't block a release
- Reviewing blocker criteria compliance
## Key Features
- **Proposed Blocker Focus** – Automatically filters for bugs with Release Blocker = Proposed
- **Red Hat OpenShift Release Blocker Criteria** – Analyzes against documented blocker criteria
- **Clear Recommendations** – Provides APPROVE, REJECT, or DISCUSS recommendations
- **Detailed Justification** – Shows which criteria matched and analysis rationale
- **Component Filtering** – Scope validation to specific components
## Implementation
For detailed implementation guidance including JQL queries, scoring algorithms, and decision logic, see the [jira-validate-blockers skill](../skills/jira-validate-blockers/SKILL.md).
### High-Level Workflow
1. **Parse Arguments and Build Filters** – Extract arguments (target version, component filter, bug ID). Build JQL query for:
- **Single bug mode** (if --bug provided): Query specific bug by issue key (version not required)
- **Component + version mode** (if both provided): Query proposed blockers matching target version and component, excluding already-fixed bugs (status not in Closed, Release Pending, Verified, ON_QA)
- **Version only mode** (if version provided): Query all proposed blockers for target version, excluding already-fixed bugs
- **Error**: If neither --bug nor version provided, show error message
2. **Query Proposed Blockers** – Use MCP tools to fetch bugs based on mode:
- Single bug: Fetch one specific bug with all fields
- Component + version: Fetch proposed blockers matching version and component filter, excluding already-fixed statuses
- Version only: Fetch all proposed blockers for target version, excluding already-fixed statuses
3. **Analyze Each Blocker** – Apply Red Hat OpenShift release blocker criteria:
- Strong blockers: Component Readiness regression, Service Delivery blocker, data loss, install/upgrade failures, service unavailability, regressions
- Never blockers: Severity below Important, new features without regression
- Workaround assessment: Check if acceptable workaround exists (idempotent, safe at scale, timely)
4. **Generate Recommendations** – Create report with APPROVE/REJECT/DISCUSS verdicts and justifications.
### Technical Details
The skill file provides complete details on:
- JQL query construction for proposed blockers
- Blocker scoring criteria and point values
- Workaround assessment logic
- Decision thresholds
## Usage Examples
### Version-Based Validation
1. **Validate all proposed blockers for a target version**:
```
/jira:validate-blockers 4.21
```
### Component-Based Validation
2. **Validate blockers for a specific component and version**:
```
/jira:validate-blockers 4.21 "Hypershift"
```
### Single Bug Validation
3. **Validate a specific proposed blocker (version not required)**:
```
/jira:validate-blockers --bug OCPBUGS-36846
```
## Output Format
The command outputs a blocker validation report:
```markdown
# 🚫 Release Blocker Validation Report
**Components**: All | **Project**: OCPBUGS | **Proposed Blockers**: 5 | **Generated**: 2025-11-23
## Summary
- ✅ **Recommend APPROVE**: 2
- ❌ **Recommend REJECT**: 1
- ⚠️ **Needs DISCUSSION**: 2
---
## Blocker Analysis
### OCPBUGS-12345: Cluster install fails on AWS ✅ APPROVE
**Recommendation**: APPROVE - This bug meets blocker criteria
**Criteria Matched**:
- ✅ Install/upgrade failure
- ✅ Affects all users
- ✅ No acceptable workaround
**Justification**:
Install failures are strong blockers. This bug prevents cluster installation on AWS, affecting all users attempting AWS deployments. No workaround exists.
**Suggested Action**: Approve as release blocker
---
### OCPBUGS-12346: UI button misaligned ❌ REJECT
**Recommendation**: REJECT - This bug does not meet blocker criteria
**Criteria Matched**:
- ❌ Cosmetic/UI-only issue (not data loss/corruption/unavailability)
- ❌ Severity: Low (must be Important or higher)
**Justification**:
Bugs with severity below Important are never blockers. This is a cosmetic issue with no functional impact.
**Suggested Action**: Reject as release blocker, triage to appropriate sprint
---
## Next Steps
1. Review APPROVE recommendations - add to blocker list
2. Review REJECT recommendations - remove blocker status
3. Discuss unclear cases in triage meeting
```
## Arguments
**IMPORTANT**: Either `target-version` OR `--bug` must be provided. If neither is provided, the command will error out.
### Core Arguments
- **$1 – target-version** *(required unless --bug is provided)*
Target release version to validate blockers for. Format: `X.Y` (e.g., `4.21`, `4.22`)
The implementation automatically:
- Expands version to search for both `X.Y` and `X.Y.0` in Target Version, Target Backport Versions, and Affected Version fields
- Excludes already-fixed bugs with status: Closed, Release Pending, Verified, ON_QA
Examples:
- `4.21` - Validates active proposed blockers for 4.21
- `4.22` - Validates active proposed blockers for 4.22
**Note**: Not required when `--bug` is provided.
- **$2 – component-filter** *(optional)*
Component name(s) to filter proposed blockers. Supports single or multiple (comma-separated) components.
Examples:
- `"Hypershift"` - Single component
- `"Hypershift,Cluster Version Operator"` - Multiple components
**Note**: Ignored if `--bug` is provided. Requires `target-version` to be specified.
Default: All components for the target version
- **--bug** *(optional)*
Validate a single specific bug by its JIRA issue key.
When provided, analyzes only this bug and ignores both target-version and component-filter.
Examples:
- `--bug OCPBUGS-36846`
**Note**: When `--bug` is provided, target-version and component-filter are ignored.
Default: Not specified
## Return Value
- **Markdown Report**: Blocker validation report with recommendations
- **Exit Code**:
- `0` - Success
- `1` - Error querying JIRA or analyzing bugs
## Prerequisites
- Jira MCP server must be configured (see [plugin README](../README.md))
- MCP tools provide read-only access to JIRA APIs
- No JIRA credentials required for read operations (public Red Hat JIRA issues)
- Access to JIRA projects (OCPBUGS)
- Permission to search and view issues in target projects

117
plugin.lock.json Normal file
View File

@@ -0,0 +1,117 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:openshift-eng/ai-helpers:plugins/jira",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "f0d9647b9a2bfada902806bc93a6ead16df44f2d",
"treeHash": "9f8869b8f996107b8bb9bf50d091f555a29385417bfe1c93b555ce73c1b48f78",
"generatedAt": "2025-11-28T10:27:27.966449Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "jira",
"description": "A plugin to automate tasks with Jira",
"version": "0.0.1"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "5beff1222698242f7b6fd8ad9cd3496bc54735af49abc6417d42eb4d06817f22"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "c8a49725be2290ea8cd9482d6883cb193a7240eedf8487d2c0d44bf226fec400"
},
{
"path": "commands/validate-blockers.md",
"sha256": "5eaaaec90d747360d251b7d78b20735091a03f29fd958746c601672e813617e5"
},
{
"path": "commands/solve.md",
"sha256": "2aa85e5cf8029980e2ac55e30aa53c95b4ebf0a0d4b59d555f24c67d159b89c2"
},
{
"path": "commands/create-release-note.md",
"sha256": "3a6563a0ab552d5844c58ad4f65bafa6cf4b89ed64f425fe5da977975f738b0c"
},
{
"path": "commands/create.md",
"sha256": "69368271325bd1709e75ace4b2a15a3107dd7ca57d8594f95e334647f106c952"
},
{
"path": "commands/backlog.md",
"sha256": "a6f26ca476ff9c5ac5fc48d5abc9ba7af9b3324635991d315abf097abe00ee62"
},
{
"path": "commands/status-rollup.md",
"sha256": "ba38d249e8d1ab2d98d072d342df88d9d37f37d9bb094dfaea292bfbc4f76a1c"
},
{
"path": "commands/generate-test-plan.md",
"sha256": "ca52082e4bcfb305647627aede0e54886242e85e3632ecfacc54a2ab6d80aef9"
},
{
"path": "commands/grooming.md",
"sha256": "1fcdc1e5e4fbd0eaf3760ebd7a721ad24a5857fbf8ecb7695b7f58a3dc8621e2"
},
{
"path": "skills/cntrlplane/SKILL.md",
"sha256": "34c0f26fa844f9be30c182d6b33d5ade619aeffd72fda1db3ff4339472892c22"
},
{
"path": "skills/create-story/SKILL.md",
"sha256": "223844b8ea29fdf3110a9806eab9509f00a0e39baa0a343b74bc9880c635a7d4"
},
{
"path": "skills/hypershift/SKILL.md",
"sha256": "137a28611e45b94c03414bb8d24a2ce260792b315c140b7a184044d4d10e3ec3"
},
{
"path": "skills/jira-validate-blockers/SKILL.md",
"sha256": "4cf3c6336bd6b48bc3c8b60e5f335a7392fc198d9bc630913882a6be7ed308e6"
},
{
"path": "skills/create-bug/SKILL.md",
"sha256": "db015ae4093d27e53da377a24164c6cfa9e454d16dab508350f1a07935f8d4fd"
},
{
"path": "skills/ocpbugs/SKILL.md",
"sha256": "837aee8b1c6fed42b5cfe72c97c4f08b0a969419150b349b3df21f5f60760f15"
},
{
"path": "skills/create-task/SKILL.md",
"sha256": "be6f4dbf25fe83617cb5bfd969a11bbe74659765ad736709e3853c8e258262f6"
},
{
"path": "skills/create-epic/SKILL.md",
"sha256": "f2e096d6463dfb762ee0b5fa6a4bb117fa8d68a52fd678c3174bbf8411e0af9b"
},
{
"path": "skills/create-feature/SKILL.md",
"sha256": "ebc0adcffc9d3c854403ff275d1cae9a9e1952df0552e745c4416e47dfa9b1ba"
},
{
"path": "skills/create-release-note/SKILL.md",
"sha256": "8926638415e3c00535019c4e7c11f5e22d8514aa81ee0281864ef47603429906"
},
{
"path": "skills/create-feature-request/SKILL.md",
"sha256": "b0617bb782c0a3d413da73eb99b1f936e9330e719d5838f0dbcc810ba16cb556"
}
],
"dirSha256": "9f8869b8f996107b8bb9bf50d091f555a29385417bfe1c93b555ce73c1b48f78"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

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