A plugin to automate tasks with Jira
- version
- 0.9.8
- GitHub stars
- 123
Install
/plugin install jira@ai-helpersRun it inside Claude Code after adding the marketplace with /plugin marketplace add openshift-eng/ai-helpers.
Contents
Discovered from sourceSkills 13
Catch Me Up
Gathers recent Jira activity (changelogs and comments) for issues where the user is assignee or watcher, then classifies events into three tiers: needs attention, unsure, or noise.
Scripts
scripts/gather.py— Fetches events from Jira REST API. Requiresaiohttp. Outputs JSON to.work/catch-me-up/runs/{date}-{days}d/events.json. Caches by date and lookback window.scripts/split_batches.py— Splits gathered events into batch files for parallel classification.
Usage
Invoked by the /jira:catch-me-up command. Not intended for standalone use.
Activity Type Classification
Categorize Jira issues into Red Hat's Sankey capacity allocation categories and update them via MCP Jira tools. This skill supports two modes of operation:
- Single-issue mode: Categorize one issue by key (invoked by
/jira:categorize-activity-type) - Batch mode: Categorize all unclassified issues in a project (invoked by
/jira:batch-categorize-activity-types)
Both modes use identical classification logic, validation, and reporting.
Valid Activity Types
These are the only valid values. Use the exact strings:
| Activity Type | Short Description |
|---|---|
| Associate Wellness & Development | Onboarding, training, AI learning, conferences, team health |
| Incidents & Support | Production incidents, customer escalations, on-call |
| Security & Compliance | CVEs, weaknesses, FedRAMP, compliance, security tooling |
| Quality / Stability / Reliability | Bugs, SLOs, chores, tech debt, toil reduction, PMR actions |
| Future Sustainability | Proactive architecture, productivity improvements, upstream, enablement |
| Product / Portfolio Work | New features, enhancements, strategic product/portfolio work |
For detailed definitions, subcategories, and edge cases, see resources/activity-type-guidance.md.
Activity Type Field
The Activity Type custom field ID is customfield_10464. This is the same across all projects on redhat.atlassian.net.
Prerequisites Check
Before starting any work, verify MCP Jira tools are available:
- Attempt to call
searchJiraIssuesUsingJqlwith a simple query (e.g.,jql: "project = OCM",maxResults: 1) - If the tool is not found or returns an MCP connection error, stop immediately and tell the user:
- "The MCP Jira tools are not available. This workflow requires the Atlassian Rovo MCP server to be configured with access to redhat.atlassian.net."
- Do NOT proceed to any phase if this check fails
Working Directory
Both modes write artifacts to .work/activity-type-classifier/. Create this directory before starting:
mkdir -p .work/activity-type-classifier
Workflow
Copy this checklist and track progress:
Classification Progress:
- [ ] Prerequisites: MCP Jira tools available
- [ ] Phase 1: Gather issues
- [ ] Phase 2: Categorize each issue
- [ ] Phase 3: Validate & generate report
- [ ] Phase 4: Apply updates (with approval)
- [ ] Phase 5: Iterate (batch mode only)
Phase 1: Gather Issues
Single-Issue Mode
Fetch the issue by key using getJiraIssue:
- Fields:
summary,description,issuetype,labels,parent,components,priority,customfield_10464 - If the issue already has an Activity Type set (
customfield_10464is not null), inform the user and stop
Batch Mode
Parse user input for:
- Project key (required) — e.g., OCM, ARO
- Issue type (optional, default: Epic)
- Extra JQL filters (optional) — e.g.,
AND resolved >= "2025-01-01"
Always filter for issues without an Activity Type set. The "Activity Type" is EMPTY condition is mandatory in every query — do not ask the user whether to include it.
Construct the JQL query using this template:
project = {PROJECT} AND issuetype = {TYPE} AND "Activity Type" is EMPTY
Common additions:
- Date filter:
AND resolved >= "2025-01-01" - Open issues only:
AND status != Closed
Execute searchJiraIssuesUsingJql with maxResults: 50. If more results exist, make a second call with nextPageToken to get up to 100 total. Combine both result sets.
From each issue, extract: key, summary, description (truncate to 2000 chars), labels, issuetype, status, priority, comment, and parent. Save all extracted data to .work/activity-type-classifier/issues.json.
Report the count of issues found to the user before proceeding.
Phase 2: Categorize Issues
Pre-check — Parent inheritance: Before classifying each issue, check if it has a parent issue. If the parent has an Activity Type set (customfield_10464), inherit it directly — no further classification needed. Set confidence to "High" and reasoning to "Inherited from {PARENT_KEY}". To look up a parent's Activity Type, call getJiraIssue with the parent's key and check customfield_10464. Cache parent lookups to reduce API calls — multiple children may share the same parent.
For remaining issues (no parent or parent has no Activity Type), read summary, description, labels, comments, and status. Apply the classification rules below and the detailed guidance in resources/activity-type-guidance.md.
Save classifications to .work/activity-type-classifier/classifications.json as a JSON array:
[
{
"key": "OCM-12345",
"summary": "Issue title",
"activityType": "Product / Portfolio Work",
"confidence": "High",
"reasoning": "New customer-facing feature for cluster provisioning"
}
]
In single-issue mode, this array contains exactly one entry. In batch mode, it contains all classified issues.
If total issues exceed 50 (batch mode), process in sub-batches of 20 to manage context.
Phase 3: Validate and Report
Run the validation and report generation scripts. These are located in scripts/ relative to this skill's directory.
- Run the validation script:
bash plugins/jira/skills/categorize-activity-types/scripts/validate-classifications.sh .work/activity-type-classifier/classifications.json - Fix any validation errors before proceeding
- Generate the report:
python3 plugins/jira/skills/categorize-activity-types/scripts/generate-report.py .work/activity-type-classifier/classifications.json .work/activity-type-classifier/report.md - Display the report summary to the user
Phase 4: Apply Updates
Single-Issue Mode with --auto-apply
- If
--auto-applyflag is present AND confidence is High: automatically update the Activity Type field without prompting - Otherwise: present the classification and ask for confirmation before applying
Batch Mode
- Ask the user for explicit approval before modifying any Jira issues
- If
--dry-runflag is present, skip this phase entirely - Max 2 concurrent MCP update calls to avoid rate limiting
- Report progress every 10 issues
- On error: log the failure, continue with remaining issues
- After completion, summarize successes and failures
Update Format
Use editJiraIssue to set customfield_10464 (Activity Type) to the classified value, e.g. {"value": "Product / Portfolio Work"}.
Success Confirmation
Updated OCM-12345: Activity Type set to "Product / Portfolio Work"
View at: https://redhat.atlassian.net/browse/OCM-12345
Phase 5: Iterate (Batch Mode Only)
After applying updates, offer to re-run the workflow:
- Classified issues will no longer match the JQL query (Activity Type is no longer empty)
- A new batch of unclassified issues can be gathered and processed
- Track cumulative stats across iterations
Classification Rules
When classifying an issue:
- Read carefully — consider summary, description, labels, comments, and linked issues
- Business intent over technical details — a Kubernetes refactoring driven by product requirements is "Product / Portfolio Work", not "Future Sustainability"
- Security always wins — if an issue involves CVEs, vulnerabilities, compliance, or security tooling, classify as "Security & Compliance" regardless of other aspects
- Primary purpose — when an issue spans multiple categories, choose the one that best matches the primary motivation
- Confidence levels:
- High — clear match, unambiguous indicators
- Medium — reasonable match but some ambiguity
- Low — uncertain, multiple categories could apply
- Truncate descriptions — use the first 2000 characters of the description for classification
For the complete category definitions with subcategories and examples, see resources/activity-type-guidance.md.
Error Handling
- Issue not found: Display error and suggest verifying issue key
- Permission denied: Inform user they lack update permissions
- Invalid field value: Verify Activity Type value matches allowed options
- MCP connection error: Suggest checking MCP server configuration
- Parent fetch failure: Continue without parent context, note in reasoning
Reference Files
| File | Purpose | When to Read |
|---|---|---|
| resources/activity-type-guidance.md | Full Sankey category definitions and subcategories | Phase 2 (classifying) |
| resources/report-template.md | Report format reference | Phase 3 (report generation) |
| scripts/validate-classifications.sh | Validate classifications JSON | Phase 3 (validation) |
| scripts/generate-report.py | Generate markdown report from JSON | Phase 3 (report generation) |
| scripts/cleanup.sh | Remove data artifacts, preserve reports | Post-workflow cleanup |
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:
-
Fetch the bug via
getJiraIssuewith the issue key andresponseContentFormat: "markdown". -
Parse the response:
- Extract
issuetype.name- verify it's "Bug" - Extract
description- full bug description text - Extract
issuelinks- array of linked issues - Extract
customfield_10785- current Release Note Type (if already set) - Extract
customfield_10783- current Release Note Text (if already set) - Extract
comment.comments- array of comment objects
- Extract
-
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 without making changes
- If
-
Check if release note already exists:
- If
customfield_10783is 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 without making changes
- If
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:
-
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
-
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
-
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
-
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
- If Cause is missing:
-
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):
-
Remote Links (Primary source - web links in Jira):
- Check the Jira issue response for web links
- Field name varies:
remotelinks, orissuelinkswith 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
-
Bug Description:
- Scan the
descriptionfield 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
- Scan the
-
Bug Comments:
- Iterate through
comment.commentsarray - For each comment, scan
bodyfield for GitHub PR URLs - Use same regex pattern
- Extract all matches
- Iterate through
-
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:
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:
Exit without updating the ticket.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
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:
gh pr view {number} --json body,title,commits,url,state --repo {repo}
Error handling:
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):
{
"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 descriptioncommits: Array of commit objects with messagesstate: PR state (MERGED, OPEN, CLOSED)
4.2: Fetch PR Diff
Command:
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
- New error handling (
- Don't include the entire diff in the release note
- Summarize the nature of changes
Example diff analysis:
+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:
gh pr view {number} --json comments --repo {repo}
Expected output (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:
-
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}
- Pattern:
-
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/+=]+
- Pattern:
-
Passwords in URLs:
- Pattern:
https?://[^:]+:[^@]+@ - Example:
https://user:password@example.com
- Pattern:
-
JWT Tokens:
- Pattern:
eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+
- Pattern:
-
SSH Private Keys:
- Pattern:
-----BEGIN (RSA|OPENSSH|DSA|EC|PGP) PRIVATE KEY-----
- Pattern:
-
Kubernetes Secrets:
- Pattern:
[a-zA-Z0-9+/]{40,}==?(base64 encoded secrets) - Context: If appears after "token:", "secret:", "password:"
- Pattern:
Validation logic:
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):
- Bug Fix
- Release Note Not Required
- Known Issue
- Enhancement
- Rebase
- Technology Preview
- Deprecated Functionality
- CVE
Auto-detection strategy:
-
For OCPBUGS: Default suggestion is "Bug Fix" (most common)
-
Check for CVE references:
- If bug description or PRs mention "CVE-" → Suggest "CVE"
-
Check for deprecation:
- If PRs mention "deprecated", "deprecating", "removing" → Suggest "Deprecated Functionality"
-
Check for new features:
- If PRs add significant new functionality → Suggest "Enhancement"
- Though typically bugs should be "Bug Fix"
-
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.
Use editJiraIssue with the issue key, contentFormat: "markdown", and set the following fields:
customfield_10785(Release Note Type):{"value": "<selected_type>"}customfield_10783(Release Note Text): the formatted release note text
Field details:
customfield_10785: Release Note Type (must be exact match from dropdown)customfield_10783: Release Note Text (plain text)
Error handling:
-
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} --- -
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. -
Field not found:
Failed to update {issue-key}. Error: Field customfield_10785 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_10785": {"value": "Bug Fix"},
"customfield_10783": "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://redhat.atlassian.net/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://redhat.atlassian.net/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:
- Log warning for each failed PR
- Continue with successfully analyzed PRs
- If all PRs fail, treat as "No PRs linked" error
- 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:
- Offer interactive input option
- Provide template for user
- Allow user to update bug and retry
- Don't proceed without both fields
Ambiguous PR Content
Problem: PRs don't clearly explain the fix
Recovery:
- Use PR title as fallback
- Analyze code diff more carefully
- 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:
- Present both descriptions to user
- Ask which is correct or how to combine
- Use AI to attempt intelligent synthesis
- If synthesis fails, escalate to user
Best Practices for Implementation
- Always validate inputs: Check that issue exists, PRs are accessible, fields are present
- On failure, provide helpful error messages with recovery instructions
- Be defensive: Handle missing data, API errors, permission issues
- Log progress: Show user what's happening at each step
- Preserve data: If update fails, show generated content so it's not lost
- Security first: Always validate before updating Jira
- 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)
Create Jira Issue
/jira:create <type> [project-key] <summary> [--component <name>] [--version <version>] [--parent <key>]
Creates Jira issues following best practices and team-specific conventions. Supports stories, epics, features, initiatives, tasks, bugs, risks, spikes, and feature requests with intelligent defaults, interactive prompts, and validation.
Type-Specific Guidance
Load the reference file matching the issue type for templates, interactive workflows, and best practices:
| Type | Reference | Key Content |
|---|---|---|
| story | Story guide | User story format, acceptance criteria, summary vs description |
| bug | Bug guide | Bug template, steps to reproduce, reproducibility |
| epic | Epic guide | Epic Name field, scope/timeline, parent Feature linking |
| feature | Feature guide | Market problem, strategic value, success criteria |
| initiative | Initiative guide | Internal capability, problem statement, internal impact |
| risk | Risk guide | Qualifying criteria, probability/impact assessment, auto-calculated fields |
| spike | Spike guide | Research question, time box, investigation approach |
| task | Task guide | Task vs story distinction, action-verb summaries |
| feature-request | Feature Request guide | RFE project, 4-question workflow, business requirements |
Also load Markdown for Jira for description formatting.
Arguments
- type (required) —
story|epic|feature|initiative|task|bug|risk|spike|feature-request - project-key (optional for bugs and feature-requests) — e.g.,
CNTRLPLANE,OCPBUGS,RFE. Default for bugs:OCPBUGS. Default for feature-requests:RFE. - summary (required) — Issue title. Use quotes for multi-word:
"Enable automatic scaling" - --component (optional) — Component name. Auto-detected from summary for known projects.
- --version (optional) — Target version. Normalized to
openshift-X.Yper project conventions. - --parent (optional) — Parent issue key for linking (e.g.,
CNTRLPLANE-123).
Implementation Phases
Phase 1: Load Guidance
- Load the type-specific reference file from the table above
- Invoke the
jira:jira-conventionsskill when the project key, component, or summary keywords match a known project or team
Phase 2: Parse Arguments & Detect Context
Parse required and optional arguments. Analyze summary text for context clues (team, component, platform keywords).
Phase 3: Apply Smart Defaults
Universal requirements (ALL tickets):
"labels": ["ai-generated-jira"]
"security": {"name": "Red Hat Employee"}
contentFormat: "markdown"
Project and team defaults (version, component, labels) come from the jira-conventions skill.
Phase 4: Interactive Prompts
Follow the type-specific reference file's interactive workflow to collect missing information (story format, bug template sections, epic scope, etc.).
Phase 5: Summary Validation
Check for anti-patterns before creation:
- Summary starts with "As a" or contains "I want" / "so that" → belongs in description
- Summary exceeds 100 characters → likely too long
If detected:
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)
Phase 6: Security Validation
Scan all content (summary, description) for sensitive data:
- Credentials, API tokens, cloud keys (AWS, GCP, Azure)
- Kubeconfigs, SSH keys, certificates, PEM files
- URLs with embedded credentials
If detected: STOP creation, inform user of the type found (without echoing it), suggest placeholder values.
Phase 7: Create Issue via MCP
Use createJiraIssue with collected parameters. Include universal fields and any project/team-specific fields.
Phase 8: Return Result
Created: PROJECT-1234
Title: <issue summary>
URL: <issue URL>
Applied defaults:
- <Field>: <Value>
Custom Fields (redhat.atlassian.net)
| Field | ID | Type | Usage |
|---|---|---|---|
| Epic Name | customfield_10011 | String | Required for Epics; must match summary |
| Target Version | customfield_10855 | Array | Format: [{"id": "VERSION_ID"}] — fetch via getJiraIssueTypeMetaWithFields. Some projects use string format; project conventions take precedence |
Issue Hierarchy and Parent Linking
Jira issue types have a hierarchyLevel that determines valid parent-child relationships. The parent field only accepts an issue whose hierarchyLevel is exactly one level above the child. Not all projects have all levels — use getJiraProjectIssueTypesMetadata to discover available types and their levels for a given project.
Level 3: Outcome
Level 2: Feature / Initiative
Level 1: Epic
Level 0: Story / Task / Bug / Spike
Level -1: Sub-task
Parent Field
Use {"parent": {"key": "PARENT-KEY"}} in additional_fields for all parent-child relationships (Story→Epic, Task→Epic, Bug→Epic, Spike→Epic, Epic→Feature, Epic→Initiative, Feature→Outcome, Initiative→Outcome).
Pre-Validation (when --parent is provided)
Fetch the parent via getJiraIssue to verify it exists and its type matches the hierarchy:
| Creating | Parent Should Be | If Wrong Type |
|---|---|---|
| Story | Epic | Warn user, ask to confirm or correct |
| Task | Epic | Warn user, ask to confirm or correct |
| Bug | Epic | Warn user, ask to confirm or correct |
| Spike | Epic | Warn user, ask to confirm or correct |
| Epic | Feature or Initiative | Warn user, ask to confirm or correct |
| Feature | Outcome | Warn user, ask to confirm or correct |
| Initiative | Outcome | Warn user, ask to confirm or correct |
If parent not found, offer options: proceed without parent, specify different parent, or cancel.
Parent Linking Fallback
If creation fails with a parent-related error, create without the parent and link via editJiraIssue with {"parent": {"key": "PARENT-KEY"}}.
Changing Issue Type Across Hierarchy Levels
When changing an existing issue's type to a different hierarchy level, the current parent may become invalid. Jira validates the one-level-higher constraint on every edit, so you must change the parent and type in separate steps:
- Unset the parent:
editJiraIssuewith{"parent": null} - Change the issue type:
editJiraIssuewith{"issuetype": {"name": "NewType"}} - Set the new parent if needed:
editJiraIssuewith{"parent": {"key": "NEW-PARENT"}}
Error Handling
Invalid Issue Type
Invalid issue type "stroy". Valid types: story, epic, feature, initiative, task, bug, risk, spike, feature-request
Did you mean "story"?
Missing Project Key
Project key is required for stories/tasks/epics/features/initiatives/risks/spikes.
Usage: /jira:create story PROJECT-KEY "summary"
Field Format Errors
| Field | Wrong | Correct |
|---|---|---|
| Target Version | "customfield_10855": "openshift-4.21" | "customfield_10855": [{"id": "12448830"}] |
| Component | "components": "Name" | "components": [{"name": "Name"}] |
MCP Tool Errors
- "Field 'component' is required" → Prompt for component
- "Version not found" → Fetch available versions, suggest closest match
- "Permission denied" → User may lack permissions
- "Issue type not available" → Project may not support this type
Usage Examples
/jira:create story CNTRLPLANE "Add user dashboard"
/jira:create story CNTRLPLANE "Add search" --component "Frontend" --version "4.22"
/jira:create epic CNTRLPLANE "Mobile redesign" --parent CNTRLPLANE-100
/jira:create bug "API returns 500 error" --component "Backend"
/jira:create task CNTRLPLANE "Update API docs" --parent CNTRLPLANE-456
/jira:create feature CNTRLPLANE "Advanced search capabilities"
/jira:create initiative GCP "Establish performance testing infrastructure"
/jira:create risk GCP "Cincinnati API outage could block new cluster creation due to version resolution dependency"
/jira:create spike GCP "Evaluate Workload Identity Federation vs service account key rotation for HCP node auth"
/jira:create feature-request RFE "Support custom SSL certificates for ROSA HCP"
Configuration
Project and Team Conventions
The jira-conventions skill automatically detects and applies conventions:
- CNTRLPLANE: version normalization, parent linking fields
- OCPBUGS: bug-specific version fields
- GCP: team templates, sizing guide, priority scheme
- HyperShift: component selection (ARO/ROSA/HyperShift)
To add conventions for your project, create a reference file at plugins/jira/reference/your-project.md and add a routing entry to plugins/jira/skills/jira-conventions/SKILL.md.
Best Practices
- Use descriptive summaries with relevant keywords for auto-detection
- Provide
--componentand--versionflags when known to skip prompts - Use
--parentto maintain issue hierarchy - Sanitize content — remove credentials before including logs
Anti-Patterns
- Wrong type:
/jira:create story "Refactor database"→ technical work, usetask - Vague summary:
/jira:create bug "Something is broken"→ be specific - Credentials in content: Use placeholders like
YOUR_API_KEY
Jira Pull Request Extractor
This skill recursively discovers Jira issues and extracts all associated GitHub Pull Request links.
IMPORTANT FOR AI: This is a procedural skill - when invoked, you should directly execute the implementation steps defined in this document. Do NOT look for or execute external scripts (like extract_prs.py). Follow the step-by-step instructions in the "Implementation" section below.
When to Use This Skill
Use this skill when you need to:
- Discover all GitHub PRs associated with a Jira feature and its subtasks
- Extract PR metadata without analyzing PR content
- Build a complete map of PRs for documentation or release notes
Key characteristics:
- ✅ Always recursive: Automatically discovers all descendant issues via
parent = KEYBFS - ✅ PR-only: Extracts only Pull Request URLs (ignores Issue and Commit URLs)
- ✅ Dual-source: Extracts from both changelog remote links and text content (description/comments)
- ✅ Structured output: Returns JSON with PR metadata and deduplication across sources
Prerequisites
- MCP Jira server configured and running (required - see
plugins/jira/README.mdfor setup) jqinstalled for JSON parsing- GitHub CLI (
gh) installed and authenticated for fetching PR metadata - User has read permissions for target Jira issues (including private issues via MCP authentication)
- User has read access to linked GitHub repositories
Output Format
Purpose: This skill returns structured JSON that serves as an interface contract for consuming skills and commands.
Delivery Method:
- Primary: Output JSON directly to the response (no file writes, no user prompts)
- Secondary: Only save to
.work/extract-prs/{issue-key}/output.jsonif user explicitly requests to save results
Schema Version: 1.0
Structure
{
"schema_version": "1.0",
"metadata": {
"generated_at": "2025-11-24T10:30:00Z",
"command": "extract_prs",
"input_issue": "OCPSTRAT-1612"
},
"pull_requests": [
{
"url": "https://github.com/openshift/hypershift/pull/6444",
"state": "MERGED",
"title": "Add support for custom OVN subnets",
"isDraft": false,
"sources": ["comment", "description", "remote_link"],
"found_in_issues": ["CNTRLPLANE-1201", "OCPSTRAT-1612"]
}
]
}
Fields:
schema_version: Format version ("1.0")metadata: Generation timestamp, command name, and input issuepull_requests: Array of PR objects withurl,state,title,isDraft,sources, andfound_in_issues
Implementation
The skill operates in three main phases:
Phase 1: Descendant Issue Discovery
Discovers all descendant issues using parent = KEY JQL with BFS recursion.
Implementation:
-
Fetch issue metadata via
getJiraIssuewith the issue key, requesting fieldssummary,description,issuetype,status,comment, andexpand: "changelog".- Extract
fields.description-- for text-based PR URL extraction - Extract
fields.comment.comments-- for PR URLs mentioned in comments - Extract
changelog.histories-- for remote link PR URLs fromRemoteIssueLinkfield changes
- Extract
-
Search for descendant issues using BFS via
searchJiraIssuesUsingJqlwithjql: "parent = <issue-key>",fields: ["key"], andmaxResults: 100. Recursively searchparent = <child-key>for each result until no more children. Only fetch thekeyfield here -- full data (including changelog) is fetched per-issue in Phase 2. -
Fetch full data for each issue (including root + all descendants) via
getJiraIssuewith fieldssummary,description,issuetype,status,comment, andexpand: "changelog". This fetches description, comments, and changelog (which includes remote links). Excludes issue links (relates to,blocks, etc.) -- only parent-child relationships.
🔗 Phase 2: GitHub PR Extraction
Extracts PR URLs from two sources:
Source 1: Jira Remote Links via Changelog (primary)
- Extract remote links from issue changelog (using MCP with authenticated access):
- Fetch the issue via
getJiraIssuewithissueIdOrKeyandexpand: "changelog" - From the response, extract
changelog.histories[].items[]entries wherefield == "RemoteIssueLink" - Parse the
toString(orto_string) value of each entry for GitHub PR URLs matchinghttps://github.com/{owner}/{repo}/pull/{number} - Deduplicate the extracted URLs
- Fetch the issue via
- Important:
- Remote links appear in changelog as
RemoteIssueLinkfield changes - Changelog contains link creation events with GitHub PR URLs in
toStringorto_stringfield - Store results in variables, not temporary files
- Uses MCP authentication (no separate curl needed)
- Remote links appear in changelog as
- Filters for GitHub PR URLs matching
/pull/or/pulls/pattern
Source 2: Text Content (backup)
- Searches both
fields.descriptionandfields.comment.comments[](already fetched in Phase 1) - Description: Extract from
fields.description(plain text or Jira wiki format) - Comments: Iterate through
fields.comment.comments[]array and search eachcomment.body - Uses regex:
https?://github\.com/([\w-]+)/([\w-]+)/pulls?/(\d+) - Example extraction (using variables):
# From description (stored in variable from MCP response) description_prs=$(echo "$description" | \ grep -oE 'https?://github\.com/[^/]+/[^/]+/pulls?/[0-9]+') # From comments (parse JSON in memory) comment_prs=$(echo "$issue_json" | \ jq -r '.fields.comment.comments[]?.body // empty' | \ grep -oE 'https?://github\.com/[^/]+/[^/]+/pulls?/[0-9]+') # Combine all PRs all_prs=$(echo -e "${description_prs}\n${comment_prs}" | sort -u)
Deduplication:
- Merges URLs found in multiple sources/issues
- Tracks
sourcesarray:["comment", "description", "remote_link"](alphabetically sorted)"comment": Found in issue comments"description": Found in issue description"remote_link": Found via Jira Remote Links API
- Tracks
found_in_issuesarray:["OCPSTRAT-1612", "CNTRLPLANE-1201"](alphabetically sorted) - Important: If same PR URL found in multiple sources or issues, merge into single entry with combined arrays
📊 Phase 3: Data Structuring and Output
PR Metadata: Fetch via gh pr view {url} --json state,title,isDraft. CRITICAL: When building the output JSON, you MUST use the exact values returned by gh pr view - do NOT manually type or guess PR states/titles.
Output: Build JSON in memory using jq -n, output to console. Only save to .work/extract-prs/{issue-key}/output.json if user explicitly requests.
Important: Use bash variables for all data - no temporary files to avoid user confirmation prompts.
Error Handling
- MCP server not available: Display error message directing user to configure MCP server (see Prerequisites)
- Issue not found: Log warning and continue with remaining issues
- Permission denied:
- If MCP returns 403 for private issues, verify JIRA_API_TOKEN and JIRA_USERNAME are set and match a valid Jira account
- MCP authentication handles all Jira access (including changelog and remote links)
- Changelog expansion fails: If
expand="changelog"returns error, continue with text-based extraction only (graceful degradation) - No PRs found: Return empty
pull_requestsarray (valid result) - Too many descendants: If hierarchy has >100 issues, increase
maxResultsparameter insearchJiraIssuesUsingJql - GitHub rate limit: If
gh pr viewfails due to rate limiting, display error with reset time - PR metadata fetch fails: If
gh pr viewreturns error (PR deleted/private), exclude that PR from output
Performance Considerations
API calls: BFS searchJiraIssuesUsingJql calls + N getJiraIssue (with changelog) + M gh pr view
- Example: 11 issues = BFS discovery calls + 11 MCP detail calls + M PR fetches
- Changelog expansion includes remote links (no extra calls needed)
- Can parallelize: issue fetching and PR metadata fetching
File I/O: Save PR metadata to .work/extract-prs/{issue-key}/pr-*-metadata.json, build final JSON by reading files
Generate Enhancement from Jira Epic or Feature
This skill provides implementation guidance for generating OpenShift enhancement proposal markdown files based on Jira epic or feature issues.
When to Use This Skill
This skill is automatically invoked by the /jira:generate-enhancement command to guide the enhancement generation process from Jira epics or features.
Prerequisites
- MCP Jira server configured and accessible (or direct API access)
- User has permissions to view the target epic or feature
- Epic or Feature issue exists and has substantive content
- Understanding of OpenShift enhancement process
Reference Documentation:
What is an OpenShift Enhancement?
An OpenShift enhancement proposal is:
- A design document that describes significant changes to OpenShift
- A communication tool for building consensus among stakeholders
- An architectural record for future reference
- A mandatory process for all enhancements (starting with release 4.3)
Enhancement Template Structure
The enhancement proposal uses YAML frontmatter metadata and structured markdown sections:
---
title: neat-enhancement-idea
authors:
- "@github-username"
reviewers:
- "@reviewer1"
- "@reviewer2"
approvers:
- "@approver"
api-approvers:
- None # Or "@api-approver" if API changes
creation-date: yyyy-mm-dd
last-updated: yyyy-mm-dd
status: provisional
tracking-link:
- https://issues.redhat.com/browse/FEATURE-123
---
# Enhancement Title
## Summary
## Motivation
### User Stories
### Goals
### Non-Goals
## Proposal
### Workflow Description
### API Extensions
### Topology Considerations
#### Hypershift / Hosted Control Planes
#### Standalone Clusters
#### Single-node Deployments or MicroShift
#### OpenShift Kubernetes Engine
### Implementation Details/Notes/Constraints
### Risks and Mitigations
### Drawbacks
## Alternatives (Not Implemented)
## Open Questions [optional]
## Test Plan
## Graduation Criteria
### Dev Preview -> Tech Preview
### Tech Preview -> GA
### Removing a deprecated feature
## Upgrade / Downgrade Strategy
## Version Skew Strategy
## Operational Aspects of API Extensions
## Support Procedures
## Infrastructure Needed [optional]
Workflow: Generate Enhancement from Epic or Feature
Step 1: Fetch Epic or Feature from Jira
Use direct API calls or MCP tools to retrieve the issue:
# Direct API (used in OCPSTRAT-1596 example)
curl -u "$USERNAME:$API_TOKEN" \
"https://redhat.atlassian.net/rest/api/3/issue/<ISSUE-KEY>"
Extract key information:
- Summary (becomes enhancement title)
- Description (contains problem statement, goals, acceptance criteria)
- Components (determines topology considerations)
- Target version (informs graduation criteria)
- Child issues (epics, stories, tasks - become implementation details)
- Creation date (metadata)
- Issue type (Epic or Feature)
Validation checks:
- ✅ Issue type is "Epic" or "Feature"
- ✅ Issue has description content
- ✅ Issue summary is meaningful
- ⚠️ Warn if missing: detailed description, acceptance criteria, child issues
Step 2: Parse Epic or Feature Description
For Features created via /jira:create feature:
Features follow this structure:
<Brief overview>
h2. Market Problem
<Problem description>
h2. Proposed Solution
<Solution description>
h2. Strategic Value
h3. Customer Value
* <benefits>
h3. Business Impact
* <impacts>
h2. Success Criteria
h3. Adoption
* <metrics>
h2. Scope
h3. Epics (Planned)
* Epic 1: <name>
* Epic 2: <name>
h3. Out of Scope
* <items>
h2. Timeline
* Target: <release>
* Milestones: <dates>
Parse sections into variables:
overview- First paragraphmarket_problem- Content under "Market Problem"solution- Content under "Proposed Solution"customer_value- Items under "Customer Value"success_criteria- All success criteria sectionsepics_planned- Epic listout_of_scope- Out of scope itemstimeline- Timeline information
For Epics:
Epics typically have simpler structure (as seen in HIVE-2589, OCPSTRAT-1596):
<Epic summary>
h3. Feature Overview (aka. Goal Summary)
<Brief description>
h3. Goals (aka. expected user outcomes)
<What should be achieved>
h3. Requirements (aka. Acceptance Criteria)
<What must be delivered>
[Deployment considerations table]
h3. Questions to Answer (Optional)
<Open questions>
h3. Background
<Context and motivation>
h3. Documentation Considerations
<Docs needed>
h3. Interoperability Considerations
<Integration points>
Parse epic sections into variables:
overview- Feature Overview / Goal Summarygoals- Goals sectionacceptance_criteria- Requirements / Acceptance Criteriadeployment_considerations- Table of deployment scenariosbackground- Background section (use as motivation)questions- Open questionsdocs_considerations- Documentation needsinterop_considerations- Interoperability needs
For both types, also fetch child issues:
# Get child stories/tasks/epics
curl -u "$USERNAME:$API_TOKEN" \
"https://redhat.atlassian.net/rest/api/3/search" \
--data-urlencode "jql=parent = <ISSUE-KEY>"
Step 3: Generate Enhancement Metadata
---
title: <generated-from-summary>
authors:
- "@<jira-reporter-github-username>" # Prompt if unknown
reviewers:
- TBD # Prompt for reviewers
approvers:
- TBD # Prompt for approver (typically team lead)
api-approvers:
- None # Or prompt if API changes detected
creation-date: <feature-creation-date>
last-updated: <current-date>
status: provisional
tracking-link:
- <jira-feature-url>
see-also:
- # Related enhancements (optional)
replaces:
- # If replacing existing enhancement (optional)
superseded-by:
- # Leave empty
---
Title generation:
- Convert summary to lowercase
- Replace spaces with hyphens
- Remove special characters
- Example: "Advanced HCP Observability" → "advanced-hcp-observability"
Detect API changes:
- Search description for: "API", "CRD", "Custom Resource", "field", "endpoint"
- If detected, prompt: "This feature mentions API changes. Who should review API changes?"
Step 4: Map Content to Enhancement Sections
Summary
Use the feature overview (first paragraph) as the enhancement summary.
Example:
## Summary
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.
Motivation
Map from the Market Problem section:
## Motivation
<Content from "Market Problem" section>
This addresses the critical need for <summarize problem impact>.
User Stories
Two approaches:
Approach 1: Extract from feature if present Some features include user stories in the description.
Approach 2: Generate from customer value Convert customer value bullet points into user story format:
### User Stories
#### Story 1: Fleet-wide Visibility
As a platform administrator managing 50+ ROSA HCP clusters, I want to view
aggregated health metrics across all clusters in a single dashboard, so that
I can quickly identify issues without navigating between separate UIs.
#### Story 2: Faster Incident Response
As an SRE, I want to receive alerts based on cross-cluster conditions, so that
I can detect and respond to incidents 80% faster than with per-cluster monitoring.
Prompt if needed:
The feature doesn't include explicit user stories. I can:
1. Generate user stories from the customer value section
2. Prompt you to provide user stories
Which would you prefer?
Goals
Map from Strategic Value and Proposed Solution:
### Goals
* Deliver centralized metrics aggregation across all customer clusters
* Provide unified dashboards for cluster health, performance, and capacity
* Enable fleet-wide alerting with intelligent cross-cluster correlation
* Support compliance and audit reporting across cluster fleet
* <Additional goals from strategic value>
Non-Goals
Map from Out of Scope section:
### Non-Goals
* 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)
If not present, prompt:
What is explicitly OUT of scope for this enhancement?
This helps prevent scope creep and sets clear boundaries.
Proposal - Workflow Description
Generate from Proposed Solution:
### Workflow Description
**Platform Administrator:**
1. Accesses unified observability dashboard
2. Views aggregated metrics across all managed clusters
3. Configures fleet-wide alert rules
4. Generates compliance reports for audit purposes
**SRE:**
1. Receives cross-cluster alert notification
2. Uses dashboard to identify affected clusters
3. Drills down into specific cluster metrics
4. Takes remediation action with API/CLI
Prompt if details missing:
Please describe the typical workflow for using this feature:
- What does the user do first?
- What are the key interactions?
- What is the end result?
Proposal - API Extensions
Prompt for API changes:
Does this feature introduce or modify APIs? (yes/no)
If yes, describe:
- New CRDs or API resources
- New fields in existing resources
- API endpoints
- Validation webhooks
If no API changes:
### API Extensions
This enhancement does not introduce new API extensions.
If API changes:
### API Extensions
#### New CRD: ObservabilityConfiguration
```yaml
apiVersion: observability.openshift.io/v1alpha1
kind: ObservabilityConfiguration
metadata:
name: fleet-config
spec:
clusterSelector:
matchLabels:
fleet: production
metricsRetention: 30d
alertRules:
- name: high-cpu
expression: "avg(cpu_usage) > 80"
```
<Additional API details>
Proposal - Topology Considerations
Auto-detect from feature components and prompt:
# Detect from components
hypershift_detected = "HyperShift" in components or "ROSA" in components or "ARO" in components
standalone_detected = "Standalone" in description or not hypershift_detected
For each topology, generate section:
#### Hypershift / Hosted Control Planes
This enhancement is designed specifically for Hypershift hosted control planes
(ROSA HCP and ARO HCP). It provides fleet-level observability by aggregating
metrics from control planes running in the management cluster.
**Considerations:**
* Metrics are collected from hosted control plane namespaces
* Aggregation service runs in the management cluster
* Supports multi-tenant isolation of metrics data
Prompt if unclear:
Which OpenShift topologies does this enhancement support?
1. Hypershift / Hosted Control Planes (ROSA HCP, ARO HCP)
2. Standalone Clusters
3. Single-node Deployments or MicroShift
4. OpenShift Kubernetes Engine (OKE)
Select all that apply (comma-separated): 1,2
Proposal - Implementation Details
Map from Epics (Planned) section:
### Implementation Details/Notes/Constraints
This enhancement will be delivered through the following epics:
1. **Multi-cluster metrics aggregation infrastructure** ([EPIC-1])
- Build centralized metrics collection service
- Implement storage backend for aggregated metrics
- Establish secure communication from clusters to aggregator
2. **Unified observability dashboard and visualization** ([EPIC-2])
- Develop dashboard UI components
- Integrate with metrics aggregation API
- Support customizable views and filters
3. **Fleet-wide alerting and intelligent correlation** ([EPIC-3])
- Implement alert rule engine for cross-cluster conditions
- Build notification integration (email, Slack, PagerDuty)
- Add intelligent deduplication and correlation
<Continue for all epics>
**Technical Constraints:**
* Must support 500+ clusters without performance degradation
* Metrics retention: 30 days
* Query latency: <1s for 95th percentile
Fetch linked epics if available: Query searchJiraIssuesUsingJql with jql: "parent = {feature_key} AND type = Epic" and include epic summaries and keys in the implementation details.
Risks and Mitigations
Map from Risks and Mitigation section in feature (if present), or prompt:
### Risks and Mitigations
**Risk 1: Performance degradation with >500 clusters**
* **Impact:** High - Could prevent enterprise adoption
* **Likelihood:** Medium
* **Mitigation:**
- Performance benchmarking sprint in Epic 1
- Horizontal scaling architecture from day 1
- Load testing with 1000+ simulated clusters
**Risk 2: Integration complexity with third-party monitoring tools**
* **Impact:** Medium - Affects customer adoption
* **Likelihood:** Medium
* **Mitigation:**
- Partner early with Datadog/Splunk on integration design
- Provide standardized export formats (Prometheus, OpenMetrics)
- Comprehensive integration documentation
Prompt:
What are the main risks for this enhancement?
For each risk, provide:
- Description of the risk
- Potential impact
- Mitigation strategy
Test Plan
Prompt for test strategy:
What testing is planned for this enhancement?
Consider:
- Unit tests
- Integration tests
- E2E tests
- Performance/scale tests
- Upgrade tests
## Test Plan
### Unit Tests
* Metrics collection service: 85%+ coverage
* Aggregation logic: 90%+ coverage
* API endpoints: 100% coverage
### Integration Tests
* Multi-cluster metrics collection end-to-end
* Alert rule evaluation and notification delivery
* Dashboard data rendering with live metrics
### E2E Tests
* Deploy observability stack to test cluster
* Simulate 100 managed clusters
* Verify metrics aggregation, alerting, and dashboard functionality
* Test upgrade scenario from previous version
### Performance/Scale Tests
* Baseline: 500 clusters, 10K metrics/second
* Target: <1s query latency (p95), <5% CPU overhead per cluster
Graduation Criteria
Map from Success Criteria and Timeline:
## Graduation Criteria
### Dev Preview -> Tech Preview
* Feature complete for MVP use cases (Epic 1-2)
* Basic E2E tests passing
* Documentation available
* Successfully tested with 10+ early adopter customers
* Known limitations documented
**Success signals:**
* 5+ customers using in non-production
* No critical bugs in 30 days
### Tech Preview -> GA
* All planned epics complete (Epic 1-7)
* Full E2E and scale testing complete (500+ clusters)
* Performance targets met (<1s query latency p95)
* Customer documentation complete
* Support procedures documented
* 30+ customers using in production
**Success signals:**
* Adoption: 50% of customers with 10+ clusters
* Customer satisfaction: CSAT >8.0
* Stability: <5 P1 bugs in 60 days
### Removing a deprecated feature
Not applicable - this is a new feature.
Step 5: Prompt for Missing Sections
Some sections cannot be derived from the feature and require prompts:
Drawbacks:
What are the drawbacks or downsides of this approach?
Consider:
- Added complexity
- Maintenance burden
- Performance impact
- Operational overhead
Alternatives:
What alternative approaches were considered but not implemented?
For each alternative:
- Brief description
- Why it was rejected
Upgrade/Downgrade Strategy:
How will upgrades and downgrades be handled?
Consider:
- Data migration requirements
- Backward compatibility
- Rollback procedures
- Version skew during upgrades
Support Procedures:
What procedures should support teams use to diagnose and resolve issues?
Include:
- Common failure modes
- Diagnostic steps
- Recovery procedures
- Required access/permissions
Step 6: Generate Filename and Write File
Filename generation:
def generate_filename(summary: str, component: str = None) -> str:
# Convert summary to kebab-case
filename = summary.lower()
filename = filename.replace(" ", "-")
filename = re.sub(r'[^a-z0-9-]', '', filename)
# Add .md extension
return f"{filename}.md"
# Examples:
# "Advanced HCP Observability" → "advanced-hcp-observability.md"
# "Multi-cluster Metrics" → "multi-cluster-metrics.md"
Directory selection: Suggest directory based on component:
| Component | Directory |
|---|---|
| HyperShift, ROSA, ARO | enhancements/hypershift/ |
| Networking | enhancements/network/ |
| Storage | enhancements/storage/ |
| Authentication | enhancements/authentication/ |
| Other | enhancements/ (root) |
Prompt:
Suggested directory: enhancements/hypershift/
Suggested filename: advanced-hcp-observability.md
Accept? (yes/no/edit)
Write file:
# Create directory if needed
os.makedirs(output_dir, exist_ok=True)
# Write enhancement file
with open(filepath, 'w') as f:
f.write(enhancement_content)
Step 7: Report Results
Created enhancement proposal:
File: .work/enhancements/hypershift/advanced-hcp-observability.md
Tracking: https://issues.redhat.com/browse/CNTRLPLANE-100
Next steps:
1. Review and refine technical details
2. Add reviewers and approvers to metadata
3. Complete any sections marked [TODO]
4. Share with stakeholders for feedback
5. Submit PR to openshift/enhancements repository
Sections requiring attention:
- [ ] Test Plan - Add specific test scenarios
- [ ] Support Procedures - Define diagnostic steps
- [ ] Operational Aspects - Add SLI details
Step 8: Verify and Sync with PRs (Optional)
When --verify or --sync-from-prs flags are provided, analyze linked PRs to compare or update the enhancement.
Fetch Linked PRs
Discover PRs from multiple sources:
def fetch_linked_prs(issue_key, repos=None):
"""Fetch all PRs linked to an epic/feature."""
if repos is None:
repos = [
'openshift/api',
'openshift/installer',
'openshift/machine-api-operator',
'openshift/cluster-api-provider-aws',
'openshift/hive'
]
all_prs = []
# 1. From Jira issue links (issuelinks field)
issue = fetch_issue(issue_key)
for link in issue.get('fields', {}).get('issuelinks', []):
if 'github.com' in str(link) and '/pull/' in str(link):
all_prs.append(extract_pr_info(link))
# 2. From Jira comments (GitHub bot comments)
for comment in issue.get('fields', {}).get('comment', {}).get('comments', []):
pr_links = extract_github_pr_links(comment['body'])
all_prs.extend(pr_links)
# 3. From child issues (stories, tasks, sub-epics)
child_issues = fetch_child_issues(issue_key)
for child in child_issues:
child_prs = fetch_linked_prs(child['key'], repos)
all_prs.extend(child_prs)
# 4. Search GitHub for PRs mentioning the issue key
for repo in repos:
search_query = f'repo:{repo} "{issue_key}" in:body type:pr'
github_prs = search_github(search_query)
all_prs.extend(github_prs)
# Deduplicate by PR URL
return deduplicate_prs(all_prs)
def extract_pr_info(pr_url):
"""Fetch PR details from GitHub API."""
# Extract org, repo, pr_number from URL
# https://github.com/openshift/api/pull/1234
match = re.match(r'https://github.com/([^/]+)/([^/]+)/pull/(\d+)', pr_url)
if not match:
return None
org, repo, pr_number = match.groups()
# Fetch PR via GitHub API
pr_data = github_api_get(f'/repos/{org}/{repo}/pulls/{pr_number}')
return {
'url': pr_url,
'number': int(pr_number),
'repo': f'{org}/{repo}',
'title': pr_data['title'],
'body': pr_data['body'],
'state': pr_data['state'],
'merged': pr_data.get('merged', False),
'files': fetch_pr_files(org, repo, pr_number),
'commits': fetch_pr_commits(org, repo, pr_number)
}
Verification Mode (--verify)
Compare enhancement sections against actual PR implementation:
def verify_enhancement(enhancement_path, prs):
"""Generate verification report."""
enhancement = read_enhancement(enhancement_path)
report = {
'matches': [],
'deviations': [],
'incomplete': []
}
# Verify API Extensions
api_result = verify_api_extensions(enhancement, prs)
if api_result['status'] == 'MATCHES':
report['matches'].append(api_result)
elif api_result['status'] == 'DEVIATION':
report['deviations'].append(api_result)
else:
report['incomplete'].append(api_result)
# Verify Implementation Details
impl_result = verify_implementation_approach(enhancement, prs)
if impl_result['has_deviations']:
report['deviations'].append(impl_result)
else:
report['matches'].append(impl_result)
# Verify Topology Support
topology_result = verify_topology_support(enhancement, prs)
report['incomplete'].extend(topology_result['missing'])
# Verify Test Coverage
test_result = verify_test_plan(enhancement, prs)
if test_result['has_missing_tests']:
report['incomplete'].append(test_result)
else:
report['matches'].append(test_result)
return report
def verify_api_extensions(enhancement, prs):
"""Verify API changes match enhancement."""
# Extract expected APIs from enhancement
api_section = extract_section(enhancement, "API Extensions")
expected_apis = parse_api_definitions(api_section)
# Extract actual APIs from PRs (look in openshift/api repo)
api_prs = [pr for pr in prs if pr['repo'] == 'openshift/api']
actual_apis = []
for pr in api_prs:
# Look for Go struct definitions in changed files
for file in pr['files']:
if file['filename'].endswith('.go'):
apis = extract_api_structs(file['patch'])
actual_apis.extend(apis)
# Compare
matches = []
missing = []
extra = []
for expected in expected_apis:
if find_matching_api(expected, actual_apis):
matches.append(expected)
else:
missing.append(expected)
for actual in actual_apis:
if not find_matching_api(actual, expected_apis):
extra.append(actual)
if missing or extra:
return {
'section': 'API Extensions',
'status': 'DEVIATION',
'expected': expected_apis,
'actual': actual_apis,
'missing': missing,
'extra': extra,
'prs': [pr['url'] for pr in api_prs]
}
else:
return {
'section': 'API Extensions',
'status': 'MATCHES',
'prs': [pr['url'] for pr in api_prs]
}
def verify_test_plan(enhancement, prs):
"""Verify test coverage matches enhancement."""
test_section = extract_section(enhancement, "Test Plan")
expected_tests = parse_test_requirements(test_section)
# Find test files in PRs
test_files = []
for pr in prs:
for file in pr['files']:
if '_test.go' in file['filename'] or 'test_' in file['filename']:
test_files.append({
'file': file['filename'],
'pr': pr['url'],
'type': classify_test_type(file['filename'])
})
# Check for missing test types
missing = []
if 'unit' in expected_tests and not any(t['type'] == 'unit' for t in test_files):
missing.append('Unit tests')
if 'integration' in expected_tests and not any(t['type'] == 'integration' for t in test_files):
missing.append('Integration tests')
if 'e2e' in expected_tests and not any(t['type'] == 'e2e' for t in test_files):
missing.append('E2E tests')
return {
'section': 'Test Plan',
'status': 'INCOMPLETE' if missing else 'MATCHES',
'expected': expected_tests,
'actual': test_files,
'missing': missing,
'has_missing_tests': bool(missing)
}
Verification Report Format:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VERIFICATION REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Enhancement: ec2-dedicated-hosts-on-aws.md
Tracking: OCPSTRAT-1596
PRs analyzed: 12
✅ API Extensions (2 PRs)
Expected: AWSMachineProviderConfig.placement.dedicatedHost
Actual: Matches in openshift/api#1234
Status: MATCHES
⚠️ Topology Support (3 PRs)
Expected: HCP and Standalone
Actual: HCP only (openshift/installer#5678)
Deferred: Standalone support (planned for 4.23)
Status: DEVIATION
❌ Test Coverage (4 PRs)
Expected: Unit, Integration, E2E
Actual: Unit tests only
Missing: Integration tests, E2E tests
Status: INCOMPLETE
✅ Implementation Approach (5 PRs)
Expected: MAPI shim + CAPI conversion
Actual: CAPI-only in cluster-api-provider-aws#789
Note: Approach changed based on upstream decision
Status: DEVIATION (documented in PR)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Matches: 2
⚠️ Deviations: 2 (approach changed, standalone deferred)
❌ Incomplete: 1 (test coverage)
Recommendation: UPDATE ENHANCEMENT
The enhancement should be updated to reflect the CAPI-only approach
and document that standalone support is deferred to 4.23.
Run: /jira:generate-enhancement OCPSTRAT-1596 --sync-from-prs
Sync Mode (--sync-from-prs)
Update enhancement based on actual PR implementation:
def sync_enhancement_from_prs(enhancement_path, prs, interactive=False):
"""Update enhancement with actual implementation."""
enhancement = read_enhancement(enhancement_path)
updates = []
# Analyze PRs for implementation details
api_changes = extract_api_changes(prs)
implementation_approach = analyze_implementation_approach(prs)
test_coverage = analyze_test_coverage(prs)
topology_support = analyze_topology_support(prs)
# Update API Extensions section
if not is_manual_section(enhancement, "API Extensions"):
new_api_section = generate_api_section_from_prs(api_changes)
updates.append({
'section': 'API Extensions',
'old': extract_section(enhancement, 'API Extensions'),
'new': new_api_section
})
# Update Implementation Details
if not is_manual_section(enhancement, "Implementation Details"):
new_impl_section = generate_implementation_section(implementation_approach)
updates.append({
'section': 'Implementation Details',
'old': extract_section(enhancement, 'Implementation Details'),
'new': new_impl_section
})
# Update Test Plan
if not is_manual_section(enhancement, "Test Plan"):
new_test_section = generate_test_section_from_prs(test_coverage)
updates.append({
'section': 'Test Plan',
'old': extract_section(enhancement, 'Test Plan'),
'new': new_test_section
})
# Update Topology Considerations
if not is_manual_section(enhancement, "Topology Considerations"):
new_topology_section = generate_topology_section(topology_support)
updates.append({
'section': 'Topology Considerations',
'old': extract_section(enhancement, 'Topology Considerations'),
'new': new_topology_section
})
# Add Implementation Notes section for deviations
deviations = find_deviations(enhancement, prs)
if deviations and not is_manual_section(enhancement, "Implementation Notes"):
impl_notes = generate_implementation_notes(deviations)
updates.append({
'section': 'Implementation Notes (NEW)',
'old': None,
'new': impl_notes
})
# Apply updates (with interactive prompts if requested)
for update in updates:
if interactive:
print(f"\n{'='*60}")
print(f"Section: {update['section']}")
print(f"{'='*60}")
print(f"\n--- OLD ---\n{update['old'][:500]}...")
print(f"\n--- NEW ---\n{update['new'][:500]}...")
response = input("\nApply this change? (y/n/diff): ")
if response == 'diff':
show_unified_diff(update['old'], update['new'])
response = input("Apply? (y/n): ")
if response != 'y':
continue
enhancement = replace_section(enhancement, update['section'], update['new'])
# Update metadata
enhancement = update_frontmatter(enhancement, {
'last-updated': datetime.now().strftime('%Y-%m-%d'),
'last-synced': datetime.now().strftime('%Y-%m-%d'),
'prs-analyzed': len(prs)
})
# Write updated enhancement
write_enhancement(enhancement_path, enhancement)
return {
'updated_sections': [u['section'] for u in updates],
'prs_analyzed': len(prs)
}
def is_manual_section(enhancement, section_name):
"""Check if section is marked as manual (via comment or frontmatter)."""
# Check for <!-- MANUAL --> comment in section content
section = extract_section(enhancement, section_name)
if section and '<!-- MANUAL' in section:
return True
# Check for sync-exclude in frontmatter
frontmatter = extract_frontmatter(enhancement)
if frontmatter:
sync_exclude = frontmatter.get('sync-exclude', [])
if section_name in sync_exclude:
return True
return False
def extract_frontmatter(enhancement):
"""Extract YAML frontmatter from enhancement."""
import re
import yaml
match = re.match(r'^---\n(.*?)\n---', enhancement, re.DOTALL)
if match:
try:
return yaml.safe_load(match.group(1))
except:
return None
return None
def generate_implementation_notes(deviations):
"""Generate Implementation Notes section."""
notes = ["## Implementation Notes\n\n"]
notes.append("This section documents deviations from the original enhancement proposal based on actual implementation.\n\n")
for deviation in deviations:
notes.append(f"### {deviation['title']}\n\n")
notes.append(f"**Original Proposal:** {deviation['expected']}\n\n")
notes.append(f"**Actual Implementation:** {deviation['actual']}\n\n")
notes.append(f"**Reason:** {deviation['reason']}\n\n")
notes.append(f"**PRs:** {', '.join(deviation['prs'])}\n\n")
return ''.join(notes)
Interactive Sync Example:
Syncing enhancement from PRs...
Found 12 PRs:
openshift/api: 2 PRs
openshift/installer: 3 PRs
openshift/cluster-api-provider-aws: 4 PRs
openshift/machine-api-operator: 2 PRs
openshift/hive: 1 PR
============================================================
Section: API Extensions
============================================================
--- OLD ---
### API Extensions
Add new fields to the `AWSMachineProviderConfig` spec:
```yaml
placement:
dedicatedHost:
hostId: h-0123456789abcdef0
```
--- NEW ---
### API Extensions
#### AWSMachineProviderConfig API
Based on implementation in openshift/api#1234:
```yaml
apiVersion: machine.openshift.io/v1beta1
kind: AWSMachineProviderConfig
spec:
placement:
dedicatedHost:
id: h-0123456789abcdef0
resourceGroupArn: arn:aws:ec2:...
tenancy: host
```
Apply this change? (y/n/diff): diff
[Shows unified diff]
Apply? (y/n): y
✓ Updated API Extensions
============================================================
Section: Implementation Notes (NEW)
============================================================
--- OLD ---
[Section does not exist]
--- NEW ---
## Implementation Notes
### MAPI Shim Approach Abandoned
**Original Proposal:** Add shim fields to MAPI, convert to CAPI
**Actual Implementation:** CAPI-only approach
**Reason:** Upstream CAPA added native dedicated host support
**PRs:** openshift/cluster-api-provider-aws#789
Apply this change? (y/n/diff): y
✓ Added Implementation Notes section
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Sync complete!
Updated sections: 4
PRs analyzed: 12
Enhancement updated: ec2-dedicated-hosts-on-aws.md
Manual Edit Protection
Users can mark sections to prevent sync from overwriting:
Comment-based:
## Motivation
<!-- MANUAL: Strategic rationale - do not sync -->
Enterprise customers deploying ROSA...
[manually written content]
Frontmatter-based:
---
title: ec2-dedicated-hosts-on-aws
sync-exclude:
- Motivation
- User Stories
- Drawbacks
---
The sync process will skip these sections and report:
Preserved manual sections:
- Motivation (marked <!-- MANUAL -->)
- User Stories (in sync-exclude)
Content Mapping Reference
Jira Feature → Enhancement Mapping
| Jira Section | Enhancement Section | Transformation |
|---|---|---|
| Summary | Title (metadata) | Convert to kebab-case |
| Overview | Summary | Direct copy |
| Market Problem | Motivation | Direct copy + context |
| Customer Value | User Stories | Convert to "As a... I want... So that..." |
| Strategic Value | Goals | Extract objectives |
| Out of Scope | Non-Goals | Direct copy |
| Proposed Solution | Workflow Description | Expand into step-by-step |
| Epics (Planned) | Implementation Details | List epics with details |
| Success Criteria | Graduation Criteria | Map adoption/outcomes to GA criteria |
| Timeline | Graduation Criteria | Map milestones to Dev Preview/Tech Preview/GA |
| Risks | Risks and Mitigations | Direct copy + expand |
Enhancement Template Placeholders
For sections that cannot be derived from the feature, use informative placeholders:
## Alternatives (Not Implemented)
**TODO:** Describe alternative approaches that were considered but not selected.
For each alternative:
- Brief description of the approach
- Pros and cons compared to the chosen solution
- Why it was rejected
Example alternatives to consider:
- Different architectural patterns
- Alternative technologies or frameworks
- Simpler approaches that were insufficient
Validation Checks
Before writing the file, validate:
Required sections present:
- ✅ Summary (from epic/feature overview)
- ✅ Motivation (from background or market problem)
- ✅ Goals (from goals section or strategic value)
- ✅ Proposal (from child issues or solution)
- ⚠️ User Stories (generated or prompted)
- ⚠️ Test Plan (prompted)
- ⚠️ Graduation Criteria (from acceptance criteria or success criteria)
Metadata complete:
- ✅ Title generated
- ✅ Creation date from epic/feature
- ✅ Tracking link to epic/feature
- ⚠️ Authors (prompt if needed)
- ⚠️ Reviewers (prompt)
- ⚠️ Approvers (prompt)
Quality checks:
- ✅ No [TODO] markers without explanation
- ✅ No Jira wiki markup (h2., *, etc.) in final markdown
- ✅ All internal links valid
- ✅ Consistent terminology
Jira Wiki Markup Conversion
Epics and features often use Jira wiki markup which must be converted to standard markdown:
| Jira Wiki | Markdown |
|---|---|
h2. Heading | ## Heading |
h3. Heading | ### Heading |
* bullet | * bullet (same) |
# numbered | 1. numbered |
[PROJ-123] | [PROJ-123](https://issues.redhat.com/browse/PROJ-123) |
{{code}} | `code` |
def convert_jira_to_markdown(jira_text: str) -> str:
# Convert headings
text = re.sub(r'^h2\.\s+(.+)$', r'## \1', jira_text, flags=re.MULTILINE)
text = re.sub(r'^h3\.\s+(.+)$', r'### \1', text, flags=re.MULTILINE)
# Convert Jira links
text = re.sub(r'\[([A-Z]+-\d+)\]',
r'[\1](https://issues.redhat.com/browse/\1)', text)
# Convert inline code
text = re.sub(r'{{(.+?)}}', r'`\1`', text)
return text
Error Handling
Wrong Issue Type
Scenario: Issue is not type "Epic" or "Feature"
Action:
CNTRLPLANE-123 is a Story, not an Epic or Feature.
This command requires an Epic or Feature issue type.
To create an enhancement from a Story, consider:
1. Convert the Story to an Epic or Feature first
2. Manually create the enhancement using the template
Empty Description
Scenario: Epic or Feature has no description or minimal content
Action:
Issue CNTRLPLANE-100 has minimal content.
Enhancement proposals require substantial detail. Please:
1. Complete the epic/feature description in Jira
2. Run /jira:generate-enhancement again
Or continue with interactive prompts to fill in details? (yes/no)
Cannot Determine Component
Scenario: Cannot auto-detect component/directory from epic/feature
Action:
Cannot determine the appropriate directory for this enhancement.
Please select:
1. enhancements/ (root - for broad-impact enhancements)
2. enhancements/hypershift/ (HyperShift/ROSA/ARO)
3. enhancements/network/ (Networking)
4. enhancements/storage/ (Storage)
5. enhancements/authentication/ (Auth/Identity)
6. Other (specify)
Selection:
Best Practices
- Complete epic/feature first: Ensure Jira epic or feature has comprehensive content before generation
- Review AI-generated content: Enhancement is a starting point, not final document
- Add technical depth: Expand implementation details with architecture diagrams, API specs
- Iterate with reviewers: Share draft early for feedback
- Keep Jira updated: Update epic/feature as enhancement evolves, or regenerate enhancement from updated Jira content
- Link bidirectionally: Add enhancement PR link to epic/feature, epic/feature link in enhancement metadata
Example Enhancement Generation
Input Feature: CNTRLPLANE-100
Summary: Advanced observability for hosted control planes
Description:
Deliver unified observability capabilities for ROSA and ARO hosted control planes.
h2. Market Problem
Enterprise customers with 50+ clusters face significant operational challenges...
h2. Proposed Solution
Build a comprehensive observability platform...
h2. Strategic Value
h3. Customer Value
* 60% reduction in cluster management time
* 80% faster incident detection
h2. Scope
h3. Epics (Planned)
* Epic 1: Multi-cluster metrics aggregation
* Epic 2: Unified dashboard
* Epic 3: Fleet-wide alerting
h2. Timeline
* Target: Q3 2025 (4.23 GA)
Generated Enhancement:
---
title: advanced-observability-for-hosted-control-planes
authors:
- "@jdoe"
reviewers:
- "@reviewer1"
- "@reviewer2"
approvers:
- "@team-lead"
api-approvers:
- None
creation-date: 2025-01-15
last-updated: 2025-03-31
status: provisional
tracking-link:
- https://issues.redhat.com/browse/CNTRLPLANE-100
---
# Advanced Observability for Hosted Control Planes
## Summary
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.
## Motivation
Enterprise customers managing multiple ROSA HCP clusters (50+) face significant
operational challenges...
[Full enhancement content continues...]
See Also
/jira:generate-feature-doc- Generate feature documentation/jira:create- Create Jira issues- OpenShift Enhancement Process: https://github.com/openshift/enhancements
Jira Conventions Router
This skill routes to the correct project or team conventions based on the Jira project key, component, or keywords in the issue summary.
Routing Table
Match on project key, component, or summary keywords. Load the corresponding reference file.
By Project Key
| Project Key | Conventions | Reference |
|---|---|---|
| CNTRLPLANE | Red Hat OpenShift Control Planes — features, epics, stories, tasks | CNTRLPLANE conventions |
| OCPBUGS | OpenShift Bugs — bug reports only | OCPBUGS conventions |
| GCP | GCP Hosted Control Planes (Hypershift on GKE) — stories, epics, tasks, bugs, features | GCP HCP conventions |
| TRT | Technical Release Team — story, bug, spike, task and ticket templates, readiness criteria, concision rubric | TRT conventions |
By Team / Keywords
Detect these keywords in the issue summary, description, or component to layer team-specific conventions on top of project conventions:
| Keywords | Team Conventions | Reference |
|---|---|---|
| HyperShift, ARO HCP, ROSA HCP, hosted control plane | HyperShift team — component selection (HyperShift / ARO, HyperShift / ROSA, HyperShift) | HyperShift conventions |
| GCP HCP, Hypershift on GKE, GKE hosted control plane | GCP HCP team — GCP project conventions, team templates, sizing guide | GCP HCP conventions |
Layering Rules
- Project conventions are loaded first based on the project key
- Team conventions are layered on top when keywords match
- Both can apply simultaneously (e.g., CNTRLPLANE + HyperShift)
- If no project or team matches, skip this skill — the issue uses only type-specific guidance from the
createskill
How to Use
After identifying the matching conventions:
- Read the linked reference file(s)
- Apply project-specific custom fields, version handling, and component requirements
- Layer team-specific conventions if keywords match (component selection, labels, templates)
- Defer to the
createskill for issue-type guidance (story template, bug template, etc.), except where a loaded project or team reference defines its own template or requirement for that issue type: the reference wins on any conflict.- For example, a reference that makes a Spike's time box recommended (not required) means a Spike may be created or refined without one.
Jira Feature Documentation Generator
This skill provides detailed step-by-step implementation guidance for the /jira:generate-feature-doc command, which generates comprehensive feature documentation by recursively analyzing a Jira feature and all its related issues and GitHub pull requests.
IMPORTANT FOR AI: This is a procedural skill - when invoked, you should directly execute the implementation steps defined in this document. Do NOT look for or execute external scripts. Follow the step-by-step instructions below, starting with Step 1.
When to Use This Skill
This skill is automatically invoked by the /jira:generate-feature-doc command and should not be called directly by users.
Prerequisites
- MCP Jira server configured and running (required - see
plugins/jira/README.mdfor setup) - GitHub CLI (
gh) installed and authenticated (for analyzing PRs) - User has read access to Jira issues (including private issues via MCP authentication)
- User has read access to linked GitHub repositories
- Working directory has
.work/jira/feature-doc/for output (will be created if needed)
Implementation Steps
Step 1: Initialize and Fetch Main Feature Issue
Objective: Set up environment and fetch main feature issue.
Actions:
-
Save initial directory:
INITIAL_DIR=$(pwd)(save at start, before any cd commands) -
Check prerequisites: Verify
jqandghCLI are installed and authenticated- If missing, display error with installation instructions
-
Create output directory:
WORK_DIR=$INITIAL_DIR/.work/jira/feature-doc/<feature-key>(usemkdir -p) -
Fetch main feature via
getJiraIssuewith the feature key. If MCP is unavailable, display error pointing toplugins/jira/README.md. -
Parse response: Extract
key,summary,description,issuetype,status- If fetch fails, display error and exit
-
Display progress: Show feature summary and type
Step 2: Analyze Each GitHub PR
Important: This step expects PR data as input from the jira:extract-prs skill (invoked by the command file). The input is structured JSON containing all discovered PRs with their metadata.
Input Format:
{
"pull_requests": [
{
"url": "https://github.com/org/repo/pull/123",
"state": "MERGED",
"title": "PR title",
"isDraft": false,
"sources": ["remote_link", "description"],
"found_in_issues": ["ISSUE-123"]
}
]
}
Objective: Fetch and analyze PR details to extract implementation information.
Important: This command is for documenting completed features. Only analyze PRs that have been MERGED. Skip OPEN, DRAFT, WIP, or CLOSED (but not merged) PRs.
Actions:
-
Filter for MERGED PRs: Only analyze PRs with
state == "MERGED"ANDisDraft == false- Skip OPEN PRs (work in progress)
- Skip PRs with
isDraft == true(not ready for review) - Skip CLOSED PRs (not merged)
-
For each MERGED PR, fetch detailed data:
- Parse PR URL to extract org/repo/number
- Fetch metadata:
gh pr view {number} --repo {org}/{repo} --json title,body,mergedAt,author,commits,files - Fetch diff:
gh pr diff {number} --repo {org}/{repo} - Fetch comments:
gh pr view {number} --repo {org}/{repo} --json comments
-
Extract key information:
- From body: Purpose, approach, breaking changes
- From commits: Implementation steps, testing
- From diff: New APIs, architectural changes, config updates
- From comments: Design decisions, rationale, considerations
-
Handle errors: If PR inaccessible (403, 404), log warning and continue
-
Save data: Store metadata, diff, and comments to
${WORK_DIR}/pr-{org}-{repo}-{number}.*
Step 3: Synthesize Documentation Structure
Objective: Organize information into structured outline.
Available sections (calling command specifies which to generate):
- Overview: Jira link, status, counts, dates, authors (from main issue + PR metadata)
- Background and Goals: Description from main issue (clean Jira formatting)
- Architecture and Design: High-level changes, components, design decisions (from PRs)
- Implementation Details: Core changes, API changes, configuration (from PR diffs, code snippets)
- Usage Guide: Prerequisites, basic/advanced usage (from README updates, PR descriptions)
- Testing: Test coverage, strategies, key test PRs
- Related Resources: Can include external links, issue tables, PR tables, dependency graphs
Step 4: Generate Documentation Content
Objective: Fill in the outline with actual content based on command requirements.
Section generation guidelines:
- Overview: Extract from main issue + PR metadata (Jira link, status, counts, dates, authors)
- Background: Clean Jira formatting from main issue description
- Architecture: Synthesize from PR descriptions and comments (high-level overview, components, decisions with PR links)
- Implementation: Group by core changes, API changes, configuration (include code snippets, link to PRs, list key files)
- Usage: Extract from README updates and PR descriptions (prerequisites, YAML/CLI examples)
- Testing: Summarize by category (unit, E2E, CI), list key test PRs
- Related Resources: Format depends on command requirements (external links, tables, graphs)
Note: Only generate sections specified by the calling command. Check the command file for exact requirements.
Step 5: Output
Objective: Save documentation and display summary.
Actions:
-
Write documentation: Save to
${WORK_DIR}/feature-doc.mdwith footer:--- *Generated by `/jira:generate-feature-doc` on <timestamp>* *Source: <feature-key> and <count> related issues* -
Save metadata: Store analysis log with timestamps, counts, output files, errors/warnings
-
Display summary:
- Success message with file location
- Statistics: issues analyzed, PRs analyzed, commits, files changed, doc lines
- Warnings if any (inaccessible PRs, missing descriptions)
- Additional files for debugging
Error Handling
Issue Not Found (404, 403, network error):
- Display error with verification steps (issue key format, permissions, MCP config)
- Display the error message, clean up any temporary state, and exit without creating files
No PRs Found:
- Display warning (feature not implemented, PRs not linked, or small feature)
- Generate documentation from main issue only
GitHub Rate Limit:
- Display error with progress and reset time
- Offer options: wait, generate from partial data, or cancel
Large Feature (>50 PRs):
- Display warning with estimated time and API calls
- Offer options: continue or cancel
Malformed Issue Data:
- Log warning about missing/invalid fields
- Continue with remaining issues (don't fail entire process)
Performance Optimization
Parallel PR Analysis:
- For >10 PRs, use parallel processing (
xargs -P 5) - Limit to ~5 concurrent requests to avoid rate limits
Smart Diff Analysis:
- Use
--statto identify key files - Skip vendor/, generated files, test fixtures
- Fetch full diff only for critical files
Best Practices for AI Implementation
-
Progress feedback: Show progress after each major step (discovery, PR analysis, etc.)
-
Error resilience: Don't fail the entire process if one PR is inaccessible
-
Smart synthesis: Don't just concatenate PR descriptions - synthesize into coherent narrative
-
Context awareness: Understand the codebase domain (e.g., Kubernetes, OpenShift) to better interpret changes
-
Structured output: Use consistent markdown formatting with proper headers, code blocks, tables
-
Link preservation: Always provide clickable links to Jira issues and GitHub PRs
-
Timestamp tracking: Note when PRs were merged to understand timeline
-
Author attribution: Credit authors of PRs and issues where relevant
-
Code examples: Include actual code snippets from PRs to illustrate changes
-
Visual hierarchy: Use tables, lists, and headers to make documentation scannable
Example Workflow
User runs: /jira:generate-feature-doc OCPSTRAT-1612
1. Initialize
- Fetch main feature issue (OCPSTRAT-1612)
- Create working directory (.work/jira/feature-doc/OCPSTRAT-1612/)
- Verify prerequisites (jq, gh CLI)
2. Extract PRs (via extract-prs skill)
- Discover descendants using `parent = KEY` BFS → 3 issues total
- Extract PRs from remote links (primary) + text (backup) → 7 PRs
- Fetch PR state from GitHub → 5 MERGED, 1 OPEN, 1 CLOSED
3. Analyze MERGED PRs
- Filter for MERGED PRs → 5 PRs to analyze
- For each: fetch metadata + diff + comments
- Extract implementation details, design decisions
4. Generate Documentation
- Synthesize sections: Overview, Architecture, Implementation, Usage, Testing
- Create tables for issues and PRs
- Write to feature-doc.md
5. Display Results
✅ Documentation generated successfully!
📄 File: .work/jira/feature-doc/OCPSTRAT-1612/feature-doc.md
📊 3 issues, 5 MERGED PRs, ~380 lines generated
JIRA Issues by Component - Helper Skill
This skill provides a secure curl wrapper script for the jira:issues-by-component command. The wrapper prevents JIRA authentication token exposure in process listings and command history.
When to Use This Skill
This skill is automatically used by the jira:issues-by-component command. You typically don't need to invoke it directly unless you're:
- Developing or testing JIRA API integrations
- Building custom JIRA scripts that need secure authentication
- Debugging JIRA API connectivity issues
Security Benefits
The jira_curl.sh wrapper script provides:
- Token Protection: Authentication tokens never appear in process listings (
ps aux) - History Safety: Tokens are not saved in shell history files
- Process Isolation: Token is read from environment variables inside the script
- Clean Interface: Same curl arguments you're already familiar with
Files
jira_curl.sh
Secure curl wrapper that automatically adds JIRA authentication headers.
Location: plugins/jira/skills/jira-issues-by-component/jira_curl.sh
Usage:
jira_curl.sh [curl arguments...]
Required Environment Variables:
JIRA_URL: JIRA instance URL (e.g.,https://redhat.atlassian.net)JIRA_API_TOKEN: Authentication tokenJIRA_USERNAME: Atlassian account email for Basic auth
Example:
# Set credentials
export JIRA_URL="https://redhat.atlassian.net"
export JIRA_API_TOKEN="your-token-here"
export JIRA_USERNAME="user@redhat.com"
# Use wrapper (token hidden from process list)
jira_curl.sh -s -X POST -d '{"jql":"project=OCPBUGS"}' https://redhat.atlassian.net/rest/api/3/search/jql
How It Works
- Environment Check: Validates that
JIRA_URLand authentication token are set - Token Selection: Uses
JIRA_API_TOKENfor Atlassian Cloud authentication - Header Injection: Constructs
Authorization: Basic <base64>header inside the script usingJIRA_USERNAMEandJIRA_API_TOKEN - Process Replacement: Uses
exec curlto replace the script process with curl - Clean Execution: Token never crosses process boundaries as a visible argument
Implementation Details
The wrapper uses the same security pattern as the oc auth skill:
# Token and username are read from environment variables inside the script
AUTH_TOKEN="${JIRA_API_TOKEN:-}"
JIRA_USER="${JIRA_USERNAME:-}"
# Execute curl with Basic authentication header
# Credentials are constructed here, never visible in parent process command line
AUTH_HEADER=$(printf '%s:%s' "$JIRA_USER" "$AUTH_TOKEN" | base64)
exec curl -H "Authorization: Basic $AUTH_HEADER" -H "Accept: application/json" "$@"
Why exec?
- Replaces the script process with curl process
- By the time curl runs, the wrapper script is gone
- Only curl appears in process listings, not the wrapper with token
Error Handling
The script provides clear error messages for common scenarios:
Missing JIRA_URL:
Error: JIRA_URL environment variable is required
Please set JIRA credentials:
export JIRA_URL='https://redhat.atlassian.net'
export JIRA_API_TOKEN='your-token-here'
Alternatively, source a credentials file:
source ~/.jira-credentials
Missing Token:
Error: JIRA authentication token is required
Please set:
export JIRA_API_TOKEN='your-token-here'
export JIRA_USERNAME='user@redhat.com'
Get your token from:
- Atlassian API Token: https://id.atlassian.com/manage-profile/security/api-tokens
Credentials Setup
Option 1: Export Directly
export JIRA_URL="https://redhat.atlassian.net"
export JIRA_API_TOKEN="your-token-here"
export JIRA_USERNAME="user@redhat.com"
Option 2: Credentials File (Recommended)
Create ~/.jira-credentials:
# ~/.jira-credentials
export JIRA_URL="https://redhat.atlassian.net"
export JIRA_API_TOKEN="your-token-here"
export JIRA_USERNAME="user@redhat.com"
Secure the file:
chmod 600 ~/.jira-credentials
Source it when needed:
source ~/.jira-credentials
Getting Your Token
Atlassian Cloud (API Token)
- Visit: https://id.atlassian.com/manage-profile/security/api-tokens
- Click "Create API token"
- Give it a label (e.g., "CLI Access")
- Copy the token
- Set as
JIRA_API_TOKEN
Comparison to Direct Curl
Insecure Approach (Don't Do This)
# Credentials exposed in process list and history!
curl -u "user@redhat.com:${JIRA_API_TOKEN}" -X POST \
-H "Content-Type: application/json" \
-d '{"jql":"..."}' \
https://redhat.atlassian.net/rest/api/3/search/jql
Problems:
- ❌ Token visible in
ps aux - ❌ Token saved in shell history
- ❌ Token may appear in logs
- ❌ Security risk
Secure Approach (Use This)
# Token hidden inside wrapper script
jira_curl.sh -X POST -H "Content-Type: application/json" \
-d '{"jql":"..."}' https://redhat.atlassian.net/rest/api/3/search/jql
Benefits:
- ✅ Token never in process list
- ✅ Token never in shell history
- ✅ Clean and simple syntax
- ✅ Secure by design
Integration with jira:issues-by-component
The jira:issues-by-component command uses this wrapper to fetch JIRA issues securely:
# Get path to secure curl wrapper
PLUGIN_DIR="plugins/jira/skills/jira-issues-by-component"
JIRA_CURL="${PLUGIN_DIR}/jira_curl.sh"
# Fetch issues with pagination (token hidden)
HTTP_CODE=$("$JIRA_CURL" -s -w "%{http_code}" \
-o "batch-${BATCH_NUM}.json" \
"${API_URL}")
This approach:
- Handles 2000+ issues efficiently
- Streams data directly to disk
- Never exposes authentication token
- Avoids LLM token consumption
See Also
- oc auth skill - Similar pattern for OpenShift authentication
- jira:issues-by-component command - Command that uses this skill
- CLAUDE.md - Plugin development guide
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 Jira tools available (Atlassian Rovo MCP)
- 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
--bugflag value (optional, for single bug validation mode)
Project:
- Hardcoded to "OCPBUGS" project
Validate inputs:
- If neither
--bugnortarget-versionis 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:
-
Single bug mode (if
--bugis provided):- Skip JQL query construction
- Use
getJiraIssueto fetch the single bug - Target version and component filter are ignored in this mode
- Proceed to analysis with single bug only
-
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
-
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:
project = OCPBUGS AND type = Bug AND "Release Blocker" = Proposed
IMPORTANT: Use "Release Blocker" = Proposed NOT cf[12319743]. The field ID customfield_10847 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:
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:
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:
AND component = "{COMPONENT}"
Multiple components (comma-separated):
AND component IN ({COMPONENT_LIST})
Final JQL examples:
Version only (4.21):
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"):
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"):
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 searchJiraIssuesUsingJql:
- jql: The constructed JQL query from Phase 2
- fields: ["key", "summary", "priority", "severity", "status", "assignee", "created", "updated", "labels", "components", "description", "reporter", "customfield_10847", "customfield_10855"]
- maxResults: 100 (maximum per page; use
nextPageTokento paginate if more results exist)
Parse the response to extract:
- Total count of proposed blockers
- List of bug objects with all required fields
Custom fields to include:
customfield_10847- Release Blocker status (should be "Proposed")customfield_10855- Target Version
For single bug mode (--bug flag), fetch the bug by key via getJiraIssue:
- issueIdOrKey: The bug key provided by user
- expand: "renderedFields"
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
- Look for labels:
Workaround Assessment (may affect recommendation):
An acceptable workaround must meet ALL three criteria:
- Idempotent - can be applied repeatedly without resulting change
- Safe at scale - can be safely deployed to 1000's of clusters without material risk via automation
- 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:
- Fetch bug details including summary, description, labels, priority, severity, comments
- 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
- Check labels:
- 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
- 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)
- Use
- 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:
getJiraIssuewith 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:
# 🚫 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
searchJiraIssuesUsingJqlfails, display JQL query and error message - If
getJiraIssuefails:- Fallback to WebFetch: Try fetching via
https://redhat.atlassian.net/browse/{issue-key} - If WebFetch succeeds: Parse the web page to extract bug details (summary, severity, description) and continue with validation
- If WebFetch also fails: Display clear error indicating bug doesn't exist or isn't accessible
- Fallback to WebFetch: Try fetching via
- 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
searchJiraIssuesUsingJqlwith appropriatemaxResults(avoid pagination when possible) - Caching: Store bug data in memory during execution to avoid re-querying JIRA
JQL Query Examples
Version only (4.21):
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"):
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):
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")
Custom Fields
| Field Name | Field ID | JQL Name | Type |
|---|---|---|---|
| Release Blocker | customfield_10847 | "Release Blocker" | String |
| Target Version | customfield_10855 | "Target Version" | String |
Name
jira:ready-to-solve
Synopsis
/jira:ready-to-solve <jira-issue-key> [--dry-run] [--verbose] [--fix]
Description
The jira:ready-to-solve command checks whether a Jira issue has sufficient grooming for /jira:solve to produce a quality solution.
It runs a two-phase validation:
- Deterministic checks via a Python script that verifies structural requirements: required sections exist, are non-empty, and have adequate content.
- AI qualitative assessment that evaluates whether the acceptance criteria are specific and testable, whether there is enough implementation context, and whether clear success/failure conditions exist.
On pass, the label ready-to-solve is added to the issue. On fail, not-ready-to-solve is added. The stale opposite label is removed if present.
With --fix, when validation fails the command generates a revised description that adds or improves the failing sections, shows the proposed changes to the user for approval, and updates the Jira issue description upon confirmation.
Prerequisites
- Jira MCP server configured (Atlassian Rovo MCP)
- Python 3.8+ (
which python3)
Implementation
Phase 1: Fetch Issue Data
Fetch the issue via getJiraIssue with the issue key.
Extract from the response:
fields.description-- full description textfields.summary-- issue titlefields.labels-- current labels array (needed for label updates)fields.status.name-- current statusfields.issuetype.name-- issue type
If description is null or empty, skip to Phase 4 with an automatic FAIL verdict.
Phase 2: Run Deterministic Checks
Pipe the description to the Python script:
echo '{"description": "<description_content>"}' | python3 plugins/jira/skills/ready-to-solve/scripts/check_sections.py
For verbose output (includes matched content):
echo '{"description": "<description_content>"}' | python3 plugins/jira/skills/ready-to-solve/scripts/check_sections.py --verbose
Important: Construct the JSON input carefully. The description may contain quotes, newlines, and special characters. Use Python or jq to safely serialize:
echo "$DESCRIPTION" | jq -Rs '{"description": .}' | python3 plugins/jira/skills/ready-to-solve/scripts/check_sections.py
The script outputs JSON with per-check results. Parse the output to get:
overall_pass: boolean -- whether all REQUIRED checks passedchecks: array of individual check resultsstats: summary counts
Deterministic checks performed by the script:
| Check ID | Name | Pass Condition | Severity |
|---|---|---|---|
has_context | Context section present | Heading matching: Context, Description, Background, Overview, or Why | REQUIRED |
has_ac | Acceptance Criteria present | Heading matching: Acceptance Criteria, AC, or Definition of Done | REQUIRED |
context_not_empty | Context has content | At least 50 characters below the heading | REQUIRED |
ac_not_empty | AC has content | At least 30 characters below the heading | REQUIRED |
has_tech | Technical Details present | Heading matching: Technical Details, Technical Context, Implementation Details, Implementation Notes, or Technical Notes | REQUIRED |
tech_not_empty | Technical Details has content | At least 30 characters below the heading | REQUIRED |
ac_has_items | AC has multiple items | Warns if fewer than 2 bullet points or numbered items | WARNING |
min_description_length | Adequate overall length | Total description at least 200 characters | WARNING |
Note: WARNING checks are reported but do not block the overall verdict. Only REQUIRED checks must pass for the issue to be considered ready.
Phase 3: AI Qualitative Assessment
Read the full description and evaluate three dimensions. For each, produce a verdict (PASS or FAIL) and a 1-2 sentence justification.
-
AC Specificity and Testability: Are acceptance criteria specific enough to write tests against? Do they describe observable behavior rather than vague goals?
- FAIL: no acceptance criteria, or criteria are vague ("it should work", "system performs well")
- PASS: criteria describe observable behavior ("when X happens, Y returns Z", "API returns 404 for missing resources")
-
Implementation Context Sufficiency: Is there enough description of the problem, affected code area, or desired behavior that
/jira:solvecould identify relevant files and implement a solution?- FAIL: a codebase search would be ambiguous (no component, file, or feature area mentioned)
- PASS: the description points to a specific area of the codebase, component, or behavior
-
Clear Success/Failure Conditions: Can a reviewer determine whether a proposed solution addresses the issue?
- FAIL: no way to tell if a solution is correct (no expected behavior, no test criteria)
- PASS: conditions are explicit enough to verify a solution
Phase 4: Aggregate Verdict
overall_pass = (all REQUIRED deterministic checks pass) AND (no AI check has verdict FAIL)
Collect all failures and warnings into a list for the report.
Phase 5: Fix Failing Checks (if --fix)
Skip if --fix is not set or if validation already passed.
When validation fails and --fix is set, generate a revised description that fixes the failing checks:
-
Identify failures: Collect all failed deterministic checks and AI qualitative FAILs from phases 2-4.
-
Generate revised description: Preserve ALL existing content from the original description. Only add or expand sections -- never remove or rewrite content the user wrote. For each failure:
- Missing Context/Why section: Generate an
h2. Whysection from the issue summary and any context in the existing description text. - Missing Acceptance Criteria: Generate an
h2. Acceptance Criteriasection with concrete, testable bullet points derived from the description context. - Missing Technical Details: Generate an
h2. Technical Detailssection from any code references, file paths, component mentions, or technical context in the description. - Section too short: Expand the existing section with additional relevant detail while preserving the original content.
- AC lacks list items: Restructure the existing AC text into proper bullet points and add additional criteria if needed.
- Vague acceptance criteria: Rewrite vague criteria to be specific and testable (e.g., "works" becomes "returns 200 on valid input").
- Insufficient implementation context: Add implementation pointers -- component names, likely file paths, related features.
- Unclear success conditions: Add explicit done criteria and edge cases.
- Missing Context/Why section: Generate an
-
Present proposed changes to the user: Show the full proposed description, clearly indicating what was added or changed (e.g., mark new sections with a note). Ask the user: "Here is the proposed updated description. Apply this to the Jira issue? (yes/no)"
-
If confirmed: Update the issue description via
editJiraIssue, setting thedescriptionfield to the revised text withcontentFormat: "markdown". -
Re-run validation: After updating, re-run phases 2-4 on the new description to confirm the issue now passes. Report the re-validation results.
-
If declined: Skip the update and proceed to label application and reporting with the original validation result.
Phase 6: Comment on Result
Skip if --dry-run is set.
Post or update a Jira comment reflecting the validation result so the ticket author knows the outcome without running the check themselves.
Step 1: Check for existing automated comment
Fetch the issue with comments included via getJiraIssue and search for one whose body starts with **Automated Readiness Check. Save its comment_id if found.
Step 2: Build comment body
On FAIL: Reuse the same report format defined in Phase 8 (Generate Report), filtered to only show failed and warning checks. Wrap it with:
- Header:
**Automated Readiness Check — FAILED**followed by "Please update the issue description to address the REQUIRED items below." - Footer:
*These checks can also be auto-fixed by running '/jira:ready-to-solve {issue-key} --fix' in Claude Code.* - If
--fixwas attempted but the issue still fails, replace the footer with:*Auto-fix was attempted but could not fully resolve all issues. Please address the remaining items manually.*
On PASS: If an existing automated comment was found in Step 1, use a brief body. If no existing comment was found, skip to Phase 7 — no comment is needed for a first-time PASS.
**Automated Readiness Check — PASSED**
All checks passed. This issue is ready for `/jira:solve`.
Step 3: Post or edit the comment
If an existing automated comment was found (Step 1), the Atlassian Rovo MCP does not support editing comments directly. Post a new comment instead.
Post the comment via addCommentToJiraIssue with the issue key, the comment body, and contentFormat: "markdown".
If no existing comment was found and the verdict is PASS, do nothing.
Phase 7: Apply Jira Label
Skip if --dry-run is set.
- Get current labels from the fetched issue data
- Build the updated label list:
- If PASS: remove
not-ready-to-solve(if present), addready-to-solve - If FAIL: remove
ready-to-solve(if present), addnot-ready-to-solve
- If PASS: remove
- Skip update if labels haven't changed
- Apply via
editJiraIssue, setting thelabelsfield to the updated labels list. Note: Thelabelsfield replaces the entire array, so always include all existing labels plus the new one.
Phase 8: Generate Report
Output format:
## Readiness Validation: {issue-key}
**Summary**: {summary} | **Verdict**: PASS/FAIL
### Deterministic Checks
| Check | Result | Details |
|-------|--------|---------|
| Context section present | PASS/FAIL | {details} |
| Acceptance Criteria present | PASS/FAIL | {details} |
| ... | ... | ... |
### AI Qualitative Assessment
**AC Specificity and Testability**: PASS/FAIL
{reasoning}
**Implementation Context Sufficiency**: PASS/FAIL
{reasoning}
**Clear Success/Failure Conditions**: PASS/FAIL
{reasoning}
### Overall Verdict: PASS/FAIL
{Summary of failures or confirmation that issue is ready}
**Label Applied**: `ready-to-solve` / `not-ready-to-solve` / _(dry run -- no label applied)_
Return Value
- Format: Structured markdown report with deterministic check results table, AI qualitative assessment (3 dimensions with verdicts and reasoning), overall PASS/FAIL verdict, and label applied.
- PASS: All required checks pass, no AI FAIL verdicts.
- FAIL: At least one required check failed or AI flagged a critical issue.
Error Handling
| Error | Handling |
|---|---|
| Issue not found | "Could not find issue {key}. Verify the issue key is correct." |
| MCP unavailable | Display error: "Jira MCP server required. Check plugin README for setup." |
| Python not available | "Python 3 is required. Check: which python3" |
check_sections.py fails | Display script error, proceed with AI-only assessment, note in report |
| Description is null/empty | Automatic FAIL: "Issue has no description. Add Context and Acceptance Criteria sections." |
| Comment post/edit fails | Display warning but still proceed with label application and report. Non-fatal. |
| Label update fails | Display warning but still show report. Non-fatal. |
Description update fails (--fix) | Display error, report original validation result. Non-fatal. |
User declines fix (--fix) | Skip update, proceed with original validation result. |
| Re-validation fails after fix | Report the new failures. The fix improved but did not fully resolve all issues. |
Examples
-
Basic usage:
/jira:ready-to-solve OCPBUGS-12345 -
Dry run (no label changes):
/jira:ready-to-solve OCPBUGS-12345 --dry-run -
Verbose output:
/jira:ready-to-solve OCPBUGS-12345 --verbose -
Validate and fix failing checks:
/jira:ready-to-solve OCPBUGS-12345 --fix
Arguments:
- $1: Jira issue key (required). Examples:
OCPBUGS-12345,HOSTEDCP-999,GCP-456. --dry-run: Optional. Skip label application and comment posting, only report results.--verbose: Optional. Show full per-check details including matched section content.--fix: Optional. When validation fails, generate a revised description fixing the failing checks.
See Also
/openshift-developer:jira-solve-- the skill this validates readiness for
Jira Status Analysis Engine
This skill provides the core analysis logic shared by status-related commands (/jira:status-rollup, /jira:update-weekly-status, and /jira:generate-feature-updates). It handles data collection, activity analysis, and status generation in a unified way.
IMPORTANT FOR AI: This is a procedural skill - when invoked by a command, you should execute the implementation steps defined in this document and its sub-modules. The calling command determines the configuration parameters.
When to Use This Skill
This skill is invoked automatically by:
/jira:status-rollup- Single root issue, outputs as Jira comment/jira:update-weekly-status- Multiple root issues (batch), outputs to Status Summary field/jira:generate-feature-updates- Multiple root issues (batch), outputs as markdown to stdout
Do NOT invoke this skill directly. Use the commands above.
Architecture Overview
For update-weekly-status (Pre-Gathered Data)
┌─────────────────────────────────────────────────────────────────┐
│ /jira:update-weekly-status │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Python Data Gatherer │
│ (gather_status_data.py) │
│ │
│ • Async HTTP requests (aiohttp) │
│ • Jira: issues, descendants, changelogs │
│ • GitHub: PRs via GraphQL (batched) │
│ • Output: .work/weekly-status/{date}/issues/*.json │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Status Analysis Engine │
│ ┌───────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Read JSON │ │ Activity │ │ PR Activity │ │
│ │ (pre-gathered)│─▶│ Analysis │─▶│ (pre-gathered) │ │
│ └───────────────┘ └──────────────────┘ └──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Formatting │ │
│ │ (formatting.md) │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Status Summary field (R/Y/G template) │
└─────────────────────────────────────────────────────────────────┘
For status-rollup (Direct MCP Calls)
┌─────────────────────────────────────────────────────────────────┐
│ /jira:status-rollup │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Status Analysis Engine │
│ (SKILL.md) │
│ ┌───────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Data │ │ Activity │ │ External │ │
│ │ Collection │─▶│ Analysis │─▶│ Links │ │
│ │ (data- │ │ (activity- │ │ (external- │ │
│ │ collection.md)│ │ analysis.md) │ │ links.md) │ │
│ └───────────────┘ └──────────────────┘ └──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Formatting │ │
│ │ (formatting.md) │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Jira comment (markdown) │
└─────────────────────────────────────────────────────────────────┘
Sub-Modules
Read the modules listed below when executing the analysis:
| Module | File | Purpose |
|---|---|---|
| Data Collection | data-collection.md | Reading pre-gathered JSON or fetching via MCP |
| Activity Analysis | activity-analysis.md | Detecting blockers, progress, risks, completion |
| External Links | external-links.md | GitHub PR and GitLab MR integration |
| Formatting | formatting.md | Output templates for different modes |
| Data Gatherer | scripts/gather_status_data.py | Async batch data collection (update-weekly-status) |
| Issue Summarizer | scripts/summarize_issue.py | Compact summaries of pre-gathered issue JSON |
| Issue Triage | scripts/triage_issues.py | Batch triage of pre-gathered issue directories |
| Feature Update Validator | scripts/validate_feature_updates.py | Validate generated feature-update markdown |
Configuration Parameters
Both commands share the same engine with different configuration:
| Parameter | status-rollup | update-weekly-status | generate-feature-updates |
|---|---|---|---|
data_source | MCP API calls | Pre-gathered JSON files | Pre-gathered JSON files |
root_issues | Single issue key | Multiple (from manifest.json) | Multiple (from manifest.json) |
date_range.start | User-specified or issue creation | today - 7 days | today - 7 days |
date_range.end | User-specified or today | today | today |
output_format | markdown_comment | ryg_field (default native ADF); ryg_field_markdown (explicit draft opt-in) | feature_markdown |
output_target | Comment on root issue | Status Summary field | stdout |
external_links | Via gh CLI | Pre-gathered in JSON | Pre-gathered in JSON |
user_review | Yes (before posting comment) | Yes (approve/modify/skip per issue) | Yes (full-section review) |
caching | Temp file for refinement | JSON files in .work/ | JSON files in .work/ |
Hierarchy Traversal
Both commands use the same traversal mechanism via childIssuesOf() JQL:
Root Issue (FEATURE-123)
│
├── Epic 1 (EPIC-456)
│ ├── Story 1.1
│ │ └── Subtask 1.1.1
│ └── Story 1.2
│
└── Epic 2 (EPIC-789)
└── Story 2.1
JQL: issue in childIssuesOf(FEATURE-123)
Returns: ALL descendants at any depth (EPIC-456, Story 1.1, Subtask 1.1.1, Story 1.2, EPIC-789, Story 2.1)
Key benefit: childIssuesOf() is already recursive - a single JQL query returns the entire hierarchy regardless of depth. No manual recursion needed.
The difference between commands is not in traversal but in:
- Data source: update-weekly-status uses pre-gathered JSON; status-rollup uses MCP calls
- Scope: status-rollup analyzes one root; update-weekly-status analyzes many roots
- Filtering: update-weekly-status data is pre-filtered to date range by the Python script
- Aggregation: status-rollup combines all descendants into one summary; update-weekly-status generates per-root summaries
Shared Data Structures
AnalysisConfig
Configuration passed from calling command:
{
"root_issues": ["OCPSTRAT-1234"],
"date_range": {
"start": "2025-01-06",
"end": "2025-01-13"
},
"output_format": "markdown_comment",
"output_target": "comment",
"external_links_enabled": true,
"cache_to_file": true,
"filters": {
"component": null,
"label": null,
"assignees": [],
"excluded_assignees": []
}
}
IssueActivityData
The core data structure for each analyzed issue:
{
"issue_key": "OCPSTRAT-1234",
"summary": "Implement feature X",
"status": "In Progress",
"assignee": "user@example.com",
"issue_type": "Story",
"date_range": {
"start": "2025-01-06",
"end": "2025-01-13"
},
"changelog": {
"status_transitions": [
{"from": "To Do", "to": "In Progress", "date": "2025-01-07", "author": "user@example.com"}
],
"field_changes": [],
"last_status_summary_update": "2025-01-05T10:30:00Z"
},
"comments": [
{"author": "user@example.com", "date": "2025-01-08", "body": "Started work on PR #123", "is_bot": false}
],
"descendants": [
{"key": "OCPSTRAT-1235", "summary": "Sub-task 1", "status": "Done", "updated_in_range": true}
],
"external_links": {
"github_prs": [
{"url": "https://github.com/org/repo/pull/123", "state": "MERGED", "title": "Add feature X"}
],
"gitlab_mrs": []
},
"analysis": {
"health": "green",
"blockers": [],
"risks": [],
"achievements": ["PR #123 merged", "Sub-task 1 completed"],
"in_progress": ["Sub-task 2 under review"],
"metrics": {
"total_descendants": 3,
"completed": 1,
"in_progress": 1,
"blocked": 0,
"completion_percentage": 33
}
}
}
Execution Flow
When a command invokes this skill, follow this sequence:
Step 1: Initialize Configuration
The calling command provides an AnalysisConfig. Parse and validate:
REQUIRED parameters:
- root_issues: Array of issue keys to analyze
- date_range: {start, end} in YYYY-MM-DD format
- output_format: "markdown_comment", "ryg_field", "ryg_field_markdown", or "feature_markdown"
OPTIONAL parameters:
- external_links_enabled: boolean (default: true)
- cache_to_file: boolean (default: false)
- filters: component, label, assignee filters
Step 2: Data Collection
Follow data-collection.md which supports two modes:
Option A: Pre-Gathered Data (update-weekly-status)
Data has already been collected by the Python script (gather_status_data.py):
- Read manifest from
.work/weekly-status/{date}/manifest.json - For each issue, read
.work/weekly-status/{date}/issues/{ISSUE-KEY}.json - Data includes: issue metadata, descendants, changelogs, comments, PRs (all pre-filtered to date range)
Option B: Direct MCP Calls (status-rollup)
-
For each root issue:
- Fetch issue details with
fields=summary,status,assignee,issuelinks,comment,{custom-fields} - Fetch changelog with
expand=changelog
- Fetch issue details with
-
Discover all descendants:
- Use
issue in childIssuesOf({root-issue})to get full hierarchy - Optionally filter by date range:
AND updated >= {start-date} - Use
limit=100(increase if needed for large hierarchies)
- Use
-
For each descendant issue:
- Fetch issue details and changelog
- Track which descendants were updated within date range
-
Build IssueActivityData for root and all descendants
-
Optionally cache to temp file (for refinement workflows)
Step 3: Activity Analysis
Follow activity-analysis.md to:
-
Filter to date range:
- Changelog entries within [start_date, end_date]
- Comments created within [start_date, end_date]
-
Identify key events:
- Status transitions (especially: started, completed, blocked)
- Assignee changes
- Priority/severity changes
-
Analyze comment content:
- Blockers: "blocked", "waiting on", "stuck", "dependency"
- Risks: "risk", "concern", "problem", "at risk"
- Completion: "completed", "done", "merged", "delivered"
- Progress: "started", "working on", "implementing"
-
Determine health status:
- Green: Good progress, PRs merged/in review, no blockers
- Yellow: Minor concerns, slow progress, manageable blockers
- Red: Significant blockers, no progress, major risks
-
Calculate metrics:
- Total/completed/in-progress/blocked descendants
- Completion percentage
Step 4: External Links (if enabled)
Follow external-links.md to:
-
Extract GitHub PR URLs:
- From
issuelinksfield (remote links) - From description and comments (text parsing)
- From descendants' links
- From
-
Fetch PR metadata (if
ghCLI available):gh pr view {PR-NUMBER} --repo {REPO} --json state,updatedAt,mergedAt,title -
Track PR activity:
- PRs merged within date range
- PRs updated within date range
- Open PRs awaiting review
-
Handle GitLab MRs:
- Extract URLs, note for manual checking
- Use
glabif available
Step 5: Format Output
Follow formatting.md to generate output based on output_format:
For markdown_comment (status-rollup):
## Status Rollup From: {start-date} to {end-date}
**Overall Status:** [Health assessment]
**This Week:**
- Completed:
1. [ISSUE-KEY] - [Achievement]
- In Progress:
1. [ISSUE-KEY] - [Current state]
- Blocked:
1. [ISSUE-KEY] - [Blocker reason]
**Next Week:**
- [Planned items]
**Metrics:** X/Y issues complete (Z%)
Note: When posting via addCommentToJiraIssue, always include contentFormat: "markdown".
For ryg_field (update-weekly-status):
The Status Summary field (customfield_10814) requires an ADF JSON document — contentFormat: "markdown" does not auto-convert custom field values. Always construct ADF directly and use contentFormat: "adf". See the ADF template in formatting.md for the exact structure.
Logical content structure:
- Color Status: {Red, Yellow, Green}
- Status summary:
- Thing 1 that happened since last week
- Thing 2 that happened since last week
- Risks:
- Risk 1 (or "None at this time")
For ryg_field_markdown (Markdown draft; explicit opt-in):
* Color Status: {Red, Yellow, Green}
* Status summary:
* Thing 1 that happened since last week
* Thing 2 that happened since last week
* Risks:
* Risk 1 (or "None at this time")
Use native ADF ryg_field by default. This draft requires an external Herald-style
client with verified Markdown-to-ADF conversion; this plugin does not bundle
or perform conversion. A draft string is not a valid direct custom-field value.
Follow the canonical external conversion boundary, source references and pre-write gates;
never improvise conversion or bypass required validation/history support.
The qualified Markdown PR-link rule applies only to this draft, not native ADF.
Qualify only references tied unambiguously to confirmed PR URLs; otherwise retain
the original text exactly verbatim, add no repository or link, and do not guess
or request human input. Follow all draft formatting and selection rules.
For feature_markdown (generate-feature-updates):
- [ISSUE-KEY](https://issues.redhat.com/browse/ISSUE-KEY): Issue summary
- 1-3 sentences of executive prose. No metrics, no R/Y/G.
- [ISSUE-KEY-2](https://issues.redhat.com/browse/ISSUE-KEY-2): Issue summary
- Prose focusing on significant progress, deliveries, blockers, or risks.
Step 6: Return to Calling Command
Return structured result:
{
"issues_analyzed": [...IssueActivityData],
"formatted_outputs": {
"OCPSTRAT-1234": "formatted status text..."
},
"summary": {
"total": 5,
"by_health": {"green": 3, "yellow": 1, "red": 1}
},
"cache_file": "/tmp/jira-status-{issue-id}-{timestamp}.md"
}
The calling command then handles:
- User review and approval workflow
- Posting to Jira (comment or field update)
- Summary report generation
Error Handling
All modules should handle these error cases:
| Error | Handling |
|---|---|
| Issue not found | Log warning, skip issue, continue with others |
| Permission denied | Display clear error, suggest checking MCP config |
| No activity in date range | Generate summary based on current state |
| GitHub CLI not available | Skip PR analysis, note in output |
| Rate limiting | Display error with retry guidance |
| Large hierarchies (100+ issues) | Show progress indicators |
| Missing JSON file | Log warning: "Data file for {key} not found, skipping" |
Performance Considerations
- Use pre-gathered data: For batch operations (update-weekly-status), always use the Python data gatherer
- Minimize API calls: Only fetch fields you need (for status-rollup)
- Fetch changelogs via expand: Use
expand=changelogingetJiraIssuecalls - BFS hierarchy traversal: Use
parent = KEYper level with recursive BFS (Cloud-compatible replacement forchildIssuesOf()) - Cache data: Store in temp file for refinement iterations
- Parallelize: Python script handles parallel fetching; MCP calls can run concurrently
- Limit comments: Truncate comments post-fetch to reduce analysis scope
- Filter early: Data gatherer pre-filters to date range; apply in JQL for MCP calls
Custom Fields
| Field Name | Field ID | Type | Purpose |
|---|---|---|---|
| Status Summary | customfield_10814 | ADF (rich text) | Stores R/Y/G status as ADF JSON; requires contentFormat: "adf" |
Prerequisites
For update-weekly-status
- Python 3.8+ with
aiohttppackage - Environment variables:
JIRA_API_TOKEN: Atlassian API token (create at https://id.atlassian.com/manage-profile/security/api-tokens)JIRA_USERNAME: Atlassian account emailGITHUB_TOKENor authenticatedghCLI
- Jira MCP server configured (for argument resolution)
Check setup:
python3 -c "import aiohttp; print('aiohttp OK')"
echo $JIRA_API_TOKEN
gh auth token
For status-rollup
- Jira MCP server configured and accessible
- GitHub CLI (
gh) installed and authenticated (optional but recommended) - GitLab CLI (
glab) installed and authenticated (optional)
Check for tools:
which gh && gh auth status
which glab && glab auth status # optional
JIRA Bug Validator — Implementation Guide
IMPORTANT FOR AI: This is a procedural skill. Execute each phase in order. Do not skip steps. Do not invent field IDs — use only the documented custom field IDs below.
This skill replicates the validation logic of the jira-lifecycle-plugin (Prow external plugin) that applies the jira/invalid-bug label to PRs in OpenShift repositories.
Custom Field Reference
| Field | Custom Field ID | JQL Name |
|---|---|---|
| Target Version | customfield_10855 | "Target Version" |
| Release Note Text | customfield_10783 | — |
| Release Note Type | customfield_10785 | — |
| Severity | customfield_10840 | — |
The 7 Validation Checks
The jira-lifecycle-plugin runs these checks in order. A bug must pass ALL checks to get jira/valid-bug.
| # | Check | What it validates |
|---|---|---|
| 1 | Bug is open | Status is not "Closed" |
| 2 | Target version matches branch | Bug's Target Version matches the expected version for the PR's base branch |
| 3 | Bug in valid state | Status is one of: NEW, ASSIGNED, POST |
| 4 | Release notes set | Release note text is non-empty and doesn't match the default template, OR release note type is "Release Note Not Required" |
| 5 | Dependent bug states | Each dependent (linked via "Blocks") is in an allowed state |
| 6 | Dependent bug target versions | Each dependent targets an allowed version |
| 7 | Dependents exist | At least one "Blocks" link exists to a bug in the same project |
Checks 5-7 only apply to release branches (release-4.X), not main/master.
Branch-to-Version Mapping
The plugin config follows a mechanical pattern:
Target version (what the bug on the PR's branch must target):
release-4.X→4.X.z(prefix match —4.X.0also accepted)main/master→5.0.0(prefix match —5.0also accepted). Update whenmaintargets a new major version — checkopenshift/release/core-services/jira-lifecycle-plugin/config.yamlfor the current value.
Dependent target version (what the "Blocks" linked bug must target):
release-4.X→4.(X+1).0or4.(X+1).z
Valid states for the bug itself (all branches):
NEW,ASSIGNED,POST
Valid states for dependent bugs (varies by branch — check openshift/release/core-services/jira-lifecycle-plugin/config.yaml for current boundaries):
release-4.22and newer:MODIFIED,ON_QA,VERIFIEDrelease-4.6throughrelease-4.21:VERIFIED,RELEASE PENDING,CLOSED (ERRATA),CLOSED (CURRENT RELEASE),CLOSED (DONE),CLOSED (DONE-ERRATA)
Dependent bug checks (checks 5-7):
- Required for
release-4.Xbranches - NOT required for
main/master(config setsexclude_defaults: true)
Release notes:
- Required by default (
require_release_notes: true) - Default template text (must NOT match this):
"Cause: What actions or circumstances cause this bug to present.\r\nConsequence: What happens when the bug presents.\r\nFix: What was done to fix the bug.\r\nResult: Bug doesn't present anymore."
Prerequisites
ghCLI authenticated with GitHub- Jira MCP server configured (Atlassian Rovo MCP)
cloudId: useredhat.atlassian.net
Detailed Implementation Steps
Phase 1: Resolve Input
Parse the argument to determine input type:
-
PR URL — matches
https://github.com/{org}/{repo}/pull/{number}- Extract org, repo, and PR number from the URL
- Run:
gh pr view {number} --repo {org}/{repo} --json title,baseRefName,state - Extract JIRA key from PR title using regex: first match of
[A-Z]+-[0-9]+(e.g.,OCPBUGS-85778) - Extract base branch from
baseRefName(e.g.,release-4.20,main)
-
PR number — plain integer
- Determine repo from current git remote:
gh repo view --json nameWithOwner -q .nameWithOwner - Then same as PR URL flow above
- Determine repo from current git remote:
-
JIRA key — matches
[A-Z]+-[0-9]+- Require
--branchargument (no PR context to infer branch) - If
--branchnot provided, error: "JIRA key input requires --branch (e.g., --branch release-4.20)"
- Require
Validate the JIRA key project:
- Must be a bug project:
OCPBUGS,DFBUGS, orPROJQUAY - If not, warn: "Project {PROJECT} is not a bug project. The jira-lifecycle-plugin only validates bugs in OCPBUGS, DFBUGS, and PROJQUAY."
Compute expected values from branch:
- Parse branch name to extract version number
- Compute
expected_target_version,expected_dependent_versions,valid_states,dependent_valid_states,dependents_requiredusing the mapping above
Phase 2: Gather Data
Fetch the primary bug:
Use mcp__atlassian__getJiraIssue:
cloudId:redhat.atlassian.netissueIdOrKey: the JIRA keyfields:["summary", "status", "issuetype", "fixVersions", "issuelinks", "customfield_10855", "customfield_10783", "customfield_10785", "customfield_10840", "labels", "components"]responseContentFormat:markdown
Extract key data from response:
status.name— bug status (e.g., "New", "Verified")customfield_10855— Target Version array (each entry has.name)customfield_10783— Release Note Text (string or ADF doc)customfield_10785— Release Note Type (object with.value)issuelinks— array of issue links
Find dependent bugs:
Filter issuelinks for links where:
- Link type name is
"Blocks"AND direction isoutwardIssue(this bug blocks the dependent) - The linked issue's project key matches the original bug's project (e.g., both are
OCPBUGS-*)
For each dependent found:
- Record the dependent's key, status, and priority from the link data
- If the link data doesn't include Target Version, fetch the dependent with
getJiraIssue:fields:["summary", "status", "customfield_10855", "fixVersions"]
Phase 3: Validate
Run each check and record the result:
results = []
Check 1: Bug is open
- PASS if
status.nameis NOT "Closed" - FAIL if
status.nameis "Closed" - Pass message:
"bug is open, matching expected state (open)" - Fail message:
"bug is closed, expected it to be open"
Check 2: Target version matches branch
- Get target versions from
customfield_10855(array) - FAIL if no target version is set:
"expected the bug to target the '{expected}' version, but no target version was set" - FAIL if multiple target versions are set (only one allowed)
- PASS if exactly one target version and its
.namestarts with the expected prefix (e.g.,"4.20"forrelease-4.20) - FAIL otherwise:
"expected the bug to target either version '{expected}' or 'openshift-{expected}', but it targets '{actual}' instead"
Check 3: Bug in valid state
- PASS if
status.name(uppercased) is in["NEW", "ASSIGNED", "POST"] - FAIL otherwise:
"bug is in state {actual}, which is not one of the valid states (NEW, ASSIGNED, POST)"
Check 4: Release notes
- Get release note text from
customfield_10783- If it's an ADF document, extract the plain text content
- If it's a string, use directly
- Get release note type from
customfield_10785 - PASS if release note type
.valueequals"Release Note Not Required" - PASS if release note text is non-empty AND does NOT start with
"Cause: What actions or circumstances" - FAIL otherwise:
"release note text must be set and not match the template OR release note type must be set to 'Release Note Not Required'"
Check 5: Dependent bug states (skip if dependents_required is false)
- For each dependent bug found via "Blocks" links:
- PASS if dependent's
status.name(uppercased) is in the alloweddependent_valid_stateslist - FAIL otherwise:
"expected dependent Jira Issue {key} to be in one of the following states: {allowed}, but it is {actual} instead"
- PASS if dependent's
- If no dependents exist, this check is implicitly skipped (check 7 handles that)
Check 6: Dependent bug target versions (skip if dependents_required is false)
- For each dependent bug:
- Get its Target Version from
customfield_10855 - PASS if target version starts with one of the
expected_dependent_versionsprefixes - FAIL otherwise:
"expected dependent Jira Issue {key} to target a version in {allowed}, but it targets '{actual}' instead"
- Get its Target Version from
Check 7: Dependents exist (skip if dependents_required is false)
- PASS if at least one "Blocks" link exists to a bug in the same project
- FAIL otherwise:
"expected Jira Issue to depend on a bug targeting a version in {allowed} and in one of the following states: {allowed_states}, but no dependents were found"
Phase 4: Report
Render results as a markdown table:
## Validating {JIRA_KEY} against branch {BRANCH}
**Bug**: {summary}
**Status**: {status} | **Target Version**: {target_version} | **Project**: {project}
| # | Check | Expected | Actual | Result |
|---|--------------------------------|-------------------------|--------------------| -------|
| 1 | Bug is open | Open | {status} | {P/F} |
| 2 | Target version | {expected_tv} | {actual_tv} | {P/F} |
| 3 | Valid state | NEW/ASSIGNED/POST | {status} | {P/F} |
| 4 | Release notes | Set (not template) | {actual_rn} | {P/F} |
| 5 | Dependent bug states | {allowed_states} | {actual_dep_state} | {P/F} |
| 6 | Dependent bug target version | {allowed_dep_tv} | {actual_dep_tv} | {P/F} |
| 7 | Dependents exist | At least one | {count} found | {P/F} |
Result: {N} of 7 checks passed
For checks that were skipped (main branch, no dependents required), show SKIP in the Result column.
For each failure, list the specific fix instruction:
### Fixes needed
1. **Target version**: Set Target Version to `{expected}` (currently `{actual}`)
2. **Status**: Transition to NEW, ASSIGNED, or POST (currently `{actual}`)
3. **Release notes**: Set release note text or set Release Note Type to "Release Note Not Required"
4. **Dependents**: Create or link a bug in {PROJECT} targeting `{expected_dep_version}`
If all checks pass:
All 7 checks passed. If the PR still shows `jira/invalid-bug`, comment `/jira refresh` on the PR.
Phase 5: Offer Fixes
After reporting, offer to fix each failing check. List the fixes and ask for confirmation before proceeding.
Fix: Target version (checks 2, 6)
- Resolve the version ID: use
mcp__atlassian__getJiraIssueTypeMetaWithFieldswithprojectIdOrKey: {PROJECT},issueTypeIdfrom the bug'sissuetype.id, andrequiredFieldsOnly: false - Find
customfield_10855in the response fields — itsallowedValuesarray contains all available versions. Match the entry whose.nameequals the expected version string (e.g.,4.20.z) and extract its.id - Update:
mcp__atlassian__editJiraIssuewithfields: {"customfield_10855": [{"id": "{version_id}"}]}
Fix: Status (checks 1, 3)
- Get available transitions:
mcp__atlassian__getTransitionsForJiraIssue - Find transition to a valid state (prefer "New" or "POST")
- Transition:
mcp__atlassian__transitionJiraIssuewith the transition ID
Fix: Release notes (check 4)
- Ask the user for release note text. Suggest format:
Cause: {what causes the bug} Consequence: {what happens} Fix: {what was done} Result: {the fix resolves it} - Update:
mcp__atlassian__editJiraIssuewithfields: {"customfield_10783": "{text}"} - Alternative: if user wants to skip release notes, set release note type:
fields: {"customfield_10785": {"value": "Release Note Not Required"}}
Fix: Missing dependents (check 7)
- Check if a "Blocks" linked dependent already exists in the issue's
issuelinks(same project, outward direction) - If no dependent exists, offer to create one:
- Create a new bug in the same project with:
- Same summary (prefixed with branch info if needed)
- Target Version set to the expected dependent version
- Link with a "Blocks" relationship:
mcp__atlassian__createIssueLinkwithtype: "Blocks",inwardIssue: {original_bug},outwardIssue: {new_bug}(original bug blocks the new dependent) - Use
mcp__atlassian__createJiraIssuethenmcp__atlassian__createIssueLink
- Create a new bug in the same project with:
- If a dependent exists but targets wrong version or is in wrong state, offer to fix it
Fix: Dependent bug state (check 5)
- For each dependent in wrong state:
- Get transitions:
mcp__atlassian__getTransitionsForJiraIssuefor the dependent - Find transition to an allowed state
- Transition:
mcp__atlassian__transitionJiraIssue
- Get transitions:
After all fixes applied:
- Re-run all 7 checks to confirm everything passes
- Display updated results table
- Remind user: "Comment
/jira refreshon the PR to have the bot re-validate."
Error Handling
| Error | Handling |
|---|---|
| PR not found | Display error with PR URL, suggest checking the URL |
| No JIRA key in PR title | Display the PR title, explain the expected format: {JIRA-KEY}: description |
| JIRA issue not found | Check if key is correct, check project access |
| MCP tool unavailable | Fall back to gh CLI for GitHub data; for JIRA, display manual fix instructions |
| Branch not recognized | Warn that branch {name} doesn't match expected patterns, ask for --branch override |
| Version ID not found | Display the expected version string, instruct user to set it manually in JIRA |
| Transition not available | List available transitions, explain which one is needed and why it might be blocked |
Notes
- The jira-lifecycle-plugin config lives at
openshift/release/core-services/jira-lifecycle-plugin/config.yaml. If validation rules change, update the mapping in this skill. - If a human manually adds
jira/valid-bug, the bot will not remove it. - For cherry-pick PRs, the plugin may auto-clone the parent JIRA bug. Check for existing "Blocks" links before creating new dependents.
- The
mainbranch usesexclude_defaults: true, which disables dependent bug checks (5-7).
Commands 17
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 uses direct REST API calls (via curl) instead of MCP tools because MCP has performance issues when fetching large datasets — tool result size limits cause 413 errors, and processing hundreds of tickets through MCP commands creates excessive context usage.
JIRA credentials must be set as environment variables:
| Variable | Description |
|---|---|
JIRA_URL | Jira instance URL (e.g., https://redhat.atlassian.net) |
JIRA_USERNAME | Atlassian account email address |
JIRA_API_TOKEN | Atlassian API token from Atlassian API tokens |
Verify Configuration
To verify your credentials work, test with a curl call (the same auth method this command uses):
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Basic $(printf '%s:%s' "$JIRA_USERNAME" "$JIRA_API_TOKEN" | base64 | tr -d '\n')" "$JIRA_URL/rest/api/3/myself"
- 200: Authentication works.
- 401/403: Check your
JIRA_API_TOKENandJIRA_USERNAMEare correct. To regenerate your token, visit Atlassian API tokens. - Connection error or empty
JIRA_URL: Verify all three environment variables are set.
Implementation
The command executes the following workflow:
-
Check Required Environment Variables
- Verify
JIRA_URL,JIRA_USERNAME, andJIRA_API_TOKENare set:: "${JIRA_URL:?Error: JIRA_URL not set}" : "${JIRA_USERNAME:?Error: JIRA_USERNAME not set}" : "${JIRA_API_TOKEN:?Error: JIRA_API_TOKEN not set}" AUTH_TOKEN="$JIRA_API_TOKEN" - If any required variable is missing, display error:
Error: JIRA credentials not configured. This command requires environment variables: JIRA_URL, JIRA_USERNAME, JIRA_API_TOKEN. See Prerequisites section for setup instructions.
- Verify
-
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}/
-
Construct JQL Query
- Build base JQL query:
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
- Build base JQL query:
-
Fetch All Backlog Tickets Using curl with Pagination
Fetch Strategy:
- Fetch 1000 tickets per request (JIRA's maximum
maxResultsvalue) - Use pagination (
startAtparameter) to fetch all tickets - Save each batch directly to disk to avoid memory issues
- Continue until all tickets are fetched
Authentication:
- Use Basic Auth with
JIRA_USERNAME:JIRA_API_TOKEN(base64-encoded) for Atlassian Cloud
Important API Details:
- Use POST
/rest/api/3/search/jqlendpoint with a JSON body containingjql,fields, andmaxResults - Use
Authorization: Basic <base64(username:token)>header for authentication - Check HTTP response code to detect authentication failures
Batch Processing Loop:
START_AT=0 BATCH_NUM=0 TOTAL_FETCHED=0 while true; do # Construct API URL for POST search API_URL="${JIRA_URL}/rest/api/3/search/jql" # Build JSON body for POST request JSON_BODY=$(jq -n \ --arg jql "$JQL" \ --argjson startAt "$START_AT" \ --argjson maxResults 1000 \ '{jql: $jql, startAt: $startAt, maxResults: $maxResults, fields: ["summary","status","priority","assignee","reporter","created","updated","description","labels","components","watches","comment"]}') # Fetch batch using curl with Basic authentication (POST) AUTH_HEADER=$(printf '%s:%s' "$JIRA_USERNAME" "$AUTH_TOKEN" | base64 | tr -d '\n') HTTP_CODE=$(curl -s -w "%{http_code}" \ -X POST \ -o "batch-${BATCH_NUM}.json" \ -H "Authorization: Basic ${AUTH_HEADER}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d "$JSON_BODY" \ "${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
- Fetch 1000 tickets per request (JIRA's maximum
-
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:
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:
- All batch files:
-
.work/jira-backlog/{project-key}/filtered.json- All filtered tickets grouped by priority -
.work/jira-backlog/{project-key}/stats.json- Priority distribution statisticsRun the script:
python .work/jira-backlog/${PROJECT_KEY}/process_batches.py
-
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):
- Recency: Fresher tickets (< 60 days) strongly preferred to ensure relevance
- Clarity: Clear reproduction steps, well-defined scope, available resources (must-gather, logs)
- Impact: User-facing issues, customer cases, or significant system problems
- 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
- Read filtered tickets from
-
Format Output Report Generate a formatted report organized by priority:
# 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 -
Display Report to User
- Show the formatted report
- Provide guidance on next steps
- Suggest using
/jira:groomingfor tickets lacking clarity - Suggest using
/jira:solveto start working on selected ticket
-
Save Report (Optional)
- Offer to save report to
.work/jira-backlog/{project-key}-{timestamp}.md - Useful for tracking backlog trends over time
- Offer to save report to
Error Handling:
- Missing environment variables: If
JIRA_URL,JIRA_USERNAME, orJIRA_API_TOKENare not set, display:Error: JIRA credentials not configured. This command requires environment variables: JIRA_URL, JIRA_USERNAME, JIRA_API_TOKEN. See Prerequisites section for setup instructions. - Authentication failure: If curl returns 401/403, display:
Error: JIRA authentication failed (HTTP 401/403) Please verify your JIRA credentials: 1. Check that JIRA_API_TOKEN is correct and not expired 2. Verify JIRA_USERNAME matches your Atlassian account email 3. Ensure JIRA_URL is correct (e.g., https://redhat.atlassian.net) 4. Test authentication: curl -H "Authorization: Basic $(printf '%s:%s' "$JIRA_USERNAME" "$JIRA_API_TOKEN" | base64 | tr -d '\n')" $JIRA_URL/rest/api/3/myself To regenerate your token, visit: https://id.atlassian.com/manage-profile/security/api-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 jqon macOS,apt-get install jqon 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}.mdcontaining the full report - Summary Statistics: Count of available tickets per priority level
Examples
Note: All examples require JIRA_URL, JIRA_USERNAME, and JIRA_API_TOKEN environment variables to be set (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.
-
Find unassigned tickets in OCPBUGS project:
/jira:backlog OCPBUGSOutput: 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
-
Find stale tickets with custom inactivity threshold:
/jira:backlog OCPBUGS --days-inactive 14Output: Report showing tickets with no activity for 14+ days, 2 per priority level
-
Find tickets assigned to a specific user that are stale:
/jira:backlog OCPBUGS --assignee jsmith --days-inactive 30Output: Report showing tickets assigned to jsmith with 30+ days of inactivity, 2 per priority level
-
Find tickets in Hypershift project:
/jira:backlog HYPEOutput: Analyzes backlog and shows best 2 tickets from each priority in HYPE project
-
Find tickets in CNV project:
/jira:backlog CNVOutput: 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 jsmithfinds 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 14finds tickets with 14+ days of no activity
Name
jira:batch-categorize-activity-types
Synopsis
/jira:batch-categorize-activity-types <project-key> [--type Epic] [--limit 100] [--jql 'AND status != Closed'] [--dry-run]
Description
Fetches all Jira issues in a project that have no Activity Type set, categorizes each into one of six Sankey capacity allocation categories, validates results, generates a report, and (with user approval) applies the updates back to Jira.
Classification logic is shared with /jira:categorize-activity-type via the categorize-activity-types skill.
Implementation
Delegate to the categorize-activity-types skill in batch mode. The skill handles all phases: gather, classify, validate, report, apply, and iterate.
See skills/categorize-activity-types/SKILL.md for the full workflow.
If --dry-run is set, instruct the skill to skip Phase 4 (apply).
Arguments
-
$1 - project-key (required)
- Jira project key (e.g., OCM, ARO, ROX)
-
--type <issue-type> (optional, default: Epic)
- Issue type to filter. Supports: Epic, Story, Task, Bug, etc.
-
--limit <number> (optional, default: 100)
- Maximum number of issues to fetch and classify per batch
-
--jql <conditions> (optional)
- Additional JQL conditions appended to the base query
- Example:
'AND resolved >= "2025-01-01"' - Example:
'AND status != Closed'
-
--dry-run (optional)
- Run classification and generate report without applying updates to Jira
Examples
-
Classify all Epics in OCM:
/jira:batch-categorize-activity-types OCM -
Classify Stories instead of Epics:
/jira:batch-categorize-activity-types ARO --type Story -
Add JQL filter:
/jira:batch-categorize-activity-types OCM --jql 'AND resolved >= "2025-01-01"' -
Dry run (classify and report, don't apply):
/jira:batch-categorize-activity-types ROX --dry-run
Return Value
Format: Markdown report with distribution summary, per-category issue tables with Jira links, and apply/skip status.
Artifacts written to .work/activity-type-classifier/:
issues.json— Raw fetched issue dataclassifications.json— Classification results with confidence and reasoningreport.md— Formatted markdown report
See Also
jira:categorize-activity-type- Single-issue classification (shares the same classification skill)
Notes
- Prerequisites:
jq(for validation script), Python 3 (for report generation)
Name
jira:catch-me-up
Synopsis
/jira:catch-me-up [14] [--days 7] [--no-cache]
Description
Fetches recent activity on Jira issues where you are assignee or watcher, then classifies each event into three tiers: needs attention, unsure, or noise. Uses a map/reduce approach — fast model classifies batches in parallel, then a review pass catches cross-event patterns.
Prerequisites
JIRA_API_TOKENandJIRA_USERNAMEenvironment variables setuv(astral.sh/uv) — the gather script is run viauv run --with aiohttpJIRA_URLdefaults tohttps://redhat.atlassian.net
Implementation
Step 1: Parse arguments
Default --days to 7 if not specified. The user may pass a number directly (e.g., /jira:catch-me-up 14 means 14 days).
Step 2: Check subagent permissions
Read .claude/settings.local.json. If the file exists, check whether Read(.work/catch-me-up/**) is in the permissions.allow array.
If present, continue silently.
If missing (or the file doesn't exist), append Read(.work/catch-me-up/**) to the permissions.allow array. Preserve all existing content — only add this one entry. Tell the user:
Added
Read(.work/catch-me-up/**)to.claude/settings.local.json— subagents need this to read batch files.
Step 3: Gather data
Run the data gathering script. Use uv run to handle the aiohttp dependency automatically.
uv run --with aiohttp plugins/jira/skills/catch-me-up/scripts/gather.py --days <N> -v --output-dir .work/catch-me-up/runs
If the user passed --no-cache, append --no-cache to the command above.
Check the output stats. If there are 0 events, tell the user and stop. Read the output file path from stderr.
Step 4: Split into batches
python3 plugins/jira/skills/catch-me-up/scripts/split_batches.py .work/catch-me-up/runs/<date>-<days>d/events.json 5
This creates batch files and prints a JSON manifest with batch_files paths.
Step 5: Classify batches in parallel
Spawn one Agent per batch file, all in a single message so they run in parallel. Use model: "haiku" for each agent.
Each agent's prompt must be exactly:
You are classifying Jira activity events for triage. The user is <JIRA_USERNAME> — they are the assignee or watcher on these issues. Any events authored by the user themselves should be tier 3 (noise) since they already know about their own actions.
Read <batch_file_path>. The file contains a batch of events plus a `context` field showing author/field frequency counts and the user's Jira username (`jira_username`).
Classify each event into one of three tiers:
**Tier 1 — Needs attention:** Someone @mentions the user, asks them a question, assigns something to them, raises a blocker on their issue, or posts a substantive comment on their bug. Human priority/severity escalations.
**Tier 2 — Unsure:** Ambiguous — could be signal or noise. Humans doing mechanical/formulaic work, field changes that might imply a decision, bot actions that might carry meaning.
**Tier 3 — Noise:** Mechanical process work, formulaic status updates, link churn, release process bookkeeping, bot-like behavior regardless of actor.
Output ONLY a JSON array. Each element must have exactly these fields:
{
"tier": 1,
"date": "2026-04-17",
"issue_key": "OCPBUGS-12345",
"title": "the Jira issue title, copied verbatim from the event data",
"author": "Person Name",
"summary": "one-line description of what happened and why it's in this tier"
}
List every event. Do not skip, summarize, or group.
Step 6: Collect and merge results
Parse the JSON arrays returned by each agent. Merge into a single list. If any agent returned non-JSON output, extract the JSON portion.
Group by tier:
- Count of tier 1, tier 2, tier 3 events
- Sort tier 1 and tier 2 by date descending
- Condense tier 3 into one line per event:
ISSUE-KEY | author | summary(no full JSON, just scannable text)
Step 7: Review pass
Spawn a single review Agent with model: "opus" to synthesize per-event classifications into per-issue narratives.
You are reviewing classified Jira events. The initial classification was done per-batch, per-event. Your job is to synthesize these into per-issue narratives grouped by tier.
Tier 1 and tier 2 events (full detail):
<paste merged tier 1 and tier 2 as JSON>
Tier 3 events (condensed — scan for false negatives):
<for each tier 3 event, one line: "ISSUE-KEY | author | summary">
Your tasks:
1. Group events by issue key. For each issue, write a summary of what happened and what (if anything) needs the user's action. Default to 1-2 sentences — only go longer when the situation is genuinely complex (e.g., multiple people disagreeing, a subtle root cause, a decision with non-obvious tradeoffs). Omit triage churn, field-change play-by-play, and intermediate states that were superseded. Name people only when the user needs to respond to them specifically.
2. Assign each issue (not event) a tier. An issue is tier 1 if any of its events need the user's attention. An issue is tier 2 if the activity is ambiguous but worth knowing about.
3. Demote to tier 3: authors doing purely mechanical work across many issues, duplicate events (e.g., status change that just echoes a comment), superseded actions (e.g., priority escalation reversed the next day).
4. Promote from tier 3: scan the condensed tier 3 list for events that look like they were wrongly classified as noise — substantive comments, @mentions, or escalations that Haiku missed.
Output JSON:
{
"tier_1": [
{
"issue_key": "OCPBUGS-12345",
"title": "Jira issue title from the classified events",
"summary": "What happened and why it matters. 1-2 sentences unless complexity demands more.",
"action": "One concrete next step."
}
],
"tier_2": [
{
"issue_key": "OCPBUGS-12345",
"title": "Jira issue title from the classified events",
"summary": "What happened. 1-2 sentences.",
"reason": "Why worth a glance"
}
],
"demoted_to_tier_3": ["OCPBUGS-xxxxx: reason", ...]
}
Step 8: Present results
Display to the user in this format:
## Needs your attention (N issues)
### ISSUE-KEY: issue summary
narrative — what happened, who's involved, the arc
→ **Action:** what you should do
### ISSUE-KEY: issue summary
...
## Worth a glance (N issues)
### ISSUE-KEY: issue summary
narrative
→ reason it's ambiguous
## Filtered out (N events across M issues)
Summary by category, e.g.:
23 link changes (various contributors)
12 status transitions
8 field housekeeping
Step 9: Save classified output
Write the full classification (all three tiers with individual events) to .work/catch-me-up/runs/<date>-<days>d/classified.json for later inspection.
Name
jira:categorize-activity-type
Synopsis
/jira:categorize-activity-type <issue-key> [--auto-apply]
Description
Analyzes a single JIRA ticket and assigns an Activity Type category based on ticket content, issue type, labels, and parent context. Classification logic is shared with /jira:batch-categorize-activity-types via the categorize-activity-types skill.
Implementation
Phase 1: Fetch Ticket Data
Use MCP to fetch the issue by key. Delegate to the categorize-activity-types skill in single-issue mode.
See skills/categorize-activity-types/SKILL.md for the full classification methodology, including fields to fetch, classification rules, validation, and reporting.
Phase 2: Apply Update (Conditional)
Auto-apply logic:
-
If
--auto-applyflag present AND confidence is High:- Automatically update Activity Type field
- Display confirmation to user
-
Otherwise (no flag OR confidence is Medium/Low):
- Present suggestion to user
- Ask for confirmation before applying
- If user confirms, proceed with update
- If user declines, exit without changes
Arguments
-
$1 - issue-key (required)
- JIRA issue key to categorize
- Format: PROJECT-NUMBER (e.g., ROX-12345, OCPBUGS-67890)
-
--auto-apply (optional)
- Automatically apply Activity Type when confidence is High
- Without this flag, always prompts user for confirmation
- Medium/Low confidence always requires manual confirmation
Examples
-
Basic categorization (manual confirmation):
/jira:categorize-activity-type ROX-12345 -
Auto-apply for high confidence:
/jira:categorize-activity-type ROX-12345 --auto-apply -
Process security vulnerability:
/jira:categorize-activity-type ROX-28072 --auto-applyExpected: Issue Type = Vulnerability -> "Security & Compliance" (High confidence, auto-applied)
Return Value
Format: Classification result with confidence level and reasoning, plus optional Jira update confirmation.
Artifacts written to .work/activity-type-classifier/:
classifications.json— 1-entry JSON array with the classification resultreport.md— Formatted markdown report
See Also
jira:batch-categorize-activity-types- Batch classification (shares the same classification skill)
Name
jira:clone-from-github
Synopsis
/jira:clone-from-github <issue-number> [issue-number...] [options]
Description
The jira:clone-from-github command clones one or more GitHub issues to Jira, preserving the original issue content and establishing a link between the GitHub and Jira issues. This command is useful for:
- Migrating GitHub issues to Jira for project tracking
- Creating Jira tickets that track upstream GitHub issues
- Maintaining synchronization between GitHub and Jira workflows
- Bulk importing GitHub issues into Jira projects
The command uses the gh2jira utility to perform the cloning operation. Use /jira:setup-gh2jira to install and configure gh2jira if you haven't already.
Implementation
📋 Phase 1: Validate Prerequisites and Locate Installation
Check that the gh2jira utility is available and configured:
-
Locate gh2jira binary and installation directory:
# Find the gh2jira binary GH2JIRA_BIN=$(which gh2jira 2>/dev/null) if [ -z "$GH2JIRA_BIN" ]; then echo "gh2jira not found. Run /jira:setup-gh2jira to install." exit 1 fi # If it's a symlink, resolve it to find the actual installation if [ -L "$GH2JIRA_BIN" ]; then GH2JIRA_BIN=$(readlink "$GH2JIRA_BIN") fi # Get the directory containing the gh2jira binary GH2JIRA_DIR=$(dirname "$GH2JIRA_BIN") echo "Found gh2jira at: $GH2JIRA_DIR" -
Verify configuration files exist in installation directory:
cd "$GH2JIRA_DIR" || exit 1 # Check for tokenstore.yaml if [ ! -f "tokenstore.yaml" ]; then echo "tokenstore.yaml not found in $GH2JIRA_DIR" echo "Run /jira:setup-gh2jira to configure authentication." exit 1 fi # Check for profiles.yaml (optional) if [ -f "profiles.yaml" ]; then echo "Found profiles.yaml" fi -
Verify tokens are configured:
- Check that
tokenstore.yamlcontains actual tokens (not placeholder values) - GitHub token should not contain "YOUR_GITHUB_TOKEN"
- Jira token should not contain "YOUR_JIRA_API_TOKEN"
- Check that
IMPORTANT: All gh2jira commands MUST be executed from the $GH2JIRA_DIR directory so that gh2jira can locate and load its configuration files.
If prerequisites are missing:
- Inform user about missing requirements
- Provide instructions from gh2jira README on setting up:
- GitHub Personal Access Token (scope: public_repo, read:project)
- Jira API Token
- Creating tokenstore.yaml file
🔍 Phase 2: Parse Arguments
Parse command arguments:
Required arguments:
issue-number: One or more GitHub issue numbers (e.g.,123,456 789)
Optional flags:
--github-project <org/repo>: GitHub project (e.g.,operator-framework/operator-lifecycle-manager)- Can also use profile name if configured in profiles.yaml
--jira-project <key>: Target Jira project (e.g.,OCPBUGS,CNTRLPLANE)--profile <name>: Use named profile from profiles.yaml--dryrun: Show what would be created without actually creating Jira issues
Argument validation:
- At least one issue number must be provided
- Issue numbers must be numeric
- If
--profileis not used,--github-projectand--jira-projectare typically required
🔧 Phase 3: Build gh2jira Command
Construct the gh2jira clone command based on provided arguments:
Basic command structure:
gh2jira clone <issue-number> [issue-number...] [flags]
Flag mapping:
--github-project→--github-project org/repo--jira-project→--jira-project KEY--profile→--profile-name name--dryrun→--dryrun
Example commands:
# Using profile
gh2jira clone 123 456 --profile-name my-profile --dryrun
# Using explicit projects
gh2jira clone 123 --github-project operator-framework/olm --jira-project OCPBUGS
# Multiple issues with dryrun
gh2jira clone 100 101 102 --profile-name default --dryrun
▶️ Phase 4: Execute Clone Operation
-
Run the gh2jira command from installation directory:
# IMPORTANT: Change to gh2jira installation directory cd "$GH2JIRA_DIR" || exit 1 # Execute the gh2jira clone command gh2jira clone <issue-number> [issue-number...] [flags]- Execute the constructed command from
$GH2JIRA_DIR - Capture stdout and stderr
- Monitor exit code
- Execute the constructed command from
-
Handle dryrun output:
- If
--dryrunwas specified, display the Jira issue that would be created - Show issue title, description, and fields
- Ask user if they want to proceed with actual creation
- If
-
Handle actual clone output:
- Display progress for each issue being cloned
- Show created Jira issue keys and URLs
- Report any errors or failures
Note: Running from $GH2JIRA_DIR ensures that gh2jira can locate tokenstore.yaml, profiles.yaml, and workflows.yaml in its working directory.
📊 Phase 5: Display Results
Format and display results to the user:
Success output (per issue):
✓ Cloned GitHub issue #123 → OCPBUGS-4567
Title: <issue title>
URL: https://redhat.atlassian.net/browse/OCPBUGS-4567
GitHub link: https://github.com/org/repo/issues/123
Dryrun output:
[DRYRUN] Would create Jira issue from GitHub #123:
Project: OCPBUGS
Type: Bug
Title: <issue title>
Description:
<formatted description with GitHub link>
Labels: <labels>
Error output:
✗ Failed to clone GitHub issue #123
Error: <error message>
Suggestions:
- Verify GitHub issue exists and is accessible
- Check authentication tokens are valid
- Ensure Jira project accepts this issue type
Summary:
Cloned 3 of 5 GitHub issues successfully:
✓ #123 → OCPBUGS-4567
✓ #124 → OCPBUGS-4568
✓ #125 → OCPBUGS-4569
✗ #126 - Issue not found
✗ #127 - Permission denied
Return Value
- Success: List of created Jira issue keys with URLs
- Dryrun: Preview of issues that would be created
- Error: Error messages with suggestions for resolution
Examples
Example 1: Clone single issue using profile
/jira:clone-from-github 123 --profile olm-project
Uses the olm-project profile configuration to clone GitHub issue #123.
Example 2: Clone multiple issues with explicit projects
/jira:clone-from-github 456 789 --github-project operator-framework/operator-lifecycle-manager --jira-project OCPBUGS
Clones GitHub issues #456 and #789 from the specified GitHub project to OCPBUGS.
Example 3: Dryrun before cloning
/jira:clone-from-github 100 --profile default --dryrun
Shows what Jira issue would be created without actually creating it.
Example 4: Clone with explicit configuration
/jira:clone-from-github 200 201 202 --github-project openshift/origin --jira-project OCPBUGS
Clones three GitHub issues from openshift/origin to OCPBUGS project.
Arguments
-
$1+ – issue-number(s) (required) One or more GitHub issue numbers to clone. Can be space-separated. Example:
123or123 456 789 -
--github-project (optional) GitHub project in format
org/repo(e.g.,operator-framework/operator-lifecycle-manager). Not required if: using--profile -
--jira-project (optional) Target Jira project key (e.g.,
OCPBUGS,CNTRLPLANE). Not required if: using--profile -
--profile (optional) Named profile from profiles.yaml that contains GitHub and Jira project mappings. Example:
--profile olm-project -
--dryrun (optional) Preview what would be created without actually creating Jira issues. Recommended for first-time use or when cloning many issues.
Configuration
TokenStore Setup
The command requires a tokenstore.yaml file in the gh2jira directory:
schema: gh2jira.tokenstore
authTokens:
jira: <your-jira-pat>
github: <your-github-pat>
Creating tokens:
- GitHub: Personal Access Token with scopes
public_repoandread:project- Create at: https://github.com/settings/tokens
- Jira: Personal Access Token
- Create at: https://id.atlassian.com/manage-profile/security/api-tokens (for Jira Cloud)
- Or follow your organization's Jira PAT creation process
Profiles Setup (Optional)
Create profiles.yaml in the gh2jira directory for easier management:
profiles:
- description: OLM Project
githubConfig:
project: operator-framework/operator-lifecycle-manager
jiraConfig:
project: OCPBUGS
tokenStore: tokenstore.yaml
- description: OpenShift Origin
githubConfig:
project: openshift/origin
jiraConfig:
project: OCPBUGS
Then use with --profile "OLM Project" instead of specifying projects each time.
Workflows Configuration
The gh2jira utility uses workflows.yaml for state mapping. The default configuration is:
schema: gh2jira.workflows
name: jira
mappings:
- ghstate: "open"
jstates:
- "To Do"
- "In Progress"
- "New"
- "Code Review"
- ghstate: "closed"
jstates:
- "Done"
- "Dev Complete"
- "Release Pending"
This is used by the reconcile command but may affect clone behavior.
Error Handling
gh2jira Binary Not Found
Scenario: The gh2jira binary doesn't exist.
Action:
The gh2jira utility is not installed.
Please run /jira:setup-gh2jira to install and configure gh2jira.
Missing TokenStore
Scenario: tokenstore.yaml doesn't exist. Action:
TokenStore configuration not found.
Please run /jira:setup-gh2jira to configure gh2jira with your GitHub and Jira tokens.
Alternatively, you can manually create the tokenstore.yaml file:
1. Create GitHub Personal Access Token:
- Go to: https://github.com/settings/tokens
- Scopes: public_repo, read:project
2. Create Jira API Token:
- Follow your organization's process
3. Create tokenstore.yaml in the gh2jira installation directory:
cat > tokenstore.yaml << 'EOF'
schema: gh2jira.tokenstore
authTokens:
jira: YOUR_JIRA_API_TOKEN
github: YOUR_GITHUB_TOKEN
EOF
GitHub Issue Not Found
Scenario: Specified GitHub issue doesn't exist or is inaccessible. Action:
GitHub issue #999 not found in operator-framework/operator-lifecycle-manager
Possible causes:
- Issue number is incorrect
- Issue is in a different repository
- Repository is private and token lacks access
- Issue has been deleted
Please verify:
- Issue exists at: https://github.com/operator-framework/operator-lifecycle-manager/issues/999
- Your GitHub token has access to this repository
Jira Project Not Found
Scenario: Target Jira project doesn't exist or user lacks access. Action:
Jira project "INVALIDPROJ" not found or inaccessible
Possible causes:
- Project key is incorrect
- You don't have permission to create issues in this project
- Project doesn't exist in your Jira instance
Please verify:
- Project exists in Jira
- You have "Create Issues" permission
- Project key is correct (usually all caps, e.g., OCPBUGS)
Authentication Failure
Scenario: GitHub or Jira tokens are invalid or expired. Action:
Authentication failed for GitHub/Jira
Please check your tokens in tokenstore.yaml:
- Verify tokens are not expired
- Ensure tokens have required permissions
- Try regenerating tokens if issues persist
GitHub token scopes required: public_repo, read:project
Jira token: Must have issue creation permissions
Issue Already Exists
Scenario: A Jira issue may already exist for this GitHub issue. Action:
A Jira issue may already exist for GitHub #123
Existing issue: OCPBUGS-4567
Created: 2024-01-15
URL: https://redhat.atlassian.net/browse/OCPBUGS-4567
Options:
1. Skip this issue (recommended)
2. Create duplicate anyway
3. Update existing issue
What would you like to do?
Best Practices
- Use --dryrun first: Always preview what will be created before bulk cloning
- Set up profiles: Create profiles.yaml for projects you clone from frequently
- Verify tokens: Ensure your tokens have appropriate permissions
- Check issue states: Review GitHub issues before cloning to ensure they're relevant
- Batch responsibly: Clone in reasonable batches (10-20 issues at a time)
- Document links: The command automatically adds GitHub links to Jira issues
See Also
/jira:setup-gh2jira- Install and configure gh2jira/jira:reconcile-github- Reconcile state between GitHub and Jira issues/jira:create- Create new Jira issues manually/jira:solve- Analyze and solve Jira issues- gh2jira README
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
-
Fetch bug ticket using
getJiraIssueMCP tool:- Request all fields to ensure we have complete data
- Verify the issue is a Bug type
- Extract issue description, links, and custom fields
-
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
-
Parse bug description to extract required sections:
- Cause: The root cause of the problem
- Consequence: The impact or effect of the problem
-
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:
-
Remote links (Primary source - web links in Jira):
- Check the Jira issue response for web links/remote links
- Common field names:
remotelinks,issuelinkswithoutwardIssue.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}
-
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
- Use regex pattern to find PR URLs:
-
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
-
Deduplicate: Create unique set of PR URLs
-
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-*):
# 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
-
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:
-
Extract repository and PR number from URL:
- Parse:
https://github.com/{org}/{repo}/pull/{number} - Store:
{org}/{repo}asREPO,{number}asPR_NUMBER
- Parse:
-
Fetch PR details using
ghCLI: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
-
Fetch PR diff using
ghCLI:gh pr diff {PR_NUMBER} --repo {REPO}- Analyze code changes to understand what was fixed
- Look for key changes in error handling, validation, etc.
-
Fetch PR comments using
ghCLI:gh pr view {PR_NUMBER} --json comments --repo {REPO}- Extract reviewer comments and author responses
- Look for clarifications about the fix or workarounds
-
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
-
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:
-
Combine Cause/Consequence from Jira bug:
- Use the extracted Cause and Consequence sections
- Clean up formatting (remove Jira markup if needed)
-
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
-
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..."
-
Extract Workaround (if applicable):
- Check if PRs mention temporary solutions
- Only include if a workaround was documented
- Omit this section if no workaround exists
-
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:
-
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
-
Scanning approach:
- Use regex patterns to detect common credential formats
- Check for base64-encoded secrets
- Look for common secret prefixes (sk_, ghp_, etc.)
-
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:
-
Available options (from Jira dropdown):
- Bug Fix (most common for OCPBUGS)
- Release Note Not Required
- Known Issue
- Enhancement
- Rebase
- Technology Preview
- Deprecated Functionality
- CVE
-
Auto-detection (optional):
- For OCPBUGS: Default to "Bug Fix"
- Check PR titles/descriptions for keywords
- Suggest type based on content analysis
-
User confirmation:
- Show suggested type
- Allow user to override
- Use
AskUserQuestiontool for interactive selection
✅ Phase 7: Update Jira Ticket
Update the Jira bug ticket with generated release note:
Use editJiraIssue with contentFormat: "markdown" to set these fields:
customfield_10785(Release Note Type):{"value": "<selected type>"}(e.g.{"value": "Bug Fix"})customfield_10783(Release Note Text): the formatted release note text
- 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:
-
Display generated release note:
Release Note Created for {issue-key} Type: Bug Fix Text: --- Cause: ... Consequence: ... Fix: ... Result: ... Workaround: ... --- Updated: https://redhat.atlassian.net/browse/{issue-key} -
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:
- Fetch the bug from Jira
- Extract Cause and Consequence from the description
- Find and analyze all linked GitHub PRs
- Generate the release note
- Prompt for Release Note Type selection
- Update the Jira ticket
- 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://redhat.atlassian.net/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_10785
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
- Link PRs early: Add GitHub PR links to bugs as soon as PRs are created
- Use structured bug descriptions: Always include Cause and Consequence sections
- Review before submission: Check the generated release note before confirming
- Sanitize PR content: Don't include credentials in PR descriptions or commits
- One release note per bug: Don't run this command multiple times for the same bug
- Update if needed: Release notes can be manually edited in Jira after creation
Prerequisites
Required Tools
-
MCP Jira Server: Must be configured and accessible
- See Jira Plugin README for setup instructions
- Requires read/write permissions for bugs
-
GitHub CLI (
gh): Must be installed and authenticated- Install:
brew install gh(macOS) or see GitHub CLI docs - Authenticate:
gh auth login - Verify:
gh auth status
- Install:
-
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
-
Jira Permissions:
- Read access to bug tickets
- Write access to Release Note Type field (customfield_10785)
- Write access to Release Note Text field (customfield_10783)
-
GitHub Permissions:
- Read access to pull requests
- Read access to repository diffs and commits
See Also
jira:solve- Analyze and solve Jira issuesjira:create- Create Jira issues with guided workflowsjira:generate-test-plan- Generate test plans for PRsjira:status-rollup- Create status rollup reports
Technical Notes
Jira Custom Fields
The command uses these Jira custom field IDs:
customfield_10785: Release Note Type (dropdown)customfield_10783: 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, monitor rate limit usage and reduce concurrent requests if limits are reached
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.
Name
jira:generate-enhancement
Synopsis
/jira:generate-enhancement <issue-key>
Description
The jira:generate-enhancement command generates an OpenShift enhancement proposal markdown file based on a Jira epic or feature. It fetches the feature details, analyzes the content, and creates an enhancement document following the OpenShift enhancement template structure.
This command is particularly useful for:
- Converting strategic Jira features or epics into formal enhancement proposals
- Bootstrapping enhancement documents with epic/feature context
- Maintaining consistency between Jira planning and enhancement documentation
- Accelerating the enhancement proposal writing process
Key Features
- Automatic Feature Fetching - Retrieves feature details from Jira including description, epics, and context
- Template-Based Generation - Creates enhancement markdown following the official OpenShift template
- Content Mapping - Intelligently maps Jira feature fields to enhancement sections
- Epic Integration - Incorporates linked epics as implementation details
- Interactive Refinement - Prompts for missing information and clarifications
- File Naming - Generates appropriate filename based on feature summary
Workflow
The command follows these steps:
1. Fetch Jira Epic or Feature
- Retrieve epic/feature details using MCP Jira tools or REST API
- Extract summary, description, child issues, components, timeline
- Validate issue type (must be an Epic or Feature issue type)
2. Analyze Epic or Feature Content
- Parse description, goals, acceptance criteria
- Identify user stories and objectives
- Extract scope and child issues (epics, stories, tasks)
- Determine topology considerations from components
3. Generate Enhancement Sections
- Map Jira content to enhancement template sections
- Create initial draft with available information
- Identify gaps requiring user input
4. Interactive Refinement
- Prompt for technical implementation details
- Collect test plan information
- Define graduation criteria
- Gather operational considerations
5. Write Enhancement File
- Generate filename from feature summary
- Create markdown file in appropriate directory
- Include all required sections with content or placeholders
6. Verify and Sync with PRs (Optional)
When using --verify or --sync-from-prs flags:
Verification Mode (--verify):
- Fetch all PRs linked to the epic/feature (from Jira links and GitHub PR descriptions)
- Compare enhancement sections against actual PR implementation
- Generate verification report showing:
- ✅ Matches: Sections that align with PR implementation
- ⚠️ Deviations: Changes in approach or scope
- ❌ Incomplete: Missing implementation or tests
- Recommend whether enhancement needs updating
Sync Mode (--sync-from-prs):
- Analyze linked PRs for actual implementation details
- Update enhancement sections with real API changes, test coverage, etc.
- Add "Implementation Notes" section documenting deviations from original proposal
- Preserve sections marked with
<!-- MANUAL -->comments - Update metadata with sync date and analyzed PR count
Interactive Mode (--interactive):
- Show diff for each section change
- Prompt for confirmation before applying updates
- Allow selective section updates
Enhancement Structure Mapping
| Enhancement Section | Source |
|---|---|
| Metadata | Issue key, creation date, authors |
| Summary | Epic/Feature description overview |
| Motivation | Problem statement from description |
| User Stories | Derived from description or child stories |
| Goals | Epic/Feature objectives and acceptance criteria |
| Non-Goals | Out of scope items from description |
| Proposal | Implementation details from child issues |
| Topology Considerations | Detected from components (HyperShift, etc.) |
| Test Plan | User prompts or child issue details |
| Graduation Criteria | Derived from acceptance criteria |
| Support Procedures | User prompts |
Usage Examples
-
Generate enhancement from feature:
/jira:generate-enhancement OCPSTRAT-1596→ Fetches feature, generates enhancement proposal
-
Generate enhancement from epic:
/jira:generate-enhancement HIVE-2589→ Fetches epic and child issues, generates enhancement proposal
-
With custom output directory:
/jira:generate-enhancement CNTRLPLANE-100 --output enhancements/hypershift/→ Generates enhancement in specified directory
-
Verify PRs match enhancement:
/jira:generate-enhancement OCPSTRAT-1596 --verify→ Compares enhancement against linked PRs, shows deviations and incomplete items
-
Update enhancement from actual implementation:
/jira:generate-enhancement OCPSTRAT-1596 --sync-from-prs→ Updates enhancement with actual API changes, test coverage, implementation approach
-
Interactive sync with review:
/jira:generate-enhancement OCPSTRAT-1596 --sync-from-prs --interactive→ Shows each change and prompts for confirmation before applying
Arguments
-
$1 – issue-key (required) Jira epic or feature key (e.g.,
HIVE-2589,OCPSTRAT-1596,CNTRLPLANE-100). Must be an Epic or Feature issue type. -
--output (optional) Output directory for enhancement file. Default:
.work/enhancements/ -
--verify (optional) Verify linked PRs match the enhancement proposal. Generates a verification report showing matches, deviations, and incomplete items.
-
--sync-from-prs (optional) Update the enhancement based on actual PR implementation. Analyzes linked PRs and updates enhancement sections with actual implementation details.
-
--interactive (optional) Prompt before applying sync changes (use with
--sync-from-prs). Shows a diff and asks for confirmation before updating each section. -
--preserve-manual (optional) Don't overwrite sections marked with
<!-- MANUAL -->comments. Default:true -
--repos (optional) Comma-separated list of GitHub repos to search for PRs. Default:
openshift/api,openshift/installer,openshift/machine-api-operator,openshift/cluster-api-provider-aws,openshift/hive
Return Value
- Enhancement file path: Location of created enhancement markdown file
- Summary: Overview of generated content and sections requiring attention
Implementation
This command invokes the jira:generate-enhancement skill which provides detailed guidance on:
- Epic and Feature content extraction
- Enhancement template structure
- Content mapping strategies (from both epic and feature formats)
- Child issue integration (stories, tasks, sub-epics)
- Interactive prompting workflows
- File organization best practices
Error Handling
Issue Not Found
Scenario: Issue key doesn't exist in Jira.
Action:
Issue CNTRLPLANE-999 not found.
Please verify the issue key and try again.
Wrong Issue Type
Scenario: Issue is not an Epic or Feature type.
Action:
CNTRLPLANE-123 is a Story, not an Epic or Feature.
This command requires an Epic or Feature issue type. Use /jira:generate-enhancement with an Epic or Feature key.
Incomplete Epic or Feature
Scenario: Epic/Feature lacks required content sections.
Action:
Warning: Issue is missing some recommended sections:
- Detailed description
- Acceptance criteria
- Child issues
The enhancement will include placeholders for these sections.
Continue? (yes/no)
MCP Access Error
Scenario: Cannot access Jira via MCP.
Action:
Cannot access Jira. Please ensure:
1. MCP Jira server is configured
2. You have permissions to view CNTRLPLANE project
3. Network connectivity is working
Run: /mcp status
Best Practices
- Complete the epic/feature first: Ensure the Jira epic or feature has comprehensive content before generating the enhancement
- Review and refine: The generated enhancement is a starting point; review and enhance with technical details
- Iterate with stakeholders: Share the draft enhancement for feedback before submitting PR
- Keep synchronized: Regenerate the enhancement as the epic/feature evolves in Jira
- Link back to Jira: The tracking-link metadata will automatically reference the source issue
File Organization
Enhancement files are created following OpenShift conventions:
The command suggests the appropriate directory based on feature components.
See Also
jira:generate-feature-doc- Generate feature documentationjira:create- Create Jira issues- OpenShift Enhancement Guidelines: https://github.com/openshift/enhancements/tree/master/guidelines
Skills Reference
This command invokes:
- generate-enhancement - Enhancement generation guidance and template mapping
To view skill details:
cat plugins/jira/skills/generate-enhancement/SKILL.md
Name
jira:generate-feature-doc
Synopsis
/jira:generate-feature-doc <feature-key>
Description
The jira:generate-feature-doc command generates comprehensive feature documentation by recursively analyzing a Jira feature ticket and all its related issues, sub-tasks, and linked GitHub pull requests.
This command is particularly useful for:
- Creating complete feature documentation after implementation
- Understanding the full scope and implementation details of a feature
- Generating onboarding materials for new team members
- Creating technical design documents from actual implementation
- Documenting complex features with multiple related issues and PRs
The command performs deep analysis of:
- The main feature issue and all related Jira tickets (recursively)
- All linked GitHub PRs, commits, and code changes
- Design decisions captured in PR discussions and code reviews
- Implementation details from actual code changes
Implementation
This command orchestrates two skills in sequence to generate comprehensive feature documentation:
-
Extract GitHub PRs (via
jira:extract-prsskill)- Discovers all descendant issues recursively using
parent = KEYBFS - Extracts PR URLs from Jira Remote Links (primary) and text content (backup)
- Fetches PR metadata from GitHub (state, title)
- Returns structured JSON with deduplicated PRs
- Discovers all descendant issues recursively using
-
Generate Documentation (via
jira-doc-generatorskill)- Receives PR data from step 1
- Analyzes MERGED PRs only (fetches metadata, diff, comments)
- Synthesizes feature documentation with the following sections:
- Overview
- Background and Goals
- Architecture and Design
- Usage Guide
- Related Resources (External Links only)
- Skip sections: Implementation Details, Testing
- Outputs to
.work/jira/feature-doc/<feature-key>/feature-doc.md
For detailed implementation, see:
plugins/jira/skills/extract-prs/SKILL.mdplugins/jira/skills/jira-doc-generator/SKILL.md
Arguments
- $1 – feature-key (required)
Jira issue key for the feature (e.g.,
OCPSTRAT-1612). Can be any issue type, but typically used for Features, Epics, or Stories.
Return Value
- Documentation File:
.work/jira/feature-doc/<feature-key>/feature-doc.md - Summary Statistics: Number of issues analyzed, PRs analyzed, total lines of documentation
- Related Resources: List of all Jira issues and GitHub PRs included in the analysis
- Debug Files: Raw issue data, PR data, and analysis log
Output Format
The command generates a comprehensive markdown document at:
.work/jira/feature-doc/<feature-key>/feature-doc.md
Document Structure
# Feature: <Feature Title>
## Overview
- **Jira Issue**: <main issue link>
- **Status**: <status>
- **Related Issues**: <count>
- **Related PRs**: <count>
- **Implementation Period**: <date range>
## Background and Goals
<Extracted from feature description>
## Architecture and Design
<Synthesized from design discussions and PR descriptions>
## Usage Guide
<How to use the implemented feature>
## Related Resources
<External links only - no tables>
Examples
Basic Usage
Generate documentation for a feature:
/jira:generate-feature-doc OCPSTRAT-1612
The command will:
- Fetch the main feature issue
- Recursively discover all related issues (sub-tasks, linked issues, etc.)
- Extract all GitHub PR links from Remote Links API and text
- Analyze each PR (description, code changes, discussions)
- Synthesize all information into a comprehensive document
- Save to
.work/jira/feature-doc/OCPSTRAT-1612/feature-doc.md - Display summary statistics
Example Output
📋 Analyzing OCPSTRAT-1612...
🔗 Discovering related issues (subtasks only)...
✓ Found main feature: "Configure and Modify Internal OVN IPV4 Subnets"
✓ Discovered 2 subtasks
Total issues: 3
🔗 Extracting GitHub PRs...
- From text (descriptions/comments): 1 PR
- From Remote Links API (PRIMARY): 6 PRs
Total unique PRs: 7 (after deduplication)
🔍 Analyzing PRs (MERGED only)...
✓ [1/7] openshift/hypershift#6444 (MERGED)
⚠️ [2/7] openshift/hypershift#6500 (OPEN - skipped)
✓ [3/7] openshift/hypershift#6554 (MERGED)
...
📝 Generating documentation...
✓ Feature overview and background
✓ Architecture and design section
✓ Implementation details
✓ Related resources index
✅ Documentation generated successfully!
📄 File: .work/jira/feature-doc/OCPSTRAT-1612/feature-doc.md
📊 Statistics:
- Jira issues analyzed: 3 (1 feature + 2 subtasks)
- GitHub PRs discovered: 7
- GitHub PRs analyzed: 5 (MERGED only)
- GitHub PRs skipped: 2 (1 OPEN, 1 CLOSED)
- Total commits: 12
- Total files changed: 41
- Documentation lines: 150
Error Handling
For complete error handling documentation, see SKILL.md. Common scenarios:
- Issue Not Found: 404 from Jira API - verify issue key and permissions
- No Related Issues or PRs: Feature may not be implemented yet - generates docs from main issue only
- Circular Dependencies: Cycle detection prevents infinite loops
- GitHub Rate Limit: Can resume after rate limit reset or generate partial docs
- PR Not Accessible: Skips inaccessible PRs (403, 404) but lists them in output
- Large Feature: Warns when >50 issues/PRs, allows user to cancel
See jira-doc-generator SKILL.md Section "Error Handling" for detailed guidance.
Prerequisites
Required Tools
-
jq - JSON parser
- Check:
which jq - Install:
brew install jq(macOS) orapt-get install jq(Linux)
- Check:
-
GitHub CLI (
gh) - For fetching PR data- Install:
brew install gh(macOS) or see GitHub CLI docs - Authenticate:
gh auth login - Verify:
gh auth status
- Install:
-
JIRA Access - Read permissions for issues
- Network access to
https://redhat.atlassian.net
- Network access to
-
GitHub Access - Read access to repositories where PRs are located
- PRs in private repos require appropriate GitHub permissions
Performance Considerations
- Time: Large features may take 5-10 minutes to analyze completely
- API Quota: Each PR analysis uses ~3-4 GitHub API calls
- Rate Limits: GitHub allows 5,000 API calls/hour when authenticated
- Disk Space: Generated documents typically range from 10KB to 500KB
Best Practices
- Link issues in Jira: Ensure sub-tasks and related issues are linked as sub-tasks or parent issues in Jira
- Use Remote Links: Add GitHub PRs via "Link Issue" in JIRA UI (not just in descriptions)
- Use for completed features: Best results when feature is fully implemented
- Review and edit: Generated documentation is a starting point - review and enhance manually
- Save the output: Keep generated docs in version control for team reference
See Also
jira:solve- Analyze and solve Jira issuesjira:create-release-note- Generate release notes from bugs and PRsjira:status-rollup- Create status rollup reportsutils:generate-test-plan- Generate test plans for features
Technical Notes
Recursive Discovery Algorithm
Uses depth-first search with cycle detection:
- Maximum recursion depth: 5 levels (configurable)
- Visited issues tracked in a set to prevent re-processing
- Only explores: subtasks and parent issues
- Does NOT explore: issuelinks (relates, blocks, clones, duplicates) - these represent separate features
See SKILL.md Step 2 for complete algorithm details.
GitHub PR Extraction Strategy
Dual-source approach (implemented in SKILL.md Step 3):
- Primary: JIRA Remote Links API (
/rest/api/3/issue/{key}/remotelink)- Authoritative source for PRs added via "Link Issue" UI
- NOT included in main issue API response
- Backup: Text extraction from descriptions and comments
- Regex:
https?://github\.com/[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+/pulls?/[0-9]+
- Regex:
Both sources are merged and deduplicated.
PR Analysis Filter
Only MERGED PRs are analyzed (implemented in SKILL.md Step 4):
- MERGED: Analyzed and included in documentation
- OPEN: Skipped (work in progress, may change)
- CLOSED: Skipped (not merged, implementation not accepted)
This ensures documentation reflects only shipped implementation.
Output Directory Structure
.work/jira/feature-doc/<feature-key>/
├── feature-doc.md # Main documentation
├── main-issue.json # Main feature issue data
├── issue-*.json # Related issue data
├── pr-*.json # PR metadata
├── pr-*.diff # PR diffs
├── pr-urls.txt # All discovered PR URLs
└── analysis-log.txt # Analysis log (for debugging)
Name
jira:generate-feature-updates
Synopsis
/jira:generate-feature-updates [project-key] [--component <component-name>] [--label <label-name>] [user-filters...]
Description
The jira:generate-feature-updates command generates concise executive-level feature summaries for weekly status documents. It analyzes recent activity across Jira issues and their descendants to produce prose-style updates suitable for the "Key Strategic Feature Updates" section of weekly reports.
This command is particularly useful for:
- Weekly executive status documents
- Strategic feature progress summaries
- Stakeholder communication on feature delivery
- Identifying blocked or at-risk features
Key capabilities:
- Efficient batch data gathering using async Python script
- Interactive component selection from available project components
- User filtering by email or display name (with auto-resolution)
- Intelligent activity analysis using
childIssuesOf()for full hierarchy traversal - GitHub PR and GitLab MR integration via external links
- Automatic filtering: skips issues with no significant activity
- Batch processing with full-section review
- Nested list output: feature link as top-level bullet, update prose as nested bullet
This command uses the Status Analysis Engine skill for core analysis logic. See plugins/jira/skills/status-analysis/SKILL.md for detailed implementation.
Implementation
The command executes in two phases:
Phase 1: Data Gathering
Step 1. Parse Arguments and Determine Target Project
-
Parse command-line arguments:
- Extract project key from first positional argument (e.g.,
OCPSTRAT,OCPBUGS) - Parse optional
--component <component-name>parameter - Parse optional
--label <label-name>parameter - Parse user filter parameters (space-separated emails or names)
- User filters support exclusion by prefixing with an exclamation mark (example: !user@example.com)
- Extract project key from first positional argument (e.g.,
-
If project key is NOT provided:
- Use
mcp__atlassian-mcp__jira_get_all_projectsto list all accessible projects - Present projects in a numbered list with keys and names
- Ask: "Please enter the number of the project you want to generate updates for:"
- Parse response and extract project key
- Use
-
Validate project access:
- Use
mcp__atlassian-mcp__jira_searchwith JQL:project = "{project-key}" AND status != Closed - Verify the project exists and is accessible
- Use
Step 2. Determine Target Component(s)
-
If
--componentparameter is provided:- Use the component name directly
-
If
--componentis NOT provided:- Use
mcp__atlassian-mcp__jira_search_fieldswith keyword "component" to find the component field ID - Query component values through
mcp__atlassian-mcp__jira_searchwithfields=componentsand JQLproject = "{project-key}" AND status != Closed - Extract all unique component names from the search results
- Present components in a numbered list
- Ask: "Please enter the number(s) of the component(s) you want to generate updates for (space-separated), or press Enter to skip:"
- If multiple components selected, process each separately
- Use
Step 3. Resolve User Identifiers
For each user filter parameter:
-
Check if it's an email (contains
@): Use as-is for script parameter -
If it's a display name (doesn't contain
@):- Use
mcp__atlassian-mcp__jira_get_user_profilewith the name as theuser_identifierparameter - Show found user details and ask for confirmation
- If confirmed, use the email address; if not, ask for email directly
- Use
-
Handle exclusion prefix (exclamation mark):
- Strip the prefix before lookup
- Use
--exclude-assigneeparameter for the script
Step 4. Run Data Gatherer Script
Execute the Python data gatherer with the resolved parameters:
python3 {plugins-dir}/jira/skills/status-analysis/scripts/gather_status_data.py \
--project {PROJECT-KEY} \
--component "{COMPONENT-NAME}" \
--label "{LABEL-NAME}" \
--assignee {email1} --assignee {email2} \
--exclude-assignee {excluded-email} \
--verbose
Script location: plugins/jira/skills/status-analysis/scripts/gather_status_data.py
Script output:
- Directory:
.work/weekly-status/{YYYY-MM-DD}/ manifest.json: Processing config and issue listissues/{ISSUE-KEY}.json: Per-issue data with descendants and PRs
Wait for script completion and verify output exists before proceeding.
Step 5. Verify Data Collection
Read the manifest file to confirm successful collection:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Data Collection Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Issues found: {count}
Descendants: {count}
PRs collected: {count}
Date range: {start} to {end}
Output: .work/weekly-status/{date}/
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase 2: Processing (Batch)
Step 6. Load Required Skill
This step is mandatory before processing any issues:
Skill(jira:status-analysis)
This loads the Status Analysis Engine skill which provides:
- Activity analysis methodology
- Feature markdown formatting rules
- Health status determination logic
Step 7. Process ALL Issues (Batch)
Unlike update-weekly-status which processes issues one at a time interactively, this command processes all issues in batch and presents a complete section for review.
For each issue listed in the manifest:
a. Triage and Summarize Issues
Run the summarize script in batch mode with --only-significant to triage and summarize all issues in a single call. If a --label filter was used for data gathering, pass it here too to separate issues that don't carry the label:
python3 {plugins-dir}/jira/skills/status-analysis/scripts/summarize_issue.py \
.work/weekly-status/{date}/issues/ --only-significant --label {label-name}
This combines triage and summarization: it filters to issues with significant activity (PRs merged, status changes, color changes, human comments, descendant updates) and outputs a structured summary for each. PR author names are included in the output (from commits_in_range and reviews_in_range data) — use these first names for attribution, never GitHub handles.
Label filtering: When --label is provided, any issues missing that label are listed separately under a MISSING LABEL header. Present this list to the user and ask whether to include each one. These are typically descendant features that appeared in the hierarchy but aren't directly tracked under the label.
IMPORTANT — parallelization: The batch summarize output can be large. If the output exceeds comfortable context size, split processing across parallel Bash calls or sub-agents. For example, process Yellow/Red issues in one call and Green issues in another. Never loop through issues sequentially with individual script calls.
c. Analyze Activity (using Status Analysis Engine)
Using the pre-gathered data, apply the activity analysis rules from activity-analysis.md:
-
Read the existing Status Summary field (
current_status_summaryin JSON):- Parse the R/Y/G color status (Red, Yellow, Green) — this is the team's own self-assessment
- Check
last_status_summary_update— if the status was updated within the date range, the team actively reported this week - Check
changelog_in_rangefor changes to the Status Summary field — a color change (e.g., Green→Yellow, Yellow→Red) is always significant - Use the R/Y/G status to prioritize and order the output (Red/Yellow features appear before Green), but do not include a feature solely because it is Red/Yellow — there must also be a status change or other activity this week
-
Identify key events from changelog_in_range:
- Status transitions
- Assignee changes
- Priority/scope changes
- Status Summary field changes (color transitions)
-
Analyze comments (excluding bots with
is_bot: true):- Look for blockers, risks, achievements
- Note significant updates
-
Analyze PR activity:
- PRs with
commits_in_range > 0(active development) - PRs with
reviews_in_range > 0(review activity) - Recently merged PRs (
state: MERGED) - Draft PRs awaiting work
- Use
author_namefields (notauthorlogins) when attributing contributions. Always use first names, never GitHub handles.
- PRs with
-
Determine if significant: Skip issues with no noteworthy activity (only bot comments, trivial field changes, no PRs merged or opened). A color change in the Status Summary field (e.g., Green→Red) counts as significant activity and should always be included.
d. Generate feature_markdown Entry
Before generating entries, check for significant issues that have no Color Status in their Status Summary field. If any are found, list them and ask the user:
The following features have significant activity but no R/Y/G color status set:
1. ISSUE-KEY: Issue summary
2. ISSUE-KEY: Issue summary
What color circle should each use? Enter colors (e.g. "1:green 2:yellow"), "all:green" to set all, or "skip" to omit circles:
Then, for each issue with significant activity, format as a nested unordered list item with a color circle prefix (🟢🟡🔴) matching the Color Status from the Status Summary field or the user's override (Green → 🟢, Yellow → 🟡, Red → 🔴, no color → omit circle):
- 🟢 [ISSUE-KEY](https://issues.redhat.com/browse/ISSUE-KEY): Issue summary
- 1-3 sentences of executive prose focusing on significant progress, deliveries, blockers, or risks. Attribute contributions to team members by first name (from `author_name` fields, never GitHub logins). Reference PRs and related issues as markdown links.
Content priorities (in order):
- Features delivered or completing
- Features whose status changed to Red or Yellow this week
- Features with Red/Yellow status and new activity this week
- Features with significant progress (PRs merged, scope changes)
Skip issues where nothing noteworthy happened in the date range.
e. Assemble Full Section
Combine all entries into a single unordered list, ordered by significance:
- Completed/delivered features first
- Features whose status changed to Red or Yellow this week
- Red/Yellow features with new activity
- Features with notable progress
All entries form one continuous markdown unordered list (no blank lines between items).
Step 8. Present for Review
Display the complete assembled section:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Key Strategic Feature Updates
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Issues analyzed: {total}
Features with significant activity: {included}
Features skipped (no activity): {skipped}
Date range: {start} to {end}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{assembled feature updates section}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Before presenting, run the validation script to check for GitHub handle usage:
python3 {plugins-dir}/jira/skills/status-analysis/scripts/validate_feature_updates.py \
--markdown /tmp/feature-updates.md \
--data-dir .work/weekly-status/{date}/issues/
If violations are found, fix them (replace handles with first names from author_name fields) before presenting to the user.
Options:
approveora: Accept and outputmodifyorm: Modify the section (rewrite entries, skip/reorder features)regenerateorr: Regenerate from cached data with different focusquitorq: Abort
If user chooses modify:
- Ask what changes they want (rewrite specific entries, remove entries, reorder, change tone)
- Apply changes and present again
Step 9. Output Delivery
Default: print the final markdown to stdout.
Optional output mode (parsed from original arguments):
--serve: Convert markdown to HTML and serve on localhost for easy copy/paste into Google Docs
HTML conversion and serving (--serve)
-
Write the final markdown to
/tmp/feature-updates.md -
Run the validation script to ensure no GitHub handles remain:
python3 {plugins-dir}/jira/skills/status-analysis/scripts/validate_feature_updates.py \
--markdown /tmp/feature-updates.md \
--data-dir .work/weekly-status/{date}/issues/
If violations are found, fix them before converting to HTML.
- Convert to styled HTML using the Python
markdownlibrary:
import markdown
with open("/tmp/feature-updates.md") as f:
html = markdown.markdown(f.read())
with open("/tmp/feature-updates.html", "w", encoding="utf-8") as f:
f.write("""<!DOCTYPE html>
<html><head>
<meta charset="utf-8">
<style>
body { font-family: Arial, sans-serif; max-width: 800px; margin: 40px auto; line-height: 1.6; font-size: 11pt; }
a { color: #1a73e8; text-decoration: none; }
a:hover { text-decoration: underline; }
ul { margin-bottom: 0.5em; }
li { margin-bottom: 0.3em; }
</style></head><body>
""")
f.write(html)
f.write("</body></html>")
- Validate the generated HTML for encoding issues:
python3 {plugins-dir}/jira/skills/status-analysis/scripts/validate_feature_updates.py \
--html /tmp/feature-updates.html
If validation fails (missing charset, mojibake detected), regenerate the HTML using the template above before proceeding. Do not serve HTML that fails this check.
- Start a local HTTP server in the background:
python3 -m http.server 8787 --directory /tmp --bind 127.0.0.1
- Display the URL to the user:
Serving feature updates at: http://localhost:8787/feature-updates.html
Open in your browser, select all (Ctrl+A / Cmd+A), copy (Ctrl+C / Cmd+C), and paste into Google Docs.
The server will be stopped when you confirm you're done.
- Wait for user confirmation, then stop the background server.
Examples
-
With project and component (recommended):
/jira:generate-feature-updates OCPSTRAT --component "Hosted Control Planes"Output: Gathers data, analyzes all matching issues, presents feature updates section
-
With label filter:
/jira:generate-feature-updates OCPSTRAT --label strategic-work -
With specific users:
/jira:generate-feature-updates OCPSTRAT --component "Hosted Control Planes" user@redhat.com -
Serve as HTML for Google Docs pasting:
/jira:generate-feature-updates OCPSTRAT --component "Hosted Control Planes" --serve -
Full example with all options:
/jira:generate-feature-updates OCPSTRAT --component "Control Plane" --label strategic-work user@redhat.com !manager@redhat.com --serve
Example Output:
- 🟢 [OCPSTRAT-2426](https://issues.redhat.com/browse/OCPSTRAT-2426): Customer global pull secret in HCP for ROSA
- Scope reduced to Managed OpenShift and platforms using node replacement strategy. E2E tests are already passing.
- 🟡 [OCPSTRAT-1409](https://issues.redhat.com/browse/OCPSTRAT-1409): Auto backup/restore for Hosted Clusters
- A bug found in the implementation has highlighted a permission gap that we are going to cover with better UX.
- 🟢 [OCPSTRAT-1558](https://issues.redhat.com/browse/OCPSTRAT-1558): Shared ingress for HCP
- Contributor X's PR #7143 landed this week, completing the core shared ingress controller. Integration tests are passing on AWS.
Arguments
project-key(optional): The Jira project key (e.g.,OCPSTRAT,OCPBUGS). If not provided, prompts for selection--component <name>(optional): Filter by specific component name. If not provided, prompts for selection--label <label-name>(optional): Filter by specific label (e.g.,control-plane-work,strategic-work)user-filters(optional): Space-separated list of user emails or display names- Prefix with exclamation mark to exclude specific users (example: !manager@redhat.com)
- Display names without @ symbol will trigger user lookup with confirmation
--serve(optional): Convert output to HTML and serve on localhost for copy/paste into Google Docs
Notes
Important Implementation Details
-
Two-Phase Execution:
- Phase 1 (Data Gathering): Python script collects all data efficiently in parallel
- Phase 2 (Processing): LLM analyzes all issues in batch with feature_markdown format
-
Batch Processing (key difference from update-weekly-status):
- All issues are processed together, not one-by-one interactively
- Complete section is assembled before presenting for review
- No per-issue approve/skip workflow
-
No Jira Writes:
- This command only reads from Jira (via pre-gathered data)
- Output goes to stdout or localhost HTTP server — never back to Jira
-
Significant Activity Filter:
- Issues with no noteworthy activity are automatically skipped
- Prevents noise from issues that had only bot updates or trivial changes
-
Error Handling:
- Invalid project key: Display error with available projects
- Invalid component: Display available components
- User lookup fails: Ask for email directly
- Script execution failure: Display error and suggest checking environment variables
- No significant activity found: Display message and exit
Prerequisites
- Python 3.8+ with
aiohttppackage installed - Jira MCP server configured and accessible
- Environment variables:
JIRA_TOKENorJIRA_PERSONAL_TOKEN: Jira API bearer tokenGITHUB_TOKENor authenticatedghCLI
- For
--serve: Pythonmarkdownpackage (pip install markdown)
Check for required tools:
# Check Python and aiohttp
python3 -c "import aiohttp; print('aiohttp OK')"
# Check if the Jira token is defined
test -n "$JIRA_TOKEN"
# Check GitHub token (via gh CLI)
gh auth token &> /dev/null
# Check markdown library (for --serve)
python3 -c "import markdown; print('markdown OK')"
Related
- Shared skill:
plugins/jira/skills/status-analysis/SKILL.md - Data gatherer script:
plugins/jira/skills/status-analysis/scripts/gather_status_data.py - Validation script:
plugins/jira/skills/status-analysis/scripts/validate_feature_updates.py - Single-issue rollup:
/jira:status-rollup- Generate comprehensive status comment for one issue - Batch field updates:
/jira:update-weekly-status- Update Status Summary field for multiple issues
Name
jira:grooming
Synopsis
/jira:grooming [project-filter] [time-period] [--component component-name] [--label label-name] [--type issue-type] [--status status] [--story-points]
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
- Sprint-specific grooming sessions with story point summaries
- Sprint retrospectives analyzing completed work
- 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.
-
Story Point Analysis – When
--story-pointsflag is used, extract and analyze story points for all issues, calculate totals by status, priority, and type, and provide velocity metrics for sprint retrospectives. -
Status Filtering – Filter issues by status (e.g., Closed, Done, In Progress, Open) using the
--statusflag to focus on specific workflow states for sprint reviews or retrospectives. -
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
- Time range mode: Filters issues by creation date within the specified period (e.g.,
- Supports complex JQL filters, including multi-project, component-based, label-based, issue-type and status filtering.
- Extracts key fields such as title, type, priority, component, reporter, story points 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).
- When
--story-pointsflag is used:- Calculates total story points by status (Closed, In Progress, Open, etc.)
- Calculates story points by priority and type
- Identifies issues missing story point estimates
- Computes velocity metrics for sprint retrospectives
- 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.
- When
--story-pointsflag is used, includes:- Story point summary section with totals by status
- Velocity metrics and completion percentages
- Breakdown by priority and issue type
- List of issues missing story point estimates
- Output can be copied directly into Confluence or shared with the team.
Usage Examples
-
Single project weekly review:
/jira:grooming OCPSTRAT last-week -
Multiple OpenShift projects:
/jira:grooming "OCPSTRAT,OCPBUGS,HOSTEDCP" last-2-weeks -
Filter by component:
/jira:grooming OCPSTRAT last-week --component "Control Plane" -
Custom date range:
/jira:grooming OCPBUGS 2024-10-01:2024-10-15 -
Filter by label:
/jira:grooming OCPSTRAT last-week --label "technical-debt" -
Combine component and label filters:
/jira:grooming OCPSTRAT last-week --component "Control Plane" --label "performance" -
Query sprint issues with component filter:
/jira:grooming OCPBUGS "OTA 277" --component "Cluster Version Operator" -
Filter by issue type:
/jira:grooming OCPSTRAT last-week --type Bug -
Filter by multiple issue types:
/jira:grooming OCPSTRAT last-week --type "Bug,Epic" -
Combine all filters:
/jira:grooming OCPSTRAT last-week --component "Control Plane" --label "performance" --type Story -
Sprint retrospective with closed issues and story points:
/jira:grooming "CORENET" "Sprint 276" --status Closed --story-points
- Combine Label and status filters:
/jira:grooming OCPBUGS last-week --label "performance" --status "NEW"
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.
# Backlog Grooming Agenda
**Project**: [project-key] | **Period**: [time-period] | **New Issues**: [count]
## 📊 Summary
## 📊 Story Point Summary (when --story-points is used)
**Total Story Points**: 89
### By Status
- **Closed**: 55 points (61.8%)
- **In Progress**: 21 points (23.6%)
- **Open**: 13 points (14.6%)
### By Type
- **Story**: 55 points
- **Bug**: 21 points
- **Task**: 13 points
### Issues Missing Story Points (3)
- PROJ-1240 - Performance optimization needed
- PROJ-1241 - Update documentation
- PROJ-1242 - Refactor authentication module
## 🚨 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)
- [ ] Add story point estimates to 3 issues
Configuration
Default Query Configuration (.jira-grooming.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
- Time ranges:
-
--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 -
--status (optional) Filter by JIRA issue status (single or comma-separated). Examples:
--status Closed--status "POST,ON_QA"--status "In Progress"
-
--story-points (optional) Include story point analysis in the grooming report. When this flag is present:
- Extracts story points from JIRA issues
- Calculates total story points by status, and type
- Identifies issues missing story point estimates
- Generates velocity metrics for sprint retrospectives
- Includes story point summary section in the report
Return Value
- Markdown Report: Ready-to-use grooming agenda with categorized issues and action items
See Also
jira:status-rollup- Status rollup reportsjira:solve- Issue solution generation
Name
jira:issues-by-component
Synopsis
/jira:issues-by-component <project-key> [time-period] [--component component-name] [--assignee username] [--reporter username] [--status status] [--search search-term] [--search-description]
Description
The jira:issues-by-component command provides a comprehensive view of JIRA issues organized by component. It supports two modes of operation:
- Overview Mode (no
--componentflag): Lists all components with high-level statistics - Detail Mode (
--componentspecified): Shows detailed issue information for a specific component
This command is particularly useful for:
- Understanding component-level workload distribution
- Finding issues by component and user assignment
- Identifying component-specific patterns or problems
- Sprint/release planning by component
- Searching for specific issues within component contexts
- Team capacity planning and workload analysis
Key Features:
- Component organization - Issues grouped by JIRA component
- Flexible time filtering - Filter by creation date or update date
- User filtering - Filter by assignee or reporter
- Status filtering - Focus on specific workflow states
- Text search - Find issues by keywords in summary or description
- Dual-mode output - Overview or detailed views based on your needs
Prerequisites
This command requires JIRA credentials to be configured as environment variables. It uses direct API calls with a secure wrapper script to prevent token exposure.
1. Install the Jira Plugin
If you haven't already installed the Jira plugin, see the Jira Plugin README for installation instructions.
2. Configure JIRA Credentials
Why not use MCP commands? MCP commands have performance issues when fetching large datasets:
- Each MCP response must be processed by Claude, consuming LLM 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 a secure curl wrapper script that:
- Reads credentials from environment variables
- Prevents token exposure in process listings or command history
- Streams data directly to disk for efficient processing
Required Environment Variables:
Set the following environment variables:
export JIRA_URL="https://redhat.atlassian.net"
export JIRA_API_TOKEN="your-atlassian-api-token-here"
export JIRA_USERNAME="user@redhat.com"
Getting Your Token:
- Atlassian API Token: API Token Management
Recommended: Create a credentials file
To avoid setting variables every time, create ~/.jira-credentials:
# ~/.jira-credentials
export JIRA_URL="https://redhat.atlassian.net"
export JIRA_API_TOKEN="your-token-here"
export JIRA_USERNAME="user@redhat.com"
Then make it readable only by you:
chmod 600 ~/.jira-credentials
And source it when needed:
source ~/.jira-credentials
Note: The command uses JIRA_API_TOKEN and JIRA_USERNAME for Atlassian Cloud authentication.
Implementation
The command executes the following workflow:
1. Verify Environment Variables
- Check that required environment variables are set:
if [ -z "${JIRA_URL:-}" ]; then echo "Error: JIRA_URL environment variable is required" echo "Please run: export JIRA_URL='https://redhat.atlassian.net'" exit 1 fi if [ -z "${JIRA_API_TOKEN:-}" ]; then echo "Error: JIRA authentication token is required" echo "Please set: export JIRA_API_TOKEN='your-token-here'" exit 1 fi if [ -z "${JIRA_USERNAME:-}" ]; then echo "Error: JIRA_USERNAME environment variable is required" echo "Please set: export JIRA_USERNAME='user@redhat.com'" exit 1 fi - If credentials are missing, display error message with setup instructions from Prerequisites section
- The wrapper script (
jira_curl.sh) will handle these checks automatically
2. Parse Arguments and Set Defaults
- Parse project key from $1 (required): "OCPBUGS", "JIRA", "HYPE", etc.
- Parse optional time-period from $2:
last-week(default if not specified)last-2-weekslast-month- Custom range:
YYYY-MM-DD:YYYY-MM-DD
- Parse optional flags:
--component <name>: Filter to specific component (enables Detail Mode)--assignee <username>: Filter by assignee--reporter <username>: Filter by reporter--status <status>: Filter by status (comma-separated for multiple)--search <term>: Search term for summary (space or comma-separated for multiple keywords)--search-description: Include description in search (only works with--search)
- Validate project key format (uppercase, may contain hyphens)
- Create working directory:
mkdir -p .work/jira-issues-by-component/{project-key}/
3. Construct JQL Query
Build JQL query based on provided filters:
Base query:
project = {project-key}
Add time filter (if time-period provided):
AND created >= -{time-period}
Add component filter (if --component provided):
AND component = "{component-name}"
Add assignee filter (if --assignee provided):
AND assignee = {username}
Add reporter filter (if --reporter provided):
AND reporter = {username}
Add status filter (if --status provided):
AND status IN ({status1}, {status2}, ...)
Example JQL:
project = OCPBUGS
AND created >= -7d
AND component = "Cluster Version Operator"
AND assignee = jsmith
AND status IN (Open, In Progress)
ORDER BY component ASC, priority DESC, updated DESC
- URL-encode the JQL query for use in API requests
4. Fetch All Issues Using Secure Curl Wrapper with Pagination
Fetch Strategy:
- Fetch 1000 tickets per request (JIRA's maximum
maxResultsvalue) - Use pagination (
startAtparameter) to fetch all matching tickets - Save each batch directly to disk to avoid memory issues
- Continue until all tickets are fetched
Security:
- Use
jira_curl.shwrapper script to prevent token exposure - Token is read from environment variables inside the script
- Never appears in process listings (
ps aux) or command history - Wrapper script path:
plugins/jira/skills/jira-issues-by-component/jira_curl.sh
Important API Details:
- Use POST
/rest/api/3/search/jqlendpoint with a JSON body containingjql,fields, andmaxResults - Wrapper automatically adds
Authorization: Basicheader - Check HTTP response code to detect authentication failures
- Request fields:
summary,status,priority,assignee,reporter,created,updated,description,labels,components,issuetype
Batch Processing Loop:
# Get path to secure curl wrapper
PLUGIN_DIR="plugins/jira/skills/jira-issues-by-component"
JIRA_CURL="${PLUGIN_DIR}/jira_curl.sh"
# Verify wrapper script exists
if [ ! -x "$JIRA_CURL" ]; then
echo "Error: Secure curl wrapper not found at: $JIRA_CURL"
exit 1
fi
START_AT=0
BATCH_NUM=0
TOTAL_FETCHED=0
while true; do
# Construct API URL with pagination
API_URL="${JIRA_URL}/rest/api/3/search/jql"
# Build JSON body for POST request
JSON_BODY=$(jq -n \
--arg jql "$JQL" \
--argjson startAt "$START_AT" \
--argjson maxResults 1000 \
'{jql: $jql, startAt: $startAt, maxResults: $maxResults, fields: ["summary","status","priority","assignee","reporter","created","updated","description","labels","components","issuetype"]}')
# Fetch batch using secure wrapper with POST (token not exposed in process list)
HTTP_CODE=$("$JIRA_CURL" -s -w "%{http_code}" \
-X POST -H "Content-Type: application/json" \
-d "$JSON_BODY" \
-o ".work/jira-issues-by-component/${PROJECT_KEY}/batch-${BATCH_NUM}.json" \
"${API_URL}")
# Check HTTP response code
if [ "$HTTP_CODE" -ne 200 ]; then
echo "Error: HTTP $HTTP_CODE received"
cat ".work/jira-issues-by-component/${PROJECT_KEY}/batch-${BATCH_NUM}.json"
exit 1
fi
# Parse response to check if more results exist
BATCH_SIZE=$(jq '.issues | length' ".work/jira-issues-by-component/${PROJECT_KEY}/batch-${BATCH_NUM}.json")
TOTAL=$(jq '.total' ".work/jira-issues-by-component/${PROJECT_KEY}/batch-${BATCH_NUM}.json")
TOTAL_FETCHED=$((TOTAL_FETCHED + BATCH_SIZE))
echo "✓ Fetched ${BATCH_SIZE} issues (${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} issues downloaded in $((BATCH_NUM + 1)) batch(es)"
Why secure wrapper instead of direct curl:
- Security: Token never exposed in process listings or command history
- Reliability: Direct file streaming avoids Claude's tool result size limits (413 errors)
- Performance: Can handle thousands of tickets without LLM token consumption
- Speed: No intermediate serialization through MCP protocol
- Consistency: Same security pattern as
oc authskill
5. Generate Output Report
Load the grouped data and generate the appropriate report based on mode:
Overview Mode (no --component flag)
Format:
# Issues by Component - {PROJECT_KEY}
**Period**: {time-period}
**Filters**: {list active filters}
**Total Issues**: {count}
**Components**: {count}
---
## Component Summary
### 1. Cluster Version Operator (45 issues)
**Status Distribution**: 30 Open, 10 In Progress, 5 Closed
**Priority Distribution**: 15 Critical/High, 20 Normal, 10 Low
**Types**: 25 Bug, 15 Story, 5 Task
**Top Issues**:
- OCPBUGS-1234: CVE update fails - Critical, Open
- OCPBUGS-1235: Upgrade timeout - High, In Progress
- OCPBUGS-1236: Version skew detection - Normal, Open
---
### 2. Networking (32 issues)
**Status Distribution**: 20 Open, 8 In Progress, 4 Closed
**Priority Distribution**: 8 Critical/High, 18 Normal, 6 Low
**Types**: 18 Bug, 10 Story, 4 Task
**Top Issues**:
- OCPBUGS-5678: DNS resolution issue - High, Open
- OCPBUGS-5679: Network policy conflict - Normal, In Progress
---
### Issues Without Component (12)
12 issues are not assigned to any component
Detail Mode (--component specified)
Format:
# Component: {COMPONENT_NAME}
**Project**: {PROJECT_KEY}
**Period**: {time-period}
**Filters**: {list active filters}
**Total Issues**: {count}
---
## Statistics
**Status Distribution**: 30 Open, 10 In Progress, 5 Closed
**Priority Distribution**: 15 Critical/High, 20 Normal, 10 Low
**Type Distribution**: 25 Bug, 15 Story, 5 Task
---
## Critical Priority (3 issues)
### OCPBUGS-1234: CVE update fails on multi-arch clusters
**Status**: Open | **Priority**: Critical | **Type**: Bug
**Assignee**: jsmith | **Reporter**: asmith
**Created**: 2024-12-01 | **Updated**: 2 days ago
**Labels**: security, multi-arch
**Description**:
{First 300 chars of description}
---
### OCPBUGS-1235: Security vulnerability in API endpoint
**Status**: In Progress | **Priority**: Critical | **Type**: Bug
...
---
## High Priority (12 issues)
### OCPBUGS-1240: Upgrade timeout after 30 minutes
**Status**: Open | **Priority**: High | **Type**: Bug
**Assignee**: jdoe | **Reporter**: user1
**Created**: 2024-11-28 | **Updated**: 5 days ago
**Labels**: upgrade, performance
**Description**:
{First 300 chars of description}
---
## Normal Priority (20 issues)
...
## Low Priority (10 issues)
...
6. Display Report to User
- Show the formatted report (overview or detail mode)
- Provide guidance on next steps:
- Suggest using
/jira:issues-by-component {project} --component "{name}"to drill down - Suggest using
/jira:solve {issue-key}to start working on an issue - Suggest refining filters if too many/too few results
- Suggest using
7. Save Report (Optional)
- Offer to save report to
.work/jira-issues-by-component/{project-key}-{component-name}-{timestamp}.md - Useful for documentation and tracking
Error Handling
Missing environment variables: If JIRA_URL is not set:
Error: JIRA_URL environment variable is required
Please set JIRA credentials:
export JIRA_URL='https://redhat.atlassian.net'
export JIRA_API_TOKEN='your-token-here'
export JIRA_USERNAME='user@redhat.com'
Alternatively, source a credentials file:
source ~/.jira-credentials
Missing authentication token: If JIRA_API_TOKEN is not set:
Error: JIRA authentication token is required
Please set:
export JIRA_API_TOKEN='your-token-here'
Get your token from:
- Atlassian API Token: https://id.atlassian.com/manage-profile/security/api-tokens
Missing JIRA_USERNAME: If JIRA_USERNAME is not set:
Error: JIRA_USERNAME environment variable is required
Please set:
export JIRA_USERNAME='user@redhat.com'
Authentication failure: If curl returns 401/403:
Error: JIRA authentication failed (HTTP 401/403)
Please verify your JIRA credentials:
1. Check that JIRA_URL is correct: echo $JIRA_URL
2. Check that your token is valid and not expired
3. Try generating a new token from the JIRA web interface
Invalid project key: Display error with example format
No issues found:
- Explain why (filters may be too restrictive)
- Suggest relaxing filters
- Verify project key and component name are correct
Component not found: If --component specified but component doesn't exist in project:
Error: Component "{component-name}" not found in project {project-key}
Available components:
- Cluster Version Operator
- Networking
- Storage
...
Invalid time period: Display supported formats with examples
curl errors: Check exit code and display helpful error message
jq not found: Inform user to install jq
Rate limiting: If API returns 429, implement exponential backoff (wait 60s, retry)
Return Value
- Console Output: Formatted report showing issues organized by component
- Intermediate Files (created during processing):
.work/jira-issues-by-component/{project-key}/batch-*.json- Raw JIRA API responses.work/jira-issues-by-component/{project-key}/grouped.json- Issues grouped by component with statistics
- Optional Final Report:
.work/jira-issues-by-component/{project-key}-{component-name}-{timestamp}.md
Examples
Note: All examples require JIRA credentials to be set as environment variables (see Prerequisites section).
Before running any examples, set your credentials:
# Option 1: Export directly
export JIRA_URL="https://redhat.atlassian.net"
export JIRA_API_TOKEN="your-token-here"
export JIRA_USERNAME="user@redhat.com"
# Option 2: Source from credentials file
source ~/.jira-credentials
Overview Mode Examples
-
Basic overview - all components from last week:
/jira:issues-by-component OCPBUGS last-weekOutput: High-level summary of all components with issue counts and top issues
-
Overview with status filter:
/jira:issues-by-component OCPBUGS last-month --status "Open,In Progress"Output: All components showing only open and in-progress issues
-
Overview with assignee filter:
/jira:issues-by-component OCPBUGS last-2-weeks --assignee jsmithOutput: All components showing only issues assigned to jsmith
-
Overview with search:
/jira:issues-by-component OCPBUGS last-week --search "upgrade timeout"Output: All components showing only issues with "upgrade" or "timeout" in summary
Detail Mode Examples
-
Detailed view of specific component:
/jira:issues-by-component OCPBUGS --component "Cluster Version Operator"Output: Detailed listing of all issues in the Cluster Version Operator component
-
Component detail with time filter:
/jira:issues-by-component OCPBUGS last-week --component "Networking"Output: Detailed issues from Networking component created in the last week
-
Component detail with user and status filters:
/jira:issues-by-component OCPBUGS --component "Storage" --assignee jsmith --status OpenOutput: Detailed view of open Storage issues assigned to jsmith
-
Component detail with search in summary and description:
/jira:issues-by-component OCPBUGS --component "Networking" --search "DNS timeout" --search-descriptionOutput: Detailed Networking issues containing "DNS" or "timeout" in summary or description
Advanced Examples
-
Custom date range with multiple filters:
/jira:issues-by-component OCPBUGS 2024-11-01:2024-11-30 --component "Cluster Version Operator" --status "Open,In Progress" --search CVEOutput: CVE-related issues in CVO component from November that are still active
-
Reporter-based filtering:
/jira:issues-by-component OCPBUGS last-month --reporter asmith --status ClosedOutput: Overview of all components showing closed issues reported by asmith
-
Multiple search terms:
/jira:issues-by-component OCPBUGS --search "authentication authorization security"Output: Overview showing issues mentioning any security-related keywords
Arguments
-
project-key (required, $1): JIRA project key to search
- Must be uppercase
- May contain hyphens (e.g., "OCPBUGS", "HYPE")
- If not provided, will prompt user
-
time-period (optional, $2): Time range for issue filtering
last-week(default)last-2-weekslast-monthYYYY-MM-DD:YYYY-MM-DD(custom range)- If not provided, defaults to
last-week
-
--component (optional): Filter to specific component
- Enables Detail Mode with verbose issue information
- Component name must match exactly (case-sensitive)
- Example:
--component "Cluster Version Operator"
-
--assignee (optional): Filter by assignee username
- Only shows issues assigned to specified user
- Example:
--assignee jsmith
-
--reporter (optional): Filter by reporter username
- Only shows issues reported by specified user
- Example:
--reporter asmith
-
--status (optional): Filter by issue status
- Single status:
--status Open - Multiple statuses (comma-separated):
--status "Open,In Progress,Reopened" - Common statuses: Open, In Progress, Closed, Resolved, Verified
- Single status:
-
--search (optional): Search term(s) for filtering
- Searches in issue summary (title) by default
- Multiple keywords (space or comma-separated):
--search "upgrade timeout failure" - Case-insensitive matching
- Any keyword match includes the issue
-
--search-description (optional): Include description in search
- Only works when
--searchis also specified - Searches both summary and description text
- May return more results but slower
- Example:
--search "DNS" --search-description
- Only works when
See Also
/jira:backlog- Find suitable backlog tickets to work on/jira:grooming- Generate grooming meeting agendas/jira:solve- Start working on a specific issue
Name
jira:reconcile-github
Synopsis
/jira:reconcile-github [options]
Description
The jira:reconcile-github command identifies and reports state mismatches between linked GitHub and Jira issues according to a configurable state mapping. This command is useful for:
- Ensuring Jira issues stay synchronized with their linked GitHub issues
- Identifying issues that need status updates
- Maintaining workflow consistency between GitHub and Jira
- Auditing cross-platform issue tracking accuracy
The command uses the gh2jira utility to perform the reconciliation. Use /jira:setup-gh2jira to install and configure gh2jira if you haven't already.
Implementation
📋 Phase 1: Validate Prerequisites
Check that the gh2jira utility is available and configured:
-
Verify gh2jira binary exists:
which gh2jira || echo "gh2jira not found. Run /jira:setup-gh2jira to install." -
Verify configuration files exist:
- Check for
tokenstore.yamlin the gh2jira directory - Check for
profiles.yamlif using profiles - Check for
workflows.yamlfor state mapping configuration - If missing, provide instructions on creating them
- Check for
-
Check for required tokens:
- GitHub token (in tokenstore.yaml)
- Jira token (in tokenstore.yaml)
If prerequisites are missing:
- Inform user about missing requirements
- Provide setup instructions (see Error Handling section)
🔍 Phase 2: Parse Arguments
Parse command arguments:
Optional flags:
--github-project <org/repo>: GitHub project (e.g.,operator-framework/operator-lifecycle-manager)--jira-project <key>: Jira project to reconcile (e.g.,OCPBUGS,CNTRLPLANE)--profile <name>: Use named profile from profiles.yaml--porcelain: Output in machine-readable format for scripting--output <format>: Output format for porcelain mode (jsonoryaml, default:json)
Argument validation:
- If
--profileis not used, both--github-projectand--jira-projectshould be provided - If
--porcelainis used,--outputspecifies the format
🔧 Phase 3: Build gh2jira Command
Construct the gh2jira reconcile command based on provided arguments:
Basic command structure:
gh2jira reconcile [flags]
Flag mapping:
--github-project→--github-project org/repo--jira-project→--jira-project KEY--profile→--profile-name name--porcelain→--porcelain--output→--output json|yaml
Example commands:
# Using profile
gh2jira reconcile --profile-name my-profile
# Using explicit projects
gh2jira reconcile --github-project operator-framework/olm --jira-project OCPBUGS
# Porcelain output for scripting
gh2jira reconcile --profile-name default --porcelain --output json
▶️ Phase 4: Execute Reconciliation
-
Run the gh2jira command:
- Execute the constructed command
- Capture stdout and stderr
- Monitor exit code
-
Parse reconciliation output:
- The command identifies Jira issues with GitHub links
- Compares states according to workflows.yaml mapping
- Reports mismatches
-
Process results:
- Parse output (either human-readable or porcelain format)
- Categorize mismatches by type
- Calculate statistics
📊 Phase 5: Display Results
Format and display results to the user based on output mode:
Human-readable output (default):
Reconciliation Report
=====================
Found 25 Jira issues with GitHub links
State Mismatches (5):
---------------------
1. OCPBUGS-4567 ↔ GitHub #123
Jira: "In Progress" | GitHub: "closed"
Expected Jira states: Done, Dev Complete, Release Pending
→ Jira issue should be closed
2. OCPBUGS-4568 ↔ GitHub #456
Jira: "Done" | GitHub: "open"
Expected Jira states: To Do, In Progress, New, Code Review
→ Jira issue was closed but GitHub issue is still open
Summary:
--------
Total issues checked: 25
Synchronized: 20 (80%)
Mismatched: 5 (20%)
Porcelain output (--porcelain --output json):
{
"total_issues": 25,
"synchronized": 20,
"mismatched": 5,
"mismatches": [
{
"jira_key": "OCPBUGS-4567",
"jira_state": "In Progress",
"github_issue": 123,
"github_state": "closed",
"expected_jira_states": ["Done", "Dev Complete", "Release Pending"]
}
]
}
Return Value
- Success: Reconciliation report with statistics and mismatches
- Porcelain mode: Machine-readable JSON or YAML output
- Error: Error messages with troubleshooting guidance
Examples
Example 1: Reconcile using profile
/jira:reconcile-github --profile olm-project
Uses the olm-project profile to reconcile all linked issues.
Example 2: Reconcile with explicit projects
/jira:reconcile-github --github-project operator-framework/operator-lifecycle-manager --jira-project OCPBUGS
Reconciles issues between the specified GitHub and Jira projects.
Example 3: Machine-readable output for scripting
/jira:reconcile-github --profile default --porcelain --output json
Outputs reconciliation results in JSON format for automated processing.
Arguments
-
--github-project (optional) GitHub project in format
org/repo(e.g.,operator-framework/operator-lifecycle-manager). Not required if: using--profile -
--jira-project (optional) Jira project key to reconcile (e.g.,
OCPBUGS,CNTRLPLANE). Not required if: using--profile -
--profile (optional) Named profile from profiles.yaml that contains GitHub and Jira project mappings. Example:
--profile olm-project -
--porcelain (optional) Output in machine-readable format for scripts and automation. Use with:
--outputto specify format -
--output (optional) Output format when using
--porcelain. Options:json(default) |yaml
Configuration
Workflows Configuration
The reconciliation logic uses workflows.yaml to define state mappings:
Default configuration (workflows.yaml in gh2jira installation directory):
schema: gh2jira.workflows
name: jira
mappings:
- ghstate: "open"
jstates:
- "To Do"
- "In Progress"
- "New"
- "Code Review"
- ghstate: "closed"
jstates:
- "Done"
- "Dev Complete"
- "Release Pending"
How it works:
- When a GitHub issue is "open", the linked Jira issue should be in one of: To Do, In Progress, New, or Code Review
- When a GitHub issue is "closed", the linked Jira issue should be in one of: Done, Dev Complete, or Release Pending
- Mismatches are reported when the Jira state doesn't match the expected states for the GitHub state
Error Handling
gh2jira Binary Not Found
Scenario: The gh2jira binary doesn't exist.
Action:
The gh2jira utility is not installed.
Please run /jira:setup-gh2jira to install and configure gh2jira.
Missing TokenStore
Scenario: tokenstore.yaml doesn't exist.
Action: Provide setup instructions (same as clone-from-github command).
Missing Workflows Configuration
Scenario: workflows.yaml doesn't exist.
Action:
Workflows configuration not found.
Please run /jira:setup-gh2jira to configure gh2jira, which will create the default workflows.yaml configuration.
Alternatively, create workflows.yaml manually in the gh2jira installation directory:
cat > workflows.yaml << 'EOF'
schema: gh2jira.workflows
name: jira
mappings:
- ghstate: "open"
jstates:
- "To Do"
- "In Progress"
- "New"
- "Code Review"
- ghstate: "closed"
jstates:
- "Done"
- "Dev Complete"
- "Release Pending"
EOF
Best Practices
- Run regularly: Schedule reconciliation checks weekly or after major releases
- Use porcelain for automation: Integrate with CI/CD or reporting tools using JSON/YAML output
- Customize workflows: Edit workflows.yaml to match your team's Jira workflow states
- Review mismatches: Investigate patterns in mismatches to improve processes
See Also
/jira:setup-gh2jira- Install and configure gh2jira/jira:clone-from-github- Clone GitHub issues to Jira/jira:solve- Analyze and solve Jira issues/jira:status-rollup- Create status rollup reports- gh2jira README
Name
jira:setup-gh2jira
Synopsis
/jira:setup-gh2jira
Description
The jira:setup-gh2jira command guides you through the complete installation and configuration of the gh2jira utility, which enables cloning and reconciling GitHub issues with Jira. This command:
- Checks for and installs required dependencies (Go)
- Clones and builds the gh2jira utility
- Guides you through creating GitHub and Jira API Tokens
- Creates and configures
tokenstore.yamlwith your credentials - Optionally creates
profiles.yamlfor project shortcuts - Creates default
workflows.yamlfor state mapping - Adds gh2jira to your PATH for easy access
Implementation
📋 Phase 1: Check Prerequisites
1.1 Verify Go Installation
Check if Go is installed:
go version
If Go is not installed:
- Display Go version if present
- If missing, provide installation instructions based on platform:
macOS:
# Using Homebrew (recommended)
brew install go
# Or download from: https://go.dev/dl/
Linux:
# Ubuntu/Debian
sudo apt update && sudo apt install golang-go
# Fedora/RHEL
sudo dnf install golang
# Or download from: https://go.dev/dl/
Windows:
- Download installer from: https://go.dev/dl/
- Run the MSI installer
- Verify installation by opening a new terminal and running
go version
Minimum Go version: 1.18 or higher
1.2 Verify Git Installation
git --version
If not installed, provide platform-specific instructions.
1.3 Check for Existing gh2jira Installation
which gh2jira
If gh2jira is found, ask the user if they want to:
- Reconfigure the existing installation
- Reinstall from scratch
- Exit setup
🔧 Phase 2: Install gh2jira
2.1 Determine Installation Location
Ask the user where they want to install gh2jira:
Recommended locations:
~/go/src/github.com/oceanc80/gh2jira(Go workspace convention)~/.local/bin/gh2jira(User local binaries)- Custom path specified by user
Prompt:
Where would you like to install gh2jira?
1. ~/go/src/github.com/oceanc80/gh2jira (recommended)
2. ~/.local/share/gh2jira
3. Custom path
Enter choice (1-3):
Store the chosen installation directory as $GH2JIRA_DIR.
2.2 Clone the Repository
mkdir -p $(dirname $GH2JIRA_DIR)
git clone https://github.com/oceanc80/gh2jira.git $GH2JIRA_DIR
cd $GH2JIRA_DIR
Handle errors:
- Directory already exists: Ask to remove or use existing
- Network issues: Provide troubleshooting steps
- Permission issues: Suggest using different directory or fixing permissions
2.3 Build gh2jira
cd $GH2JIRA_DIR
make
Verify build:
./gh2jira --version
If build fails:
- Check Go version meets minimum requirements
- Check for missing dependencies
- Display error message and suggest checking gh2jira README
🔐 Phase 3: Configure Authentication
This phase guides the user through creating and configuring authentication tokens.
3.1 Create GitHub Personal Access Token
Instructions for user:
Creating GitHub Personal Access Token
======================================
1. Open: https://github.com/settings/tokens
2. Click "Generate new token" → "Generate new token (classic)"
3. Set token description: "gh2jira access"
4. Select scopes:
✓ public_repo (Access public repositories)
✓ read:project (Read project data)
5. Click "Generate token"
6. Copy the token (you won't see it again!)
IMPORTANT: Keep this token secure. Do not commit it to version control.
Prompt user to enter token:
Please paste your GitHub Personal Access Token:
(input will be hidden)
Store in variable: $GITHUB_TOKEN
Validate token:
# Test token with a simple API call
curl -s -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user | jq -r '.login'
If successful, display: ✓ GitHub token validated for user: <username>
If failed:
✗ GitHub token validation failed.
Possible issues:
- Token is invalid or expired
- Token doesn't have required scopes
- Network connectivity issues
Please verify your token and try again.
3.2 Create Jira API Token
Instructions for user:
Creating Jira API Token
====================================
The process varies by Jira installation:
For Atlassian Cloud (redhat.atlassian.net, *.atlassian.net):
1. Open: https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Enter a label: "gh2jira access"
4. Click "Create"
5. Copy the token
For Jira Data Center/Server:
- Contact your Jira administrator for token creation process
- Some organizations use different authentication methods
For Red Hat Jira:
- May require specific Red Hat SSO or Kerberos setup
- Consult your organization's documentation
Prompt user to enter token:
Please paste your Jira API Token:
(input will be hidden)
If you're unsure about your Jira token setup, enter 'skip' to configure later.
Store in variable: $JIRA_API_TOKEN
Prompt user to enter username:
Please enter your Atlassian account email (e.g., user@redhat.com):
Store in variable: $JIRA_USERNAME
Validate token (optional, requires Jira URL):
Enter your Jira base URL (e.g., https://redhat.atlassian.net):
# Test token
curl -s -u "$JIRA_USERNAME:$JIRA_API_TOKEN" "$JIRA_URL/rest/api/3/myself" | jq -r '.displayName'
3.3 Create tokenstore.yaml
cat > $GH2JIRA_DIR/tokenstore.yaml << EOF
schema: gh2jira.tokenstore
authTokens:
jira: $JIRA_API_TOKEN
# Basic auth requires both username and token; jira_username may be needed by gh2jira
jira_username: $JIRA_USERNAME
github: $GITHUB_TOKEN
EOF
# Secure the file (permissions: owner read/write only)
chmod 600 $GH2JIRA_DIR/tokenstore.yaml
Confirm:
✓ Created tokenstore.yaml
✓ File permissions set to 600 (owner read/write only)
Location: $GH2JIRA_DIR/tokenstore.yaml
📂 Phase 4: Configure Profiles (Optional)
Profiles make it easier to work with specific GitHub/Jira project combinations.
Ask user:
Would you like to create project profiles?
Profiles allow you to use shortcuts like:
gh2jira clone 123 --profile-name my-project
Instead of:
gh2jira clone 123 --github-project org/repo --jira-project KEY
Create profiles now? (y/n):
If yes, proceed with profile creation:
4.1 Collect Profile Information
For each profile (allow creating multiple):
Profile Configuration
=====================
Profile #1
Description (e.g., "OLM Project", "OpenShift Origin"):
>
GitHub project (org/repo format, e.g., "operator-framework/operator-lifecycle-manager"):
>
Jira project key (e.g., "OCPBUGS", "CNTRLPLANE"):
>
Add another profile? (y/n):
4.2 Create profiles.yaml
cat > $GH2JIRA_DIR/profiles.yaml << 'EOF'
profiles:
EOF
# For each profile, append:
cat >> $GH2JIRA_DIR/profiles.yaml << EOF
- description: $PROFILE_DESC
githubConfig:
project: $GITHUB_PROJECT
jiraConfig:
project: $JIRA_PROJECT
tokenStore: tokenstore.yaml
EOF
Confirm:
✓ Created profiles.yaml with X profile(s)
Profiles:
- $PROFILE_1_DESC
- $PROFILE_2_DESC
...
Location: $GH2JIRA_DIR/profiles.yaml
🔄 Phase 5: Configure Workflows
Workflows define how GitHub and Jira issue states are mapped.
Explain to user:
Workflow Configuration
======================
Workflows map GitHub issue states (open/closed) to Jira status values.
Default mapping:
GitHub "open" → Jira: To Do, In Progress, New, Code Review
GitHub "closed" → Jira: Done, Dev Complete, Release Pending
Would you like to:
1. Use default workflow mapping (recommended)
2. Customize workflow mapping
3. Skip workflow setup
Enter choice (1-3):
5.1 Create Default workflows.yaml
cat > $GH2JIRA_DIR/workflows.yaml << 'EOF'
schema: gh2jira.workflows
name: jira
mappings:
- ghstate: "open"
jstates:
- "To Do"
- "In Progress"
- "New"
- "Code Review"
- ghstate: "closed"
jstates:
- "Done"
- "Dev Complete"
- "Release Pending"
EOF
5.2 Custom Workflow Mapping
If user chooses custom mapping:
Custom Workflow Configuration
==============================
For GitHub state "open", enter Jira statuses (comma-separated):
Examples: To Do, In Progress, Backlog, New
>
For GitHub state "closed", enter Jira statuses (comma-separated):
Examples: Done, Closed, Resolved, Verified
>
Create workflows.yaml with custom mappings.
Confirm:
✓ Created workflows.yaml
Location: $GH2JIRA_DIR/workflows.yaml
You can edit this file later to adjust state mappings.
🔗 Phase 6: Add to PATH
Make gh2jira easily accessible from anywhere.
Detect shell:
echo $SHELL
Ask user:
Add gh2jira to PATH?
====================
This will make gh2jira available from any directory.
We can add it to your shell configuration:
- Detected shell: $SHELL
- Config file: $SHELL_CONFIG
Add to PATH now? (y/n):
6.1 Create Symlink or Alias
Option 1: Symlink (recommended)
# Create symlink in user's local bin (ensure directory exists)
mkdir -p ~/.local/bin
ln -sf $GH2JIRA_DIR/gh2jira ~/.local/bin/gh2jira
# Add ~/.local/bin to PATH if not already there
if ! echo $PATH | grep -q "$HOME/.local/bin"; then
echo 'export PATH="$HOME/.local/bin:$PATH"' >> $SHELL_CONFIG
fi
Option 2: PATH export
echo "export PATH=\"$GH2JIRA_DIR:\$PATH\"" >> $SHELL_CONFIG
Shell config files by shell type:
- bash:
~/.bashrcor~/.bash_profile - zsh:
~/.zshrc - fish:
~/.config/fish/config.fish
Confirm:
✓ Added gh2jira to PATH
To use gh2jira immediately, run:
source $SHELL_CONFIG
Or open a new terminal.
✅ Phase 7: Verify Installation
Run validation checks to ensure gh2jira is accessible and all configuration files exist.
# Check gh2jira is in PATH
which gh2jira
# Verify version
gh2jira --version
# Test configuration files exist
test -f $GH2JIRA_DIR/tokenstore.yaml && echo "✓ tokenstore.yaml"
test -f $GH2JIRA_DIR/profiles.yaml && echo "✓ profiles.yaml"
test -f $GH2JIRA_DIR/workflows.yaml && echo "✓ workflows.yaml"
Display summary:
Installation Complete!
======================
✓ gh2jira installed at: $GH2JIRA_DIR
✓ GitHub token configured
✓ Jira token configured
✓ Profiles created: X
✓ Workflows configured
✓ Added to PATH
Next Steps:
-----------
1. Test GitHub connection:
gh2jira github list --github-project your-org/your-repo
2. Test Jira connection:
gh2jira jira list --jira-project YOUR-PROJECT-KEY
3. Clone a GitHub issue:
gh2jira clone <issue-number> --profile-name <profile>
4. Use with Claude Code commands:
/jira:clone-from-github <issue-number> --profile <profile>
/jira:reconcile-github --profile <profile>
Documentation:
--------------
- gh2jira README: https://github.com/oceanc80/gh2jira
- Command help: gh2jira --help
- Claude Code commands: /jira:clone-from-github, /jira:reconcile-github
Configuration Files:
--------------------
- Tokens: $GH2JIRA_DIR/tokenstore.yaml
- Profiles: $GH2JIRA_DIR/profiles.yaml
- Workflows: $GH2JIRA_DIR/workflows.yaml
To update tokens or configuration, edit these files or run /jira:setup-gh2jira again.
🔄 Phase 8: Environment Variables (Optional)
Optionally set environment variables for easier configuration:
# Add to shell config
cat >> $SHELL_CONFIG << EOF
# gh2jira configuration
export GH2JIRA_DIR="$GH2JIRA_DIR"
export GH2JIRA_TOKENSTORE="$GH2JIRA_DIR/tokenstore.yaml"
export GH2JIRA_PROFILES="$GH2JIRA_DIR/profiles.yaml"
export GH2JIRA_WORKFLOWS="$GH2JIRA_DIR/workflows.yaml"
EOF
Return Value
Success:
- Installation directory path
- Configuration file locations
- Summary of created resources
- Next steps for using gh2jira
Partial Success:
- List of completed steps
- List of skipped or failed steps
- Instructions to complete remaining setup manually
Error:
- Detailed error message
- Step where failure occurred
- Troubleshooting suggestions
- Link to gh2jira documentation
Examples
Example 1: Complete setup with profiles
/jira:setup-gh2jira
> Installing to ~/go/src/github.com/oceanc80/gh2jira
> Building gh2jira...
> Enter GitHub token: ***
> Enter Jira token: ***
> Create profile: "My Project"
> GitHub: myorg/myrepo
> Jira: MYPROJ
> Using default workflows
> Added to PATH
✓ Setup complete!
Example 2: Minimal setup without profiles
/jira:setup-gh2jira
> Installing to ~/.local/share/gh2jira
> Building gh2jira...
> Enter GitHub token: ***
> Enter Jira token: ***
> Skip profiles
> Using default workflows
> Added to PATH
✓ Setup complete!
Example 3: Reconfigure existing installation
/jira:setup-gh2jira
> Found existing installation at ~/go/src/github.com/oceanc80/gh2jira
> Reconfigure? yes
> Keep existing GitHub token
> Update Jira token: ***
> Add new profile: "Second Project"
> Keep existing workflows
✓ Reconfiguration complete!
Error Handling
Go Not Installed
Scenario: Go is not found on the system.
Action:
✗ Go is not installed
gh2jira requires Go 1.18 or higher.
Install Go:
- macOS: brew install go
- Linux: sudo apt install golang-go (Ubuntu/Debian)
- Windows: Download from https://go.dev/dl/
After installing, run /jira:setup-gh2jira again.
Build Failure
Scenario: make fails to build gh2jira.
Action:
✗ Failed to build gh2jira
Error output:
<error message>
Troubleshooting:
1. Ensure Go version is 1.18+: go version
2. Check for missing dependencies: go mod download
3. Try manual build: cd $GH2JIRA_DIR && go build
4. See gh2jira README: https://github.com/oceanc80/gh2jira
Would you like to:
1. Retry build
2. Continue setup without building (configure only)
3. Exit setup
Invalid GitHub Token
Scenario: GitHub token validation fails.
Action:
✗ GitHub token validation failed
The token may be invalid, expired, or lack required permissions.
Required scopes:
- public_repo
- read:project
Options:
1. Re-enter token
2. Skip GitHub token (configure later)
3. Exit setup
Check token at: https://github.com/settings/tokens
Invalid Jira Token
Scenario: Jira token validation fails.
Action:
✗ Jira token validation failed
This may be due to:
- Invalid or expired token
- Incorrect Jira URL
- Network issues
- Organization-specific authentication requirements
Options:
1. Re-enter token
2. Try different Jira URL
3. Skip Jira token (configure later)
4. Exit setup
For Red Hat Jira or custom setups, consult your organization's documentation.
Permission Denied
Scenario: Cannot write to installation directory.
Action:
✗ Permission denied: Cannot write to <directory>
Options:
1. Choose different installation directory
2. Fix permissions: sudo chown -R $USER <directory>
3. Use user directory: ~/.local/share/gh2jira
Would you like to:
1. Select new directory
2. Exit setup
PATH Already Contains gh2jira
Scenario: gh2jira is already in PATH from a different location.
Action:
⚠ gh2jira already exists in PATH at: <existing-path>
This installation is at: <new-path>
Options:
1. Replace existing with new installation
2. Keep both (may cause confusion)
3. Skip PATH modification
4. Abort installation
Which would you prefer?
Best Practices
-
Secure your tokens: The setup command sets
tokenstore.yamlto mode 600 (owner read/write only). Never commit this file to version control. -
Use profiles: Create profiles for frequently-used project combinations to simplify commands.
-
Test connections: After setup, test both GitHub and Jira connections with
gh2jira github listandgh2jira jira list. -
Backup configuration: Keep a backup of your configuration files (excluding
tokenstore.yaml) for easy recovery. -
Update regularly: Periodically update gh2jira by running
cd $GH2JIRA_DIR && git pull && make. -
Token rotation: When rotating tokens, simply edit
tokenstore.yamlwith new values or run/jira:setup-gh2jiraagain.
Security Considerations
- Token storage: Tokens are stored in plaintext in
tokenstore.yaml. Ensure file has restrictive permissions (600). - Token scopes: Only grant minimum required scopes to tokens.
- Environment variables: Avoid storing tokens in environment variables that may be logged.
- Shared systems: On shared systems, be extra cautious about file permissions and token security.
- Token expiration: Set token expiration dates and rotate regularly per your security policy.
See Also
- gh2jira Repository
- Go Installation Guide
- GitHub Personal Access Tokens
- Atlassian API Tokens
/jira:clone-from-github- Clone GitHub issues to Jira/jira:reconcile-github- Reconcile state between GitHub and Jira
Troubleshooting
Command not found after setup
# Reload shell configuration
source ~/.bashrc # or ~/.zshrc, etc.
# Or verify PATH
echo $PATH | grep gh2jira
Cannot clone issues after setup
- Verify tokens: Check
tokenstore.yamlhas valid tokens - Test connections: Run
gh2jira github listandgh2jira jira list - Check profiles: Verify
profiles.yamlhas correct project names - Review errors: Run with verbose output for detailed errors
Workflow reconciliation not working
- Check
workflows.yamlexists and has valid YAML syntax - Verify state names match your Jira workflow states exactly
- Test with
gh2jira reconcile --profile-name <profile>
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) via
parent = KEYBFS - Analyzes status transitions, assignee changes, and priority shifts
- Extracts blockers, risks, and completion insights from comments
- Generates valid Jira markdown with nested bullets
- Caches all data in a temp file for fast iterative refinement
- Allows review and modification before posting to Jira
This command uses the Status Analysis Engine skill for core analysis logic. See plugins/jira/skills/status-analysis/SKILL.md for detailed implementation.
IMPORTANT - Skill Loading Requirement:
Before processing any issues, you MUST invoke Skill(jira:status-analysis) to load the Status Analysis Engine skill. This ensures proper use of parent = KEY BFS for hierarchy traversal and consistent analysis methodology. Do NOT rely on conversation summaries or memory - always load the skill explicitly at the start of execution.
Implementation
The command executes the following workflow:
0. Load Required Skills (MANDATORY)
This step is non-negotiable and must be performed first:
Skill(jira:status-analysis)
This loads the Status Analysis Engine skill which provides:
- Proper
parent = KEYBFS for hierarchy traversal - Activity analysis methodology
- External links processing (GitHub PRs, GitLab MRs)
- Markdown comment formatting rules
Do NOT skip this step even in continued sessions. Session summaries do not preserve skill context.
1. Parse Arguments and Validate
- Extract issue ID from $1
- Parse
--start-dateand--end-dateif 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. Initialize Analysis Configuration
Build the configuration for the Status Analysis Engine:
{
"root_issues": ["{issue-id}"],
"date_range": {
"start": "{start-date}",
"end": "{end-date}"
},
"output_format": "markdown_comment",
"output_target": "comment",
"external_links_enabled": false,
"cache_to_file": true
}
3. Execute Status Analysis Engine
Follow the skill documentation in plugins/jira/skills/status-analysis/:
-
Data Collection (
data-collection.md):- Fetch the root issue with
getJiraIssue - Discover all descendants via
parent = {issue-id}BFS recursion - Fetch details and changelogs for all issues
- Cache data to temp file:
/tmp/jira-status-{issue-id}-{timestamp}.md
- Fetch the root issue with
-
Activity Analysis (
activity-analysis.md):- Filter changelog and comments to date range
- Identify status transitions, blockers, risks, achievements
- Calculate completion metrics
- Determine overall health (green/yellow/red)
-
Formatting (
formatting.md):- Generate Jira markdown using
markdown_commentformat - Include sections: Overall Status, This Period, Next Steps, Risks, Metrics
- Generate Jira markdown using
4. Present to User for Review
Display:
- Temp file location for verification
- Generated summary in formatted output
- Ask: "Would you like to post this to Jira, modify it, or cancel?"
Options:
postorp: Proceed to post commentmodifyorm: Request changes, regenerate from cached datacancelorc: Abort without posting
5. Iterative Refinement
If user requests changes, read from temp file (NO re-fetching from Jira):
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 and present again.
6. Post Comment to Issue
Once approved:
- Use
addCommentToJiraIssuewithcontentFormat: "markdown"to post to the root issue - Comment includes footer:
_Generated with [Claude Code](https://claude.com/claude-code) via `/jira:status-rollup {issue-id} --start-date {date} --end-date {date}`_ - Confirm success and provide issue URL
7. Temp File Cleanup
Ask user if they want to keep /tmp/jira-status-{issue-id}-{timestamp}.md:
- Keep for reference or future refinement
- Delete if no longer needed
Return Value
- Posted to Jira: Formatted status comment on the root issue
- Temp file:
/tmp/jira-status-{issue-id}-{timestamp}.mdcontaining:- Root issue details
- Complete issue hierarchy with counts by type
- Raw changelog data for all issues
- All comments with metadata (author, date, issue key)
- Analysis results (blockers, risks, achievements, metrics)
Examples
-
Generate status for a Feature for a specific week:
/jira:status-rollup FEATURE-123 --start-date 2025-01-06 --end-date 2025-01-13Output: Weekly status comment posted to FEATURE-123
-
Generate status for an Epic:
/jira:status-rollup EPIC-456 --start-date 2025-01-06 --end-date 2025-01-13Output: Epic status summary with all child stories analyzed
-
Generate status for a Story with subtasks:
/jira:status-rollup STORY-789Output: Status from story creation date to today
-
Generate status from a start date to now:
/jira:status-rollup CNTRLPLANE-1234 --start-date 2025-01-06Output: Status from Jan 6 to today
Example Output:
## Status Rollup: 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 Period
**Completed:**
- [AUTH-101](https://redhat.atlassian.net/browse/AUTH-101) - OAuth2 implementation (PR #456 merged, all review feedback addressed)
- [AUTH-102](https://redhat.atlassian.net/browse/AUTH-102) - Token validation with comprehensive unit tests
**In Progress:**
- [UI-201](https://redhat.atlassian.net/browse/UI-201) - Login UI components (design review completed, implementing responsive layout)
- [AUTH-103](https://redhat.atlassian.net/browse/AUTH-103) - Session handling refactor (draft PR submitted)
**Blocked:**
- [AUTH-104](https://redhat.atlassian.net/browse/AUTH-104) - Azure AD integration (waiting on subscription approval)
> Need Azure subscription approved before proceeding - submitted ticket #12345
### Next Steps
- Complete session handling refactor (AUTH-103) and submit for review
- Finish login UI responsive implementation (UI-201)
- Begin end-to-end testing (AUTH-107) once session handling is merged
### Risks
- **Medium:** API deprecation in upstream dependency may require refactor in Q2
### Metrics
- **Total Issues:** 15
- **Completed:** 8 (53%)
- **In Progress:** 4
- **Blocked:** 1
- **Updated This Period:** 6
---
_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
Error Handling
| Error | Handling |
|---|---|
| Invalid issue ID | Display error with verification instructions |
| No child issues | Generate summary for single issue (root only) |
| 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 |
Related
- Shared skill:
plugins/jira/skills/status-analysis/SKILL.md - Batch updates:
/jira:update-weekly-status- Update Status Summary field for multiple issues - Feature updates:
/jira:generate-feature-updates- Generate strategic feature updates for weekly status documents
Name
jira:update-weekly-status
Synopsis
/jira:update-weekly-status [project-key] [--component <component-name>] [--label <label-name>] [user-filters...]
Description
The jira:update-weekly-status command automates the process of updating weekly status summaries for Jira issues in a specified project. It analyzes recent activity across tickets, GitHub PRs, and GitLab MRs to draft color-coded status updates (Red/Yellow/Green), then allows you to review and modify them before updating Jira.
This command is particularly useful for:
- Weekly status updates on strategic issues
- Team lead status reporting workflows
- Consistent formatting across status updates
- Reducing manual effort in gathering context from multiple sources
Key capabilities:
- Efficient batch data gathering using async Python script
- Interactive component selection from available project components
- User filtering by email or display name (with auto-resolution)
- Intelligent activity analysis using
parent = KEYJQL for full hierarchy traversal (Atlassian Cloud compatible) - GitHub PR and GitLab MR integration via external links
- Recent update warnings to prevent duplicate updates
- Batch processing with selective skip options
- Formatted status summaries with color-coded health indicators (Red/Yellow/Green)
This command uses the Status Analysis Engine skill for core analysis logic. See plugins/jira/skills/status-analysis/SKILL.md for detailed implementation.
[Extended thinking: This command streamlines weekly status update workflows by first gathering all data efficiently using an async Python script, then processing each issue with focused LLM context. This two-phase approach minimizes API calls and ensures consistent, high-quality analysis.]
Implementation
The command executes in two phases:
Phase 1: Data Gathering
Step 1. Parse Arguments and Determine Target Project
-
Parse command-line arguments:
- Extract project key from first positional argument (e.g.,
OCPSTRAT,OCPBUGS) - Parse optional
--component <component-name>parameter - Parse optional
--label <label-name>parameter - Parse user filter parameters (space-separated emails or names)
- User filters support exclusion by prefixing with an exclamation mark (example: !user@example.com)
- Extract project key from first positional argument (e.g.,
-
If project key is NOT provided:
- Use
getVisibleJiraProjectsto list all accessible projects - Present projects in a numbered list with keys and names
- Ask: "Please enter the number of the project you want to update:"
- Parse response and extract project key
- Use
-
Validate project access:
- Use
searchJiraIssuesUsingJqlwith JQL:project = "{project-key}" AND status != Closed - Verify the project exists and is accessible
- Use
Step 1b. Load Project-Specific Conventions (if available)
After determining the project key, check if project-specific conventions exist that override default behavior. These can change issue type filtering, status format, milestone prioritization, and data gathering JQL.
Known project mappings:
| Project Key | Source | Key Overrides |
|---|---|---|
| ARO | Read ../reference/aro-hcp.md | Only Features/Initiatives; milestone tiers (HPSTRAT-63/130); prepend format with date stamp |
| CNTRLPLANE | Read ../reference/cntrlplane.md | CNTRLPLANE-specific conventions |
| GCP | Read ../reference/gcp-hcp.md | GCP HCP team requirements |
| OCPBUGS | Read ../reference/ocpbugs.md | OCPBUGS bug conventions |
Implementation:
- Match the resolved project key against the table above
- If a match is found, load the conventions using the source method shown (either
Readthe reference file or invoke theSkill) - The loaded conventions override the defaults in this command for:
- Issue type filter: Which issue types to process (e.g., ARO → only Features and Initiatives)
- Issue discovery: How to find target issues (e.g., ARO → milestone-based JQL instead of generic component query)
- Status format: How to format the status update (e.g., ARO → prepend with date stamp instead of replace)
- Update method: How to write to Jira (e.g., ARO → ADF via REST API)
- If no match is found, use default behavior (all issue types, generic component query, replace format)
IMPORTANT: The project-specific conventions MUST be loaded before Step 2 (component selection) and before Step 4 (data gathering), because they can change both the JQL used and the issue types collected.
Step 2. Determine Target Component(s)
-
If
--componentparameter is provided:- Use the component name directly
-
If
--componentis NOT provided:- Query component values through
searchJiraIssuesUsingJqlwithfields=componentsand JQLproject = "{project-key}" AND status != Closed - Extract all unique component names from the search results
- Present components in a numbered list
- Ask: "Please enter the number(s) of the component(s) you want to update (space-separated), or press Enter to skip:"
- If multiple components selected, process each separately
- Query component values through
Step 3. Resolve User Identifiers
For each user filter parameter:
-
Check if it's an email (contains
@): Use as-is for script parameter -
If it's a display name (doesn't contain
@):- Use
lookupJiraAccountIdwith the name as the search string - Show found user details and ask for confirmation
- If confirmed, use the email address; if not, ask for email directly
- Use
-
Handle exclusion prefix (exclamation mark):
- Strip the prefix before lookup
- Use
--exclude-assigneeparameter for the script
Step 4. Run Data Gatherer Script
Execute the Python data gatherer with the resolved parameters:
python3 {plugins-dir}/jira/skills/status-analysis/scripts/gather_status_data.py \
--project {PROJECT-KEY} \
--component "{COMPONENT-NAME}" \
--label "{LABEL-NAME}" \
--assignee {email1} --assignee {email2} \
--exclude-assignee {excluded-email} \
--verbose
When the root selection needs filters this command does not model (target
version, fix version, issue type, or any other JQL predicate), pass a complete
query with --jql instead of --project/--component/--label/--assignee:
python3 {plugins-dir}/jira/skills/status-analysis/scripts/gather_status_data.py \
--jql 'project = OCPSTRAT AND assignee = "me@example.com" AND cf[10855] = "openshift-5.1" ORDER BY rank ASC' \
--verbose
--jql is used verbatim and replaces the entire built-in query, including the
status != Closed and status != "Release Pending" guards, so the query must
express any status filtering it wants. --issue overrides --jql.
Script location: plugins/jira/skills/status-analysis/scripts/gather_status_data.py
Script output:
- Directory:
.work/weekly-status/{YYYY-MM-DD}/ manifest.json: Processing config and issue listissues/{ISSUE-KEY}.json: Per-issue data with descendants and PRs
Wait for script completion and verify output exists before proceeding.
Step 5. Verify Data Collection
Read the manifest file to confirm successful collection:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Data Collection Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Issues found: {count}
Descendants: {count}
PRs collected: {count}
Date range: {start} to {end}
Output: .work/weekly-status/{date}/
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase 2: Issue Processing (Interactive)
Process each issue one at a time, loading fresh context for each.
Step 6. Load Required Skill
This step is mandatory before processing any issues:
Skill(jira:status-analysis)
This loads the Status Analysis Engine skill which provides:
- Activity analysis methodology
- R/Y/G status formatting rules
- Health status determination logic
Step 7. Process Each Issue
For each issue listed in the manifest:
a. Read Pre-Gathered Data
Use the summarize_issue.py script to extract a structured, human-readable summary from the pre-gathered JSON. This avoids reading large JSON files directly (which can exceed context limits) and produces output optimized for LLM analysis.
python3 {plugins-dir}/jira/skills/status-analysis/scripts/summarize_issue.py \
{ISSUE-KEY} --date-dir .work/weekly-status/{date}
The script outputs a structured summary with sections for:
- Issue header (key, summary, status, assignee, current status summary)
- Descendants (total, completion %, by-status breakdown, updated in range)
- Changelog entries (formatted as
date by author: field: old -> new) - Comments (non-bot only, with body truncated to 300 chars)
- PRs (active in range, merged this week, open)
Script location: plugins/jira/skills/status-analysis/scripts/summarize_issue.py
The underlying JSON file is at .work/weekly-status/{date}/issues/{ISSUE-KEY}.json if you need to read additional details not shown in the summary.
b. Analyze Activity (using Status Analysis Engine)
Using the pre-gathered data, apply the activity analysis rules from activity-analysis.md:
-
Identify key events from changelog_in_range:
- Status transitions
- Assignee changes
- Priority changes
-
Analyze comments (excluding bots with
is_bot: true):- Look for blockers, risks, achievements
- Note significant updates
-
Analyze PR activity:
- PRs with
commits_in_range > 0(active development) - PRs with
reviews_in_range > 0(review activity) - Recently merged PRs (
state: MERGED) - Draft PRs awaiting work
- PRs with
-
Determine health status:
- Green: Good progress, PRs merged/in review, no blockers
- Yellow: Minor concerns, slow progress, manageable blockers
- Red: Significant blockers, no progress, major risks
c. Generate Status Update
Use ryg_field (native ADF JSON) by default. Select ryg_field_markdown only
when an external caller explicitly requests a draft and owns a verified
Markdown-to-ADF converter (an external Herald-style client). This plugin does
not bundle or perform conversion. Never improvise conversion or send a draft
string as the field value. See the canonical
external conversion boundary and source references.
For draft PR references, qualify only unambiguously confirmed evidence; otherwise
retain the original text exactly verbatim, add no repository or link, and do not
guess or request human input.
For ryg_field, format the status content as native ADF (Atlassian Document Format) JSON — a nested bulletList with three top-level items: Color Status, Status summary (with nested bullet items), and Risks (with nested bullet items). The gathered issue.current_status_summary value is the raw ADF document, not Markdown; use the summary script's rendered text only for review, and retain the raw document when project-specific guidance requires history preservation.
Logical structure:
- Color Status: {Red, Yellow, Green}
- Status summary:
- Thing 1 that happened since last week
- Thing 2 that happened since last week
- Risks:
- Risk 1 (or "None at this time")
d. Present to User for Review
If Status Summary was updated within last 24 hours:
⚠️ WARNING: This issue's Status Summary was last updated X hours ago (on YYYY-MM-DD at HH:MM).
Current Status Summary:
{current-status-text}
Ask: "This issue was recently updated. Do you want to skip it? (yes/no/show-proposed)"
For all issues (or if proceeding after warning):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Issue: {ISSUE-KEY} - {Summary}
Assignee: {Assignee Name}
Current Status: {Current Issue Status}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Recent Activity Analysis:
• Descendants: {total} total, {updated_in_range count} updated this week
• Completion: {completion_pct}% ({by_status breakdown})
• PRs: {count} ({merged} merged, {open} open, {draft} drafts)
• Commits in range: {total commits across PRs}
• Reviews in range: {total reviews across PRs}
Current Status Summary:
{existing-status-text-or-"None"}
Proposed Status Update:
{drafted-status-update}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Options:
approveora: Proceed with the proposed updatemodifyorm: Modify the text (prompt for new text)skipors: Skip this issue and move to nextquitorq: Stop processing remaining issues
If user chooses modify:
- Show the proposed text in an editable format
- Ask: "Please provide your updated status text (maintain the bullet format):"
- Validate the selected representation against
formatting.md:ryg_fieldrequires valid native ADF JSON with the expected list structure and color; never apply a text-prefix check to an ADF document.ryg_field_markdownrequires exactly one Color Status line first (* Color Status: Red,* Color Status: Yellow, or* Color Status: Green), standard nested Markdown bullets, and qualified PR links agreeing with confirmed evidence URLs. Retain unknown/issue references exactly verbatim without adding links or requesting input. - If the user edits the rendered display text for
ryg_field, reconstruct and validate the native ADF document rather than treating the display as field data. - Show modified version and ask for final confirmation
e. Update the Issue
For an explicitly selected ryg_field_markdown draft, the external client must
convert it and validate the new status-entry document before PUT: type: "doc",
version: 1, one top-level bulletList with exactly three listItem nodes;
Color Status: plus exactly one of Red/Yellow/Green first, then Status summary:
and Risks: each with a nonempty nested bulletList, and no empty text nodes.
Use all native validation gates,
then apply required raw-ADF history preservation. Stop if conversion, validation,
or required history support is unavailable. This plugin does not perform that
conversion; Herald's normalized readback comparison is not a schema validator or
an ARO history guarantee. Never pass the draft as a custom field value or assume
contentFormat: "markdown" converts it. Apply the same raw ADF history
preservation rules below to both paths.
Use editJiraIssue with contentFormat: "adf" to set customfield_10814 (Status Summary). This field requires an ADF (Atlassian Document Format) JSON document — passing a plain string (even with contentFormat: "markdown") will fail with "Operation value must be an Atlassian Document". For ARO, follow the loaded project guidance: prepend the new ADF entry nodes to issue.current_status_summary.content; do not replace history with the rendered display text.
Construct the ADF as a bulletList with three top-level listItem nodes. The Status summary and Risks items each contain a nested bulletList for their sub-items.
editJiraIssue(
cloudId: "redhat.atlassian.net",
issueIdOrKey: "{ISSUE_KEY}",
contentFormat: "adf",
fields: {
"customfield_10814": {
"type": "doc",
"version": 1,
"content": [{
"type": "bulletList",
"content": [
// Item 1: Color Status
{"type": "listItem", "content": [
{"type": "paragraph", "content": [
{"type": "text", "text": "Color Status: Green"}
]}
]},
// Item 2: Status summary with nested bullets
{"type": "listItem", "content": [
{"type": "paragraph", "content": [
{"type": "text", "text": "Status summary:"}
]},
{"type": "bulletList", "content": [
{"type": "listItem", "content": [
{"type": "paragraph", "content": [
{"type": "text", "text": "Achievement or progress item 1"}
]}
]},
{"type": "listItem", "content": [
{"type": "paragraph", "content": [
{"type": "text", "text": "Achievement or progress item 2"}
]}
]}
]}
]},
// Item 3: Risks with nested bullets
{"type": "listItem", "content": [
{"type": "paragraph", "content": [
{"type": "text", "text": "Risks:"}
]},
{"type": "bulletList", "content": [
{"type": "listItem", "content": [
{"type": "paragraph", "content": [
{"type": "text", "text": "None at this time"}
]}
]}
]}
]}
]
}]
}
}
)
Display confirmation: ✓ Updated {ISSUE-KEY}
Step 8. Summary Report
After processing all issues (or if user quits early):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Weekly Status Update Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Project: {PROJECT-KEY}
Component: {COMPONENT-NAME or "All components"}
Label Filter: {LABEL or "None"}
Date Range: {start} to {end}
Total Issues Found: {total}
Issues Updated: {updated-count}
• Green: {green-count}
• Yellow: {yellow-count}
• Red: {red-count}
Issues Skipped: {skipped-count}
• Recently updated: {recent-count}
• User skipped: {user-skip-count}
Updated Issues:
{list-of-updated-issue-keys-with-links}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Data Gatherer Script
The Python script (gather_status_data.py) handles efficient batch data collection:
Features
- Async HTTP requests using aiohttp for parallel fetching
- Jira rate limiting: 2 concurrent requests, 300ms delays
- GitHub GraphQL batching: Up to 30 PRs per request with retry logic
- Date range filtering: Only includes activity within the specified period
Environment Variables
JIRA_API_TOKEN: Atlassian API token (create at https://id.atlassian.com/manage-profile/security/api-tokens)JIRA_USERNAME: Atlassian account email
GITHUB_TOKENorgh auth token: GitHub access token
Output Structure
.work/weekly-status/{YYYY-MM-DD}/
├── manifest.json # Config and issue list
└── issues/
├── OCPSTRAT-1234.json # Per-issue data
├── OCPSTRAT-1235.json
└── ...
Per-Issue JSON Schema
{
"issue": {
"key": "string",
"summary": "string",
"status": "string",
"assignee": {"email": "string", "name": "string"},
"current_status_summary": "ADF document object|null",
"last_status_summary_update": "string|null"
},
"descendants": {
"total": "number",
"by_status": {"status_name": "count"},
"updated_in_range": [
{"key": "string", "summary": "string", "status": "string", "updated": "string"}
],
"completion_pct": "number"
},
"changelog_in_range": [
{"date": "string", "author": "string", "items": [...]}
],
"comments_in_range": [
{"author": "string", "date": "string", "body": "string", "is_bot": "boolean"}
],
"prs": [
{
"url": "string",
"number": "number",
"title": "string",
"state": "OPEN|CLOSED|MERGED",
"is_draft": "boolean",
"review_decision": "string|null",
"dates": {"created_at": "string", "updated_at": "string", "merged_at": "string|null"},
"files_changed": {"total": "number", "additions": "number", "deletions": "number"},
"activity_summary": {
"commits_in_range": "number",
"reviews_in_range": "number",
"review_comments_in_range": "number"
}
}
]
}
Return Value
- Updated Issues: Jira issues with refreshed Status Summary fields
- Summary Report: Console output showing update statistics and issue links
- User Interaction Log: Clear feedback on each decision point
Examples
-
With project, component, and label (recommended):
/jira:update-weekly-status OCPSTRAT --component "Hosted Control Planes" --label "control-plane-work"Output: Runs data gatherer, then processes each issue interactively
-
Interactive mode (prompts for project and component):
/jira:update-weekly-statusOutput: Prompts for project selection, then component selection
-
Specify project, auto-select component:
/jira:update-weekly-status OCPSTRATOutput: Prompts for component selection from OCPSTRAT components
-
With label filter:
/jira:update-weekly-status OCPSTRAT --label strategic-workOutput: Prompts for component, filters issues with "strategic-work" label
-
With specific users (by email):
/jira:update-weekly-status OCPBUGS antoni@redhat.com jdoe@redhat.comOutput: Only processes issues assigned to Antoni or Jane
-
With excluded users (by email):
/jira:update-weekly-status OCPSTRAT !manager@redhat.comOutput: Processes all issues except those assigned to manager@redhat.com
-
With usernames (requires confirmation):
/jira:update-weekly-status OCPSTRAT "Antoni Segura" "Jane Doe"Output: Looks up users by name, asks for confirmation, then processes their issues
-
Full example with all options:
/jira:update-weekly-status OCPSTRAT --component "Control Plane" --label strategic-work antoni@redhat.com !dave@redhat.comOutput: Processes OCPSTRAT issues in "Control Plane" component with "strategic-work" label, assigned to Antoni, excluding Dave
Arguments
project-key(optional): The Jira project key (e.g.,OCPSTRAT,OCPBUGS). If not provided, prompts for selection--component <name>(optional): Filter by specific component name. If not provided, prompts for selection--label <label-name>(optional): Filter by specific label (e.g.,control-plane-work,strategic-work)user-filters(optional): Space-separated list of user emails or display names- Prefix with exclamation mark to exclude specific users (example: !manager@redhat.com)
- Display names without @ symbol will trigger user lookup with confirmation
Notes
Important Implementation Details
-
Two-Phase Execution:
- Phase 1 (Data Gathering): Python script collects all data efficiently in parallel
- Phase 2 (Processing): LLM analyzes each issue with clean context
-
Efficiency:
- Batch data gathering minimizes API calls
- Pre-filtered data (date range) reduces context size
- Each issue processed with fresh context for better analysis
-
User Experience:
- Always warn about recently updated issues (last 24 hours)
- Recommend skipping recently updated issues
- Allow user to modify status text
- Provide clear progress indicators for batch processing
- Show issue links in final summary for easy navigation
-
Error Handling:
- Invalid project key: Display error with available projects
- Invalid component: Display available components
- User lookup fails: Ask for email directly
- Script execution failure: Display error and suggest checking environment variables
- API errors during update: Display error and continue with next issue
-
Format Validation:
- Validate Status Summary text format before updating
- Ensure the value is a valid ADF JSON document with the correct
bulletList/listItemstructure - Check for Color Status line (Red/Yellow/Green)
- Warn if format doesn't match expected template
Prerequisites
- Python 3.8+ with
aiohttppackage installed - Jira MCP server configured and accessible
- Environment variables:
JIRA_API_TOKEN: Atlassian API token (create at https://id.atlassian.com/manage-profile/security/api-tokens)JIRA_USERNAME: Atlassian account emailGITHUB_TOKENor authenticatedghCLI
Check for required tools:
# Check Python and aiohttp
python3 -c "import aiohttp; print('aiohttp OK')"
# Check if the Jira credentials are defined
test -n "$JIRA_API_TOKEN" && test -n "$JIRA_USERNAME"
# Check GitHub token (via gh CLI)
gh auth token &> /dev/null
Install aiohttp if needed:
pip install aiohttp
Customization for Different Teams
Teams can customize this command by:
- Creating project-specific skills with default label filters
- Defining team-specific Status Summary field mappings (modify
--status-fieldparameter) - Customizing color status thresholds based on team velocity
- Adding team-specific keywords for risk/blocker detection
See the Jira plugin's skills directory for examples of project-specific customizations.
Related
- Shared skill:
plugins/jira/skills/status-analysis/SKILL.md - Data gatherer script:
plugins/jira/skills/status-analysis/scripts/gather_status_data.py - Issue summarizer script:
plugins/jira/skills/status-analysis/scripts/summarize_issue.py - Single-issue rollup:
/jira:status-rollup- Generate comprehensive status comment for one issue - Feature updates:
/jira:generate-feature-updates- Generate strategic feature updates for weekly status documents
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.
High-Level Workflow
-
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
-
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
-
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)
-
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
- Validate all proposed blockers for a target version:
/jira:validate-blockers 4.21
Component-Based Validation
- Validate blockers for a specific component and version:
/jira:validate-blockers 4.21 "Hypershift"
Single Bug Validation
- Validate a specific proposed blocker (version not required):
/jira:validate-blockers --bug OCPBUGS-36846
Output Format
The command outputs a blocker validation report:
# 🚫 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.YandX.Y.0in 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.214.22- Validates active proposed blockers for 4.22
Note: Not required when
--bugis provided. - Expands version to search for both
-
$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
--bugis provided. Requirestarget-versionto 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
--bugis provided, target-version and component-filter are ignored.Default: Not specified
Return Value
- Markdown Report: Blocker validation report with recommendations
- Exit Code:
0- Success1- Error querying JIRA or analyzing bugs
Prerequisites
- Jira MCP server must be configured (see plugin README)
- 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
Name
jira:validate-bug
Synopsis
/jira:validate-bug <PR-URL | PR-number | JIRA-key> [--branch release-4.X|main|master]
Description
The jira:validate-bug command diagnoses why the Prow jira/invalid-bug label was applied to a PR. It runs the same 7 validation checks as the jira-lifecycle-plugin, reports pass/fail for each check, and offers to fix failing checks via JIRA MCP tools.
This command is essential for:
- Diagnosing why a PR is stuck with
jira/invalid-bug - Understanding which JIRA fields need correction
- Fixing JIRA bugs in-place without manual field hunting
- Batch-diagnosing multiple blocked PRs
Key Features
- 7-Check Validation — Same checks as the Prow plugin: open state, target version, valid status, release notes, dependent bug states, dependent target versions, dependents exist
- PR-Aware — Accepts PR URLs/numbers, auto-extracts JIRA key from title and branch context
- Fix Mode — After diagnosis, offers to fix failing checks via JIRA MCP tools
- Branch-Aware — Computes expected target version and dependent version from the PR's base branch
Implementation
For detailed implementation guidance, see the validate-bug skill.
High-Level Workflow
- Resolve Input — Parse PR URL/number or JIRA key. Extract JIRA key from PR title and target branch via
gh pr view. - Gather Data — Fetch the JIRA bug with all fields via MCP. Follow issue links to find dependent bugs.
- Validate — Run all 7 checks against the branch-specific expected values. Produce a pass/fail results table.
- Report — Render results matching the jira-lifecycle-plugin bot comment format, with fix instructions for each failure.
- Offer Fixes — List fixable failures, ask for confirmation, then apply fixes via MCP tools.
Usage Examples
From PR URL
/jira:validate-bug https://github.com/openshift/hypershift/pull/8811
From PR number (in a repo context)
/jira:validate-bug 8811
From JIRA key with branch
/jira:validate-bug OCPBUGS-85778 --branch release-4.20
Arguments
Core Arguments
-
$1 — input (required) PR URL, PR number, or JIRA issue key.
- PR URL:
https://github.com/{org}/{repo}/pull/{number} - PR number: plain integer (requires current directory to be inside a git repo)
- JIRA key:
OCPBUGS-12345,DFBUGS-456,PROJQUAY-789
- PR URL:
-
--branch (optional) Target branch override. Required when input is a JIRA key (no PR context). Format:
release-4.X,main, ormaster.
Output Format
Validating OCPBUGS-85778 against branch release-4.20...
| # | Check | Expected | Actual | Result |
|---|------------------------------|-----------------------|------------------|--------|
| 1 | Bug is open | Open | Open | PASS |
| 2 | Target version | 4.20.z | 5.0 | FAIL |
| 3 | Valid state | NEW/ASSIGNED/POST | Verified | FAIL |
| 4 | Release notes | Set (not template) | Not set | FAIL |
| 5 | Dependent bug states | VERIFIED/CLOSED/... | — | SKIP |
| 6 | Dependent bug target version | 4.21.0 or 4.21.z | — | SKIP |
| 7 | Dependents exist | At least one | None | FAIL |
Failures:
1. Target version: Set to 4.20.z (current: 5.0)
2. Status: Transition to NEW, ASSIGNED, or POST (current: Verified)
3. Release notes: Set release note text (current: empty)
4. Dependents: Create or link a dependent bug targeting 4.21.0 or 4.21.z
Fix 4 issues? [y/N]
Prerequisites
ghCLI authenticated with GitHub- Jira MCP server configured (Atlassian Rovo MCP)
- Read access to JIRA (for diagnosis)
- Write access to JIRA (for fix mode)
Return Value
- Markdown Report: Validation results table with fix instructions
- On fix: updated JIRA fields, confirmation to run
/jira refreshon the PR
MCP servers 1
Sponsors
Details
- Marketplace
- openshift-eng/ai-helpers
- Source
- plugins/jira
- Category
- Productivity
- Keywords
- jira, tickets, issues, project-management
More from openshift-eng/ai-helpers
All 56- lvmsv0.1.1
- marketplace-opsv0.1.2
- metricsv0.3.0
- must-gatherv0.0.3
- native-notificationsv0.0.2
- nid-teamv0.2.2
- nodev0.0.3
- node-bugv0.0.3
- node-cvev0.0.8
- node-onboardingv0.0.3
- node-rpmv0.0.3
- node-teamv1.0.1
- node-tuningv1.0.1
- olmv0.1.3
- olm-teamv0.2.1
- openshiftv0.0.8
- openshift-developerv1.1.42
- openshift-tls-profilev0.0.2
- operator-dashboardv0.0.1
- originv0.0.2
- ote-migrationv0.0.3
- patternfly
- prodsec-skillsv1.0.0
- prow-agentv0.0.7
