A plugin to automate tasks with Jira

version
0.9.8
GitHub stars
123

Install

/plugin install jira@ai-helpers

Run it inside Claude Code after adding the marketplace with /plugin marketplace add openshift-eng/ai-helpers.

Contents

Discovered from source

Skills 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. Requires aiohttp. 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 TypeShort Description
Associate Wellness & DevelopmentOnboarding, training, AI learning, conferences, team health
Incidents & SupportProduction incidents, customer escalations, on-call
Security & ComplianceCVEs, weaknesses, FedRAMP, compliance, security tooling
Quality / Stability / ReliabilityBugs, SLOs, chores, tech debt, toil reduction, PMR actions
Future SustainabilityProactive architecture, productivity improvements, upstream, enablement
Product / Portfolio WorkNew 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:

  1. Attempt to call searchJiraIssuesUsingJql with a simple query (e.g., jql: "project = OCM", maxResults: 1)
  2. 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."
  3. 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_10464 is 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.

  1. Run the validation script:
    bash plugins/jira/skills/categorize-activity-types/scripts/validate-classifications.sh .work/activity-type-classifier/classifications.json
    
  2. Fix any validation errors before proceeding
  3. 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
    
  4. Display the report summary to the user

Phase 4: Apply Updates

Single-Issue Mode with --auto-apply
  • If --auto-apply flag 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
  1. Ask the user for explicit approval before modifying any Jira issues
  2. If --dry-run flag is present, skip this phase entirely
  3. Max 2 concurrent MCP update calls to avoid rate limiting
  4. Report progress every 10 issues
  5. On error: log the failure, continue with remaining issues
  6. 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:

  1. Read carefully — consider summary, description, labels, comments, and linked issues
  2. Business intent over technical details — a Kubernetes refactoring driven by product requirements is "Product / Portfolio Work", not "Future Sustainability"
  3. Security always wins — if an issue involves CVEs, vulnerabilities, compliance, or security tooling, classify as "Security & Compliance" regardless of other aspects
  4. Primary purpose — when an issue spans multiple categories, choose the one that best matches the primary motivation
  5. Confidence levels:
    • High — clear match, unambiguous indicators
    • Medium — reasonable match but some ambiguity
    • Low — uncertain, multiple categories could apply
  6. 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

FilePurposeWhen to Read
resources/activity-type-guidance.mdFull Sankey category definitions and subcategoriesPhase 2 (classifying)
resources/report-template.mdReport format referencePhase 3 (report generation)
scripts/validate-classifications.shValidate classifications JSONPhase 3 (validation)
scripts/generate-report.pyGenerate markdown report from JSONPhase 3 (report generation)
scripts/cleanup.shRemove data artifacts, preserve reportsPost-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:

  1. Fetch the bug via getJiraIssue with the issue key and responseContentFormat: "markdown".

  2. Parse the response:

    • Extract issuetype.name - verify it's "Bug"
    • Extract description - full bug description text
    • Extract issuelinks - array of linked issues
    • Extract customfield_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
  3. Validate issue type:

    • If issuetype.name != "Bug", show warning:
      Warning: {issue-key} is not a Bug (it's a {issuetype.name}).
      Release notes are typically for bugs. Continue anyway? (yes/no)
      
    • If user says no, exit without making changes
  4. Check if release note already exists:

    • If customfield_10783 is not empty, show warning:
      This bug already has a release note:
      ---
      {existing release note}
      ---
      
      Do you want to regenerate it? (yes/no)
      
    • If user says no, exit without making changes

Step 2: Parse Bug Description for Cause and Consequence

Objective: Extract the required Cause and Consequence sections from the bug description.

Bug Description Format:

Jira bug descriptions often follow this structure:

Description of problem:
{code:none}
<problem description>
{code}

Cause:
{code:none}
<root cause>
{code}

Consequence:
{code:none}
<impact>
{code}

Version-Release number of selected component (if applicable):
...

How reproducible:
...

Steps to Reproduce:
...

Actual results:
...

Expected results:
...

Parsing Strategy:

  1. Look for "Cause:" section:

    • Search for the string "Cause:" (case-insensitive)
    • Extract text between "Cause:" and the next major section
    • Remove Jira markup: {code:none}, {code}, etc.
    • Trim whitespace
  2. Look for "Consequence:" section:

    • Search for the string "Consequence:" (case-insensitive)
    • Extract text between "Consequence:" and the next major section
    • Remove Jira markup
    • Trim whitespace
  3. Alternative patterns:

    • Some bugs may use "Root Cause:" instead of "Cause:"
    • Some bugs may use "Impact:" instead of "Consequence:"
    • Try variations if exact match not found
  4. Handle missing sections:

    • If Cause is missing:
      Bug description is missing the "Cause" section.
      
      Would you like to:
      1. Provide the Cause interactively
      2. Update the bug description in Jira first
      3. Cancel
      
    • If Consequence is missing:
      Bug description is missing the "Consequence" section.
      
      Would you like to:
      1. Provide the Consequence interactively
      2. Update the bug description in Jira first
      3. Cancel
      
  5. Interactive input (if user chooses option 1):

    • Prompt: "What is the root cause of this bug?"
    • Collect user input
    • Use as Cause value
    • Repeat for Consequence if needed

Example Parsing:

Input:

Description of problem:
{code:none}
The control plane operator crashes when CloudProviderConfig.Subnet is not specified
{code}

Cause:
{code:none}
hostedcontrolplane controller crashes when hcp.Spec.Platform.AWS.CloudProviderConfig.Subnet.ID is undefined
{code}

Consequence:
{code:none}
control-plane-operator enters a crash loop
{code}

Output:

Cause: "hostedcontrolplane controller crashes when hcp.Spec.Platform.AWS.CloudProviderConfig.Subnet.ID is undefined"
Consequence: "control-plane-operator enters a crash loop"

Step 3: Extract Linked GitHub PRs

Objective: Find all GitHub PR URLs associated with this bug.

Sources to check (in priority order):

  1. Remote Links (Primary source - web links in Jira):

    • Check the Jira issue response for web links
    • Field name varies: remotelinks, or issuelinks with outward GitHub PR links
    • Extract GitHub PR URLs matching pattern: https://github\.com/[\w-]+/[\w-]+/pull/\d+
    • IMPORTANT: Never use gh issue view {JIRA-KEY} - Jira keys are NOT GitHub issue numbers
  2. Bug Description:

    • Scan the description field for GitHub PR URLs
    • Use regex: https://github\.com/([\w-]+)/([\w-]+)/pull/(\d+)
    • Extract and parse all matches
    • IMPORTANT: Only extract full PR URLs, not issue references
  3. Bug Comments:

    • Iterate through comment.comments array
    • For each comment, scan body field for GitHub PR URLs
    • Use same regex pattern
    • Extract all matches
  4. Search by bug number (Fallback if no PR URLs found):

    • If no PRs found via links, search GitHub for PRs mentioning the bug
    • For OCPBUGS: Try common OpenShift repos:
      for repo in "openshift/hypershift" "openshift/cluster-api-provider-aws" "openshift/origin"; do
        gh pr list --repo "$repo" --search "{issue-key} in:title,body" --state all --limit 10 --json number,url,title
      done
      
    • Display found PRs and ask user to confirm which are relevant:
      Found PRs mentioning {issue-key}:
      1. openshift/hypershift#4567 - Fix panic when CloudProviderConfig.Subnet is undefined
      2. openshift/hypershift#4568 - Add tests for Subnet validation
      
      Which PRs should be included in the release note? (enter numbers separated by commas, or 'all')
      
    • IMPORTANT: Never use gh issue view {JIRA-KEY} - this will fail

URL Parsing:

For each found URL https://github.com/openshift/hypershift/pull/4567:

  • Extract org: "openshift"
  • Extract repo: "hypershift"
  • Extract pr_number: "4567"
  • Store as: {"url": "...", "repo": "openshift/hypershift", "number": "4567"}

Deduplication:

  • Keep only unique PR URLs
  • If same PR is mentioned multiple times, include it only once

Validation:

  • If no PRs found after all attempts:
    No GitHub PRs found linked to {issue-key}.
    
    Please link at least one PR to generate release notes.
    
    How to link PRs in Jira:
    1. Edit the bug in Jira
    2. Add a web link to the GitHub PR URL
    3. Or mention the PR URL in a comment
    4. Then run this command again
    
    Exit without updating the ticket.

Example:

Found PRs:

[
  {
    "url": "https://github.com/openshift/hypershift/pull/4567",
    "repo": "openshift/hypershift",
    "number": "4567"
  },
  {
    "url": "https://github.com/openshift/hypershift/pull/4568",
    "repo": "openshift/hypershift",
    "number": "4568"
  }
]

Step 4: Analyze Each GitHub PR

Objective: Extract Fix, Result, and Workaround information from each linked PR.

For each PR in the list:

4.1: Fetch PR Details

Command:

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 description
  • commits: Array of commit objects with messages
  • state: 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
  • 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:

  1. API Tokens and Keys:

    • Pattern: (sk|pk)_[a-zA-Z0-9]{20,}
    • Pattern: ghp_[a-zA-Z0-9]{36}
    • Pattern: gho_[a-zA-Z0-9]{36}
    • Pattern: github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59}
  2. AWS Credentials:

    • Pattern: AKIA[0-9A-Z]{16}
    • Pattern: aws_access_key_id\s*=\s*[A-Z0-9]+
    • Pattern: aws_secret_access_key\s*=\s*[A-Za-z0-9/+=]+
  3. Passwords in URLs:

    • Pattern: https?://[^:]+:[^@]+@
    • Example: https://user:password@example.com
  4. JWT Tokens:

    • Pattern: eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+
  5. SSH Private Keys:

    • Pattern: -----BEGIN (RSA|OPENSSH|DSA|EC|PGP) PRIVATE KEY-----
  6. Kubernetes Secrets:

    • Pattern: [a-zA-Z0-9+/]{40,}==? (base64 encoded secrets)
    • Context: If appears after "token:", "secret:", "password:"

Validation logic:

sensitive_patterns = {
    "API Token": r"(sk|pk)_[a-zA-Z0-9]{20,}",
    "GitHub Token": r"gh[po]_[a-zA-Z0-9]{36}",
    "AWS Access Key": r"AKIA[0-9A-Z]{16}",
    "URL with credentials": r"https?://[^:]+:[^@]+@",
    "JWT Token": r"eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+",
    "Private Key": r"-----BEGIN .* PRIVATE KEY-----"
}

for name, pattern in sensitive_patterns.items():
    if re.search(pattern, release_note_text):
        print(f"Security validation failed!")
        print(f"Detected what appears to be {name} in the release note text.")
        print(f"Please review the source PRs and remove any credentials.")
        exit(1)

If validation fails:

Security validation failed!

Detected what appears to be an API token in the release note text.

This may have come from:
- PR description
- Commit messages
- Code changes (diff)
- PR comments

Please review the source PRs and remove any credentials before proceeding.

Use placeholder values instead:
- YOUR_API_KEY
- <redacted>
- ********

Aborting release note creation.

Step 8: Select Release Note Type

Objective: Determine the appropriate Release Note Type for this bug.

Available types (from Jira dropdown):

  1. Bug Fix
  2. Release Note Not Required
  3. Known Issue
  4. Enhancement
  5. Rebase
  6. Technology Preview
  7. Deprecated Functionality
  8. CVE

Auto-detection strategy:

  1. For OCPBUGS: Default suggestion is "Bug Fix" (most common)

  2. Check for CVE references:

    • If bug description or PRs mention "CVE-" → Suggest "CVE"
  3. Check for deprecation:

    • If PRs mention "deprecated", "deprecating", "removing" → Suggest "Deprecated Functionality"
  4. Check for new features:

    • If PRs add significant new functionality → Suggest "Enhancement"
    • Though typically bugs should be "Bug Fix"
  5. Check for known issues:

    • If PRs don't actually fix the issue, just document it → Suggest "Known Issue"

User interaction:

Use the AskUserQuestion tool:

questions = [{
  "question": "What type of release note is this?",
  "header": "Type",
  "multiSelect": false,
  "options": [
    {
      "label": "Bug Fix",
      "description": "Fix for a defect (most common)"
    },
    {
      "label": "Known Issue",
      "description": "Documents a known problem without a fix"
    },
    {
      "label": "Enhancement",
      "description": "New feature or improvement"
    },
    {
      "label": "CVE",
      "description": "Security vulnerability fix"
    }
  ]
}]

Store selection for use in the next step.

Step 9: Update Jira Ticket

Objective: Write the release note to the Jira ticket.

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:

  1. Permission denied:

    Failed to update {issue-key}.
    
    Error: You do not have permission to edit Release Note fields
    
    Please contact your Jira administrator or manually add the release note.
    
    Generated release note (for manual entry):
    ---
    {release_note_text}
    ---
    
  2. Invalid field value:

    Failed to update Release Note Type field.
    
    Error: Value "{selected_type}" is not valid
    
    Please select a different type or manually update in Jira.
    
  3. Field not found:

    Failed to update {issue-key}.
    
    Error: Field customfield_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:

  1. Log warning for each failed PR
  2. Continue with successfully analyzed PRs
  3. If all PRs fail, treat as "No PRs linked" error
  4. Show summary of what was analyzed:
    Analyzed 2 of 3 linked PRs:
    ✓ PR #123
    ✓ PR #456
    ✗ PR #789 (access denied)
    

Incomplete Bug Description

Problem: Missing Cause or Consequence sections

Recovery:

  1. Offer interactive input option
  2. Provide template for user
  3. Allow user to update bug and retry
  4. Don't proceed without both fields

Ambiguous PR Content

Problem: PRs don't clearly explain the fix

Recovery:

  1. Use PR title as fallback
  2. Analyze code diff more carefully
  3. Ask user for clarification:
    The linked PR doesn't clearly describe the fix.
    
    Based on code analysis, it appears to:
    {best guess from diff}
    
    Is this correct? If not, please describe the fix:
    

Conflicting Information

Problem: Multiple PRs describe different fixes

Recovery:

  1. Present both descriptions to user
  2. Ask which is correct or how to combine
  3. Use AI to attempt intelligent synthesis
  4. If synthesis fails, escalate to user

Best Practices for Implementation

  1. Always validate inputs: Check that issue exists, PRs are accessible, fields are present
  2. On failure, provide helpful error messages with recovery instructions
  3. Be defensive: Handle missing data, API errors, permission issues
  4. Log progress: Show user what's happening at each step
  5. Preserve data: If update fails, show generated content so it's not lost
  6. Security first: Always validate before updating Jira
  7. User in control: Confirm selections, allow overrides

Testing Checklist

  • Bug with single linked PR
  • Bug with multiple linked PRs
  • Bug with no linked PRs (error case)
  • Bug with inaccessible PR (warning case)
  • Bug missing Cause section (error case)
  • Bug missing Consequence section (error case)
  • Bug with existing release note (warning case)
  • Bug that's not a Bug type (warning case)
  • Release note with detected credentials (security failure)
  • Different Release Note Type selections
  • Update permission denied (error case)
  • MCP server not configured (error case)
  • gh CLI not authenticated (error case)

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:

TypeReferenceKey Content
storyStory guideUser story format, acceptance criteria, summary vs description
bugBug guideBug template, steps to reproduce, reproducibility
epicEpic guideEpic Name field, scope/timeline, parent Feature linking
featureFeature guideMarket problem, strategic value, success criteria
initiativeInitiative guideInternal capability, problem statement, internal impact
riskRisk guideQualifying criteria, probability/impact assessment, auto-calculated fields
spikeSpike guideResearch question, time box, investigation approach
taskTask guideTask vs story distinction, action-verb summaries
feature-requestFeature Request guideRFE 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.Y per project conventions.
  • --parent (optional) — Parent issue key for linking (e.g., CNTRLPLANE-123).

Implementation Phases

Phase 1: Load Guidance

  1. Load the type-specific reference file from the table above
  2. Invoke the jira:jira-conventions skill 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:

  1. Summary starts with "As a" or contains "I want" / "so that" → belongs in description
  2. 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)

FieldIDTypeUsage
Epic Namecustomfield_10011StringRequired for Epics; must match summary
Target Versioncustomfield_10855ArrayFormat: [{"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:

CreatingParent Should BeIf Wrong Type
StoryEpicWarn user, ask to confirm or correct
TaskEpicWarn user, ask to confirm or correct
BugEpicWarn user, ask to confirm or correct
SpikeEpicWarn user, ask to confirm or correct
EpicFeature or InitiativeWarn user, ask to confirm or correct
FeatureOutcomeWarn user, ask to confirm or correct
InitiativeOutcomeWarn 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:

  1. Unset the parent: editJiraIssue with {"parent": null}
  2. Change the issue type: editJiraIssue with {"issuetype": {"name": "NewType"}}
  3. Set the new parent if needed: editJiraIssue with {"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

FieldWrongCorrect
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

  1. Use descriptive summaries with relevant keywords for auto-detection
  2. Provide --component and --version flags when known to skip prompts
  3. Use --parent to maintain issue hierarchy
  4. Sanitize content — remove credentials before including logs

Anti-Patterns

  • Wrong type: /jira:create story "Refactor database" → technical work, use task
  • 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 = KEY BFS
  • ✅ 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.md for setup)
  • jq installed 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.json if 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 issue
  • pull_requests: Array of PR objects with url, state, title, isDraft, sources, and found_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:

  1. Fetch issue metadata via getJiraIssue with the issue key, requesting fields summary, description, issuetype, status, comment, and expand: "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 from RemoteIssueLink field changes
  2. Search for descendant issues using BFS via searchJiraIssuesUsingJql with jql: "parent = <issue-key>", fields: ["key"], and maxResults: 100. Recursively search parent = <child-key> for each result until no more children. Only fetch the key field here -- full data (including changelog) is fetched per-issue in Phase 2.

  3. Fetch full data for each issue (including root + all descendants) via getJiraIssue with fields summary, description, issuetype, status, comment, and expand: "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):
    1. Fetch the issue via getJiraIssue with issueIdOrKey and expand: "changelog"
    2. From the response, extract changelog.histories[].items[] entries where field == "RemoteIssueLink"
    3. Parse the toString (or to_string) value of each entry for GitHub PR URLs matching https://github.com/{owner}/{repo}/pull/{number}
    4. Deduplicate the extracted URLs
  • Important:
    • Remote links appear in changelog as RemoteIssueLink field changes
    • Changelog contains link creation events with GitHub PR URLs in toString or to_string field
    • Store results in variables, not temporary files
    • Uses MCP authentication (no separate curl needed)
  • Filters for GitHub PR URLs matching /pull/ or /pulls/ pattern

Source 2: Text Content (backup)

  • Searches both fields.description and fields.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 each comment.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 sources array: ["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_issues array: ["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_requests array (valid result)
  • Too many descendants: If hierarchy has >100 issues, increase maxResults parameter in searchJiraIssuesUsingJql
  • GitHub rate limit: If gh pr view fails due to rate limiting, display error with reset time
  • PR metadata fetch fails: If gh pr view returns 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 paragraph
  • market_problem - Content under "Market Problem"
  • solution - Content under "Proposed Solution"
  • customer_value - Items under "Customer Value"
  • success_criteria - All success criteria sections
  • epics_planned - Epic list
  • out_of_scope - Out of scope items
  • timeline - 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 Summary
  • goals - Goals section
  • acceptance_criteria - Requirements / Acceptance Criteria
  • deployment_considerations - Table of deployment scenarios
  • background - Background section (use as motivation)
  • questions - Open questions
  • docs_considerations - Documentation needs
  • interop_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:

ComponentDirectory
HyperShift, ROSA, AROenhancements/hypershift/
Networkingenhancements/network/
Storageenhancements/storage/
Authenticationenhancements/authentication/
Otherenhancements/ (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 SectionEnhancement SectionTransformation
SummaryTitle (metadata)Convert to kebab-case
OverviewSummaryDirect copy
Market ProblemMotivationDirect copy + context
Customer ValueUser StoriesConvert to "As a... I want... So that..."
Strategic ValueGoalsExtract objectives
Out of ScopeNon-GoalsDirect copy
Proposed SolutionWorkflow DescriptionExpand into step-by-step
Epics (Planned)Implementation DetailsList epics with details
Success CriteriaGraduation CriteriaMap adoption/outcomes to GA criteria
TimelineGraduation CriteriaMap milestones to Dev Preview/Tech Preview/GA
RisksRisks and MitigationsDirect 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 WikiMarkdown
h2. Heading## Heading
h3. Heading### Heading
* bullet* bullet (same)
# numbered1. 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

  1. Complete epic/feature first: Ensure Jira epic or feature has comprehensive content before generation
  2. Review AI-generated content: Enhancement is a starting point, not final document
  3. Add technical depth: Expand implementation details with architecture diagrams, API specs
  4. Iterate with reviewers: Share draft early for feedback
  5. Keep Jira updated: Update epic/feature as enhancement evolves, or regenerate enhancement from updated Jira content
  6. 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 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 KeyConventionsReference
CNTRLPLANERed Hat OpenShift Control Planes — features, epics, stories, tasksCNTRLPLANE conventions
OCPBUGSOpenShift Bugs — bug reports onlyOCPBUGS conventions
GCPGCP Hosted Control Planes (Hypershift on GKE) — stories, epics, tasks, bugs, featuresGCP HCP conventions
TRTTechnical Release Team — story, bug, spike, task and ticket templates, readiness criteria, concision rubricTRT conventions

By Team / Keywords

Detect these keywords in the issue summary, description, or component to layer team-specific conventions on top of project conventions:

KeywordsTeam ConventionsReference
HyperShift, ARO HCP, ROSA HCP, hosted control planeHyperShift team — component selection (HyperShift / ARO, HyperShift / ROSA, HyperShift)HyperShift conventions
GCP HCP, Hypershift on GKE, GKE hosted control planeGCP HCP team — GCP project conventions, team templates, sizing guideGCP HCP conventions

Layering Rules

  1. Project conventions are loaded first based on the project key
  2. Team conventions are layered on top when keywords match
  3. Both can apply simultaneously (e.g., CNTRLPLANE + HyperShift)
  4. If no project or team matches, skip this skill — the issue uses only type-specific guidance from the create skill

How to Use

After identifying the matching conventions:

  1. Read the linked reference file(s)
  2. Apply project-specific custom fields, version handling, and component requirements
  3. Layer team-specific conventions if keywords match (component selection, labels, templates)
  4. Defer to the create skill 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.md for 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:

  1. Save initial directory: INITIAL_DIR=$(pwd) (save at start, before any cd commands)

  2. Check prerequisites: Verify jq and gh CLI are installed and authenticated

    • If missing, display error with installation instructions
  3. Create output directory: WORK_DIR=$INITIAL_DIR/.work/jira/feature-doc/<feature-key> (use mkdir -p)

  4. Fetch main feature via getJiraIssue with the feature key. If MCP is unavailable, display error pointing to plugins/jira/README.md.

  5. Parse response: Extract key, summary, description, issuetype, status

    • If fetch fails, display error and exit
  6. 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:

  1. Filter for MERGED PRs: Only analyze PRs with state == "MERGED" AND isDraft == false

    • Skip OPEN PRs (work in progress)
    • Skip PRs with isDraft == true (not ready for review)
    • Skip CLOSED PRs (not merged)
  2. 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
  3. 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
  4. Handle errors: If PR inaccessible (403, 404), log warning and continue

  5. 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):

  1. Overview: Jira link, status, counts, dates, authors (from main issue + PR metadata)
  2. Background and Goals: Description from main issue (clean Jira formatting)
  3. Architecture and Design: High-level changes, components, design decisions (from PRs)
  4. Implementation Details: Core changes, API changes, configuration (from PR diffs, code snippets)
  5. Usage Guide: Prerequisites, basic/advanced usage (from README updates, PR descriptions)
  6. Testing: Test coverage, strategies, key test PRs
  7. 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:

  1. Overview: Extract from main issue + PR metadata (Jira link, status, counts, dates, authors)
  2. Background: Clean Jira formatting from main issue description
  3. Architecture: Synthesize from PR descriptions and comments (high-level overview, components, decisions with PR links)
  4. Implementation: Group by core changes, API changes, configuration (include code snippets, link to PRs, list key files)
  5. Usage: Extract from README updates and PR descriptions (prerequisites, YAML/CLI examples)
  6. Testing: Summarize by category (unit, E2E, CI), list key test PRs
  7. 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:

  1. Write documentation: Save to ${WORK_DIR}/feature-doc.md with footer:

    ---
    *Generated by `/jira:generate-feature-doc` on <timestamp>*
    *Source: <feature-key> and <count> related issues*
    
  2. Save metadata: Store analysis log with timestamps, counts, output files, errors/warnings

  3. 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 --stat to identify key files
  • Skip vendor/, generated files, test fixtures
  • Fetch full diff only for critical files

Best Practices for AI Implementation

  1. Progress feedback: Show progress after each major step (discovery, PR analysis, etc.)

  2. Error resilience: Don't fail the entire process if one PR is inaccessible

  3. Smart synthesis: Don't just concatenate PR descriptions - synthesize into coherent narrative

  4. Context awareness: Understand the codebase domain (e.g., Kubernetes, OpenShift) to better interpret changes

  5. Structured output: Use consistent markdown formatting with proper headers, code blocks, tables

  6. Link preservation: Always provide clickable links to Jira issues and GitHub PRs

  7. Timestamp tracking: Note when PRs were merged to understand timeline

  8. Author attribution: Credit authors of PRs and issues where relevant

  9. Code examples: Include actual code snippets from PRs to illustrate changes

  10. 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:

  1. Token Protection: Authentication tokens never appear in process listings (ps aux)
  2. History Safety: Tokens are not saved in shell history files
  3. Process Isolation: Token is read from environment variables inside the script
  4. 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 token
  • JIRA_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

  1. Environment Check: Validates that JIRA_URL and authentication token are set
  2. Token Selection: Uses JIRA_API_TOKEN for Atlassian Cloud authentication
  3. Header Injection: Constructs Authorization: Basic <base64> header inside the script using JIRA_USERNAME and JIRA_API_TOKEN
  4. Process Replacement: Uses exec curl to replace the script process with curl
  5. 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)

  1. Visit: https://id.atlassian.com/manage-profile/security/api-tokens
  2. Click "Create API token"
  3. Give it a label (e.g., "CLI Access")
  4. Copy the token
  5. 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

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 --bug flag value (optional, for single bug validation mode)

Project:

  • Hardcoded to "OCPBUGS" project

Validate inputs:

  • If neither --bug nor target-version is provided, error out with message: "Error: Either target-version or --bug must be provided. Usage: /jira:validate-blockers [target-version] [component-filter] [--bug issue-key]"
  • If target version provided, verify it matches pattern X.Y (e.g., "4.21", "4.22")
  • If component filter provided without target version and without --bug, error out

Phase 2: Build JQL Query for Proposed Blockers

Determine query mode:

  1. Single bug mode (if --bug is provided):

    • Skip JQL query construction
    • Use getJiraIssue to fetch the single bug
    • Target version and component filter are ignored in this mode
    • Proceed to analysis with single bug only
  2. Version + component mode (if both target version and component are provided):

    • Build JQL query for proposed blockers matching target version and component filter
    • Continue with query construction below
  3. Version only mode (if only target version provided):

    • Build JQL query for all proposed blockers for the target version
    • Continue with query construction below

Base JQL for proposed blockers:

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 nextPageToken to 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

Workaround Assessment (may affect recommendation):

An acceptable workaround must meet ALL three criteria:

  1. Idempotent - can be applied repeatedly without resulting change
  2. Safe at scale - can be safely deployed to 1000's of clusters without material risk via automation
  3. Timely - SD can implement before release is pushed to more Cincinnati channels (candidate, fast, stable)

If a workaround doesn't meet all three criteria, it's NOT an acceptable workaround.

For each proposed blocker:

  1. Fetch bug details including summary, description, labels, priority, severity, comments
  2. Check for CI-only indicators (REJECT criteria):
    • Check labels: ci-fail, ci-only, test-flake
    • Check summary/description for CI-specific keywords:
      • "CI job", "test failure", "rehearsal", "periodic job", "e2e test", "periodic-ci-"
    • Check comments for explicit CI-only statements:
      • "Won't affect the product"
      • "CI-only"
      • "infrastructure issue"
      • "only affects CI"
    • If CI-only indicators found, recommend REJECT regardless of severity or failure type
  3. Analyze blocker criteria (if not CI-only):
    • Check labels: ComponentReadinessRegression, ServiceDeliveryBlocker, UpgradeBlocker
    • Check severity: Must be Important or higher (Critical/Urgent)
    • Analyze summary/description for keywords:
      • Data loss, corruption, service unavailable
      • Install failure, upgrade failure
      • Regression
    • Identify scope: All platforms vs specific form-factor/configuration
  4. Check for acceptable workarounds:
    • Use expand="renderedFields" to get comment text
    • Search for keywords: "workaround", "work around", "alternative", "bypass"
    • Assess if workaround meets all 3 criteria (idempotent, safe at scale, timely)
  5. Generate recommendation:
    • ✅ APPROVE - Meets automatic/strong blocker criteria, no acceptable workaround
    • ❌ REJECT - CI-only issue, OR severity below Important, OR new feature without regression, OR has acceptable workaround
    • ⚠️ DISCUSS - Edge cases requiring team discussion

Use MCP tools:

  • getJiraIssue with expand="renderedFields" to get comments
  • Analyze comment text for workaround mentions

Phase 5: Generate Validation Report

Create comprehensive Markdown report with all blocker validation results.

Report Structure:

# 🚫 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 searchJiraIssuesUsingJql fails, display JQL query and error message
  • If getJiraIssue fails:
    1. Fallback to WebFetch: Try fetching via https://redhat.atlassian.net/browse/{issue-key}
    2. If WebFetch succeeds: Parse the web page to extract bug details (summary, severity, description) and continue with validation
    3. If WebFetch also fails: Display clear error indicating bug doesn't exist or isn't accessible
  • Provide troubleshooting guidance (check MCP server, verify credentials)

Large result sets (>50 blockers):

  • Show progress indicators during analysis
  • Consider warning user: "Found {count} proposed blockers. This may take a moment to analyze."

Performance Considerations

  • Query optimization: Only fetch proposed blockers (cf[12319940] = "Proposed")
  • Component scoping: Use component filters to reduce result set size
  • Batch operations: Use searchJiraIssuesUsingJql with appropriate maxResults (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 NameField IDJQL NameType
Release Blockercustomfield_10847"Release Blocker"String
Target Versioncustomfield_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:

  1. Deterministic checks via a Python script that verifies structural requirements: required sections exist, are non-empty, and have adequate content.
  2. 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 text
  • fields.summary -- issue title
  • fields.labels -- current labels array (needed for label updates)
  • fields.status.name -- current status
  • fields.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 passed
  • checks: array of individual check results
  • stats: summary counts

Deterministic checks performed by the script:

Check IDNamePass ConditionSeverity
has_contextContext section presentHeading matching: Context, Description, Background, Overview, or WhyREQUIRED
has_acAcceptance Criteria presentHeading matching: Acceptance Criteria, AC, or Definition of DoneREQUIRED
context_not_emptyContext has contentAt least 50 characters below the headingREQUIRED
ac_not_emptyAC has contentAt least 30 characters below the headingREQUIRED
has_techTechnical Details presentHeading matching: Technical Details, Technical Context, Implementation Details, Implementation Notes, or Technical NotesREQUIRED
tech_not_emptyTechnical Details has contentAt least 30 characters below the headingREQUIRED
ac_has_itemsAC has multiple itemsWarns if fewer than 2 bullet points or numbered itemsWARNING
min_description_lengthAdequate overall lengthTotal description at least 200 charactersWARNING

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.

  1. 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")
  2. Implementation Context Sufficiency: Is there enough description of the problem, affected code area, or desired behavior that /jira:solve could 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
  3. 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:

  1. Identify failures: Collect all failed deterministic checks and AI qualitative FAILs from phases 2-4.

  2. 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. Why section from the issue summary and any context in the existing description text.
    • Missing Acceptance Criteria: Generate an h2. Acceptance Criteria section with concrete, testable bullet points derived from the description context.
    • Missing Technical Details: Generate an h2. Technical Details section 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.
  3. 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)"

  4. If confirmed: Update the issue description via editJiraIssue, setting the description field to the revised text with contentFormat: "markdown".

  5. 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.

  6. 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 --fix was 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.

  1. Get current labels from the fetched issue data
  2. Build the updated label list:
    • If PASS: remove not-ready-to-solve (if present), add ready-to-solve
    • If FAIL: remove ready-to-solve (if present), add not-ready-to-solve
  3. Skip update if labels haven't changed
  4. Apply via editJiraIssue, setting the labels field to the updated labels list. Note: The labels field 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

ErrorHandling
Issue not found"Could not find issue {key}. Verify the issue key is correct."
MCP unavailableDisplay error: "Jira MCP server required. Check plugin README for setup."
Python not available"Python 3 is required. Check: which python3"
check_sections.py failsDisplay script error, proceed with AI-only assessment, note in report
Description is null/emptyAutomatic FAIL: "Issue has no description. Add Context and Acceptance Criteria sections."
Comment post/edit failsDisplay warning but still proceed with label application and report. Non-fatal.
Label update failsDisplay 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 fixReport the new failures. The fix improved but did not fully resolve all issues.

Examples

  1. Basic usage:

    /jira:ready-to-solve OCPBUGS-12345
    
  2. Dry run (no label changes):

    /jira:ready-to-solve OCPBUGS-12345 --dry-run
    
  3. Verbose output:

    /jira:ready-to-solve OCPBUGS-12345 --verbose
    
  4. 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:

ModuleFilePurpose
Data Collectiondata-collection.mdReading pre-gathered JSON or fetching via MCP
Activity Analysisactivity-analysis.mdDetecting blockers, progress, risks, completion
External Linksexternal-links.mdGitHub PR and GitLab MR integration
Formattingformatting.mdOutput templates for different modes
Data Gathererscripts/gather_status_data.pyAsync batch data collection (update-weekly-status)
Issue Summarizerscripts/summarize_issue.pyCompact summaries of pre-gathered issue JSON
Issue Triagescripts/triage_issues.pyBatch triage of pre-gathered issue directories
Feature Update Validatorscripts/validate_feature_updates.pyValidate generated feature-update markdown

Configuration Parameters

Both commands share the same engine with different configuration:

Parameterstatus-rollupupdate-weekly-statusgenerate-feature-updates
data_sourceMCP API callsPre-gathered JSON filesPre-gathered JSON files
root_issuesSingle issue keyMultiple (from manifest.json)Multiple (from manifest.json)
date_range.startUser-specified or issue creationtoday - 7 daystoday - 7 days
date_range.endUser-specified or todaytodaytoday
output_formatmarkdown_commentryg_field (default native ADF); ryg_field_markdown (explicit draft opt-in)feature_markdown
output_targetComment on root issueStatus Summary fieldstdout
external_linksVia gh CLIPre-gathered in JSONPre-gathered in JSON
user_reviewYes (before posting comment)Yes (approve/modify/skip per issue)Yes (full-section review)
cachingTemp file for refinementJSON 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):

  1. Read manifest from .work/weekly-status/{date}/manifest.json
  2. For each issue, read .work/weekly-status/{date}/issues/{ISSUE-KEY}.json
  3. Data includes: issue metadata, descendants, changelogs, comments, PRs (all pre-filtered to date range)

Option B: Direct MCP Calls (status-rollup)

  1. For each root issue:

    • Fetch issue details with fields=summary,status,assignee,issuelinks,comment,{custom-fields}
    • Fetch changelog with expand=changelog
  2. 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)
  3. For each descendant issue:

    • Fetch issue details and changelog
    • Track which descendants were updated within date range
  4. Build IssueActivityData for root and all descendants

  5. Optionally cache to temp file (for refinement workflows)

Step 3: Activity Analysis

Follow activity-analysis.md to:

  1. Filter to date range:

    • Changelog entries within [start_date, end_date]
    • Comments created within [start_date, end_date]
  2. Identify key events:

    • Status transitions (especially: started, completed, blocked)
    • Assignee changes
    • Priority/severity changes
  3. 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"
  4. 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
  5. Calculate metrics:

    • Total/completed/in-progress/blocked descendants
    • Completion percentage

Step 4: External Links (if enabled)

Follow external-links.md to:

  1. Extract GitHub PR URLs:

    • From issuelinks field (remote links)
    • From description and comments (text parsing)
    • From descendants' links
  2. Fetch PR metadata (if gh CLI available):

    gh pr view {PR-NUMBER} --repo {REPO} --json state,updatedAt,mergedAt,title
    
  3. Track PR activity:

    • PRs merged within date range
    • PRs updated within date range
    • Open PRs awaiting review
  4. Handle GitLab MRs:

    • Extract URLs, note for manual checking
    • Use glab if 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:

ErrorHandling
Issue not foundLog warning, skip issue, continue with others
Permission deniedDisplay clear error, suggest checking MCP config
No activity in date rangeGenerate summary based on current state
GitHub CLI not availableSkip PR analysis, note in output
Rate limitingDisplay error with retry guidance
Large hierarchies (100+ issues)Show progress indicators
Missing JSON fileLog 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=changelog in getJiraIssue calls
  • BFS hierarchy traversal: Use parent = KEY per level with recursive BFS (Cloud-compatible replacement for childIssuesOf())
  • 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 NameField IDTypePurpose
Status Summarycustomfield_10814ADF (rich text)Stores R/Y/G status as ADF JSON; requires contentFormat: "adf"

Prerequisites

For update-weekly-status

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

FieldCustom Field IDJQL Name
Target Versioncustomfield_10855"Target Version"
Release Note Textcustomfield_10783—
Release Note Typecustomfield_10785—
Severitycustomfield_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.

#CheckWhat it validates
1Bug is openStatus is not "Closed"
2Target version matches branchBug's Target Version matches the expected version for the PR's base branch
3Bug in valid stateStatus is one of: NEW, ASSIGNED, POST
4Release notes setRelease note text is non-empty and doesn't match the default template, OR release note type is "Release Note Not Required"
5Dependent bug statesEach dependent (linked via "Blocks") is in an allowed state
6Dependent bug target versionsEach dependent targets an allowed version
7Dependents existAt 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.0 also accepted)
  • main / master → 5.0.0 (prefix match — 5.0 also accepted). Update when main targets a new major version — check openshift/release/core-services/jira-lifecycle-plugin/config.yaml for the current value.

Dependent target version (what the "Blocks" linked bug must target):

  • release-4.X → 4.(X+1).0 or 4.(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.22 and newer: MODIFIED, ON_QA, VERIFIED
  • release-4.6 through release-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.X branches
  • NOT required for main / master (config sets exclude_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

  • gh CLI authenticated with GitHub
  • Jira MCP server configured (Atlassian Rovo MCP)
  • cloudId: use redhat.atlassian.net

Detailed Implementation Steps

Phase 1: Resolve Input

Parse the argument to determine input type:

  1. 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)
  2. PR number — plain integer

    • Determine repo from current git remote: gh repo view --json nameWithOwner -q .nameWithOwner
    • Then same as PR URL flow above
  3. JIRA key — matches [A-Z]+-[0-9]+

    • Require --branch argument (no PR context to infer branch)
    • If --branch not provided, error: "JIRA key input requires --branch (e.g., --branch release-4.20)"

Validate the JIRA key project:

  • Must be a bug project: OCPBUGS, DFBUGS, or PROJQUAY
  • 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_required using the mapping above

Phase 2: Gather Data

Fetch the primary bug:

Use mcp__atlassian__getJiraIssue:

  • cloudId: redhat.atlassian.net
  • issueIdOrKey: the JIRA key
  • fields: ["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 is outwardIssue (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.name is NOT "Closed"
  • FAIL if status.name is "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 .name starts with the expected prefix (e.g., "4.20" for release-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 .value equals "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 allowed dependent_valid_states list
    • FAIL otherwise: "expected dependent Jira Issue {key} to be in one of the following states: {allowed}, but it is {actual} instead"
  • 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_versions prefixes
    • FAIL otherwise: "expected dependent Jira Issue {key} to target a version in {allowed}, but it targets '{actual}' instead"

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)

  1. Resolve the version ID: use mcp__atlassian__getJiraIssueTypeMetaWithFields with projectIdOrKey: {PROJECT}, issueTypeId from the bug's issuetype.id, and requiredFieldsOnly: false
  2. Find customfield_10855 in the response fields — its allowedValues array contains all available versions. Match the entry whose .name equals the expected version string (e.g., 4.20.z) and extract its .id
  3. Update: mcp__atlassian__editJiraIssue with fields: {"customfield_10855": [{"id": "{version_id}"}]}

Fix: Status (checks 1, 3)

  1. Get available transitions: mcp__atlassian__getTransitionsForJiraIssue
  2. Find transition to a valid state (prefer "New" or "POST")
  3. Transition: mcp__atlassian__transitionJiraIssue with the transition ID

Fix: Release notes (check 4)

  1. 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}
    
  2. Update: mcp__atlassian__editJiraIssue with fields: {"customfield_10783": "{text}"}
  3. 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)

  1. Check if a "Blocks" linked dependent already exists in the issue's issuelinks (same project, outward direction)
  2. 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__createIssueLink with type: "Blocks", inwardIssue: {original_bug}, outwardIssue: {new_bug} (original bug blocks the new dependent)
    • Use mcp__atlassian__createJiraIssue then mcp__atlassian__createIssueLink
  3. If a dependent exists but targets wrong version or is in wrong state, offer to fix it

Fix: Dependent bug state (check 5)

  1. For each dependent in wrong state:
    • Get transitions: mcp__atlassian__getTransitionsForJiraIssue for the dependent
    • Find transition to an allowed state
    • Transition: mcp__atlassian__transitionJiraIssue

After all fixes applied:

  1. Re-run all 7 checks to confirm everything passes
  2. Display updated results table
  3. Remind user: "Comment /jira refresh on the PR to have the bot re-validate."

Error Handling

ErrorHandling
PR not foundDisplay error with PR URL, suggest checking the URL
No JIRA key in PR titleDisplay the PR title, explain the expected format: {JIRA-KEY}: description
JIRA issue not foundCheck if key is correct, check project access
MCP tool unavailableFall back to gh CLI for GitHub data; for JIRA, display manual fix instructions
Branch not recognizedWarn that branch {name} doesn't match expected patterns, ask for --branch override
Version ID not foundDisplay the expected version string, instruct user to set it manually in JIRA
Transition not availableList 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 main branch uses exclude_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:

VariableDescription
JIRA_URLJira instance URL (e.g., https://redhat.atlassian.net)
JIRA_USERNAMEAtlassian account email address
JIRA_API_TOKENAtlassian 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_TOKEN and JIRA_USERNAME are 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:

  1. Check Required Environment Variables

    • Verify JIRA_URL, JIRA_USERNAME, and JIRA_API_TOKEN are 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.
      
  2. Parse Arguments and Set Defaults

    • Parse project key from $1 (required): "OCPBUGS", "JIRA", "HYPE", etc.
    • Parse optional --assignee filter (defaults to "Unassigned")
    • Parse optional --days-inactive (defaults to 28 days)
    • Validate project key format (uppercase, may contain hyphens)
    • Create working directory: mkdir -p .work/jira-backlog/{project-key}/
  3. Construct JQL Query

    • Build base JQL query:
      project = {project-key}
      AND status NOT IN (Closed, Resolved, Done, Verified, Release Pending, ON_QA)
      AND (
        assignee IS EMPTY
        OR updated <= -{days-inactive}d
      )
      ORDER BY priority DESC, updated ASC
      
    • If --assignee provided, replace assignee filter with: AND assignee = {username} AND updated <= -{days-inactive}d
    • URL-encode the JQL query for use in API requests
  4. Fetch All Backlog Tickets Using curl with Pagination

    Fetch Strategy:

    • Fetch 1000 tickets per request (JIRA's maximum maxResults value)
    • Use pagination (startAt parameter) to fetch all tickets
    • Save each batch directly to disk to avoid memory issues
    • Continue until all tickets are fetched

    Authentication:

    • Use Basic Auth with JIRA_USERNAME:JIRA_API_TOKEN (base64-encoded) for Atlassian Cloud

    Important API Details:

    • Use POST /rest/api/3/search/jql endpoint with a JSON body containing jql, fields, and maxResults
    • 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
  5. Process Batches with Python to Filter and Group by Priority

    Create a Python script (.work/jira-backlog/{project-key}/process_batches.py) that:

    Inputs:

    • All batch files: .work/jira-backlog/{project-key}/batch-*.json

    Processing Logic:

    import json
    import glob
    from collections import defaultdict
    
    # Load all batches
    all_tickets = []
    for batch_file in sorted(glob.glob('.work/jira-backlog/{project-key}/batch-*.json')):
        with open(batch_file) as f:
            data = json.load(f)
            all_tickets.extend(data['issues'])
    
    # Filter for available tickets
    available_tickets = []
    for ticket in all_tickets:
        assignee = ticket['fields'].get('assignee')
    
        # Include if unassigned
        if assignee is None:
            available_tickets.append(ticket)
            continue
    
        # Include if assigned to a bot
        assignee_name = assignee.get('displayName', '').lower()
        if 'bot' in assignee_name:
            available_tickets.append(ticket)
            continue
    
        # Otherwise exclude (assigned to real person)
    
    # Group by priority
    priority_buckets = defaultdict(list)
    for ticket in available_tickets:
        priority_name = ticket['fields']['priority']['name']
    
        # Normalize priority names
        if priority_name in ['Critical', 'Blocker']:
            priority_buckets['Critical'].append(ticket)
        elif priority_name in ['High', 'Major']:
            priority_buckets['High'].append(ticket)
        elif priority_name in ['Normal', 'Medium']:
            priority_buckets['Normal'].append(ticket)
        elif priority_name in ['Low', 'Minor', 'Trivial']:
            priority_buckets['Low'].append(ticket)
    
    # Save filtered results
    with open('.work/jira-backlog/{project-key}/filtered.json', 'w') as f:
        json.dump(priority_buckets, f, indent=2)
    
    # Save statistics
    stats = {p: len(tickets) for p, tickets in priority_buckets.items()}
    with open('.work/jira-backlog/{project-key}/stats.json', 'w') as f:
        json.dump(stats, f, indent=2)
    
    print(f"Filtered {len(available_tickets)} available tickets from {len(all_tickets)} total")
    print(f"Priority distribution: {stats}")
    

    Outputs:

  • .work/jira-backlog/{project-key}/filtered.json - All filtered tickets grouped by priority

  • .work/jira-backlog/{project-key}/stats.json - Priority distribution statistics

    Run the script:

    python .work/jira-backlog/${PROJECT_KEY}/process_batches.py
    
  1. Intelligently Analyze and Select Best Tickets from Each Priority

    CRITICAL: This is NOT a mechanical selection process. You must read and analyze ticket content to make intelligent decisions.

    Load Filtered Data:

    • Read filtered tickets from .work/jira-backlog/{project-key}/filtered.json
    • Data is already grouped by priority level (Critical, High, Normal, Low)

    For each priority level (Critical, High, Normal, Low):

    Step 6a: Extract Tickets for Human-Readable Analysis

    • Take the first 10 tickets from each priority bucket (or all available if fewer than 10)
    • For each ticket, format in a readable way showing:
      • Key, summary, status, assignee, reporter
      • Days since last update, number of comments, watchers
      • Description preview (first 300-400 characters)
      • Last 1-3 comments (author, date, first 200 characters of body)
      • Components and labels
    • Output this formatted data so you can read and analyze it
    • DO NOT analyze inside Python/bash - extract the data in readable format first

    Step 6b: Analyze Ticket Suitability Read the formatted data and evaluate each ticket for:

    Age Classifications (consider when prioritizing):

    • Very Fresh (< 30 days): Highest priority - likely still relevant and active
    • Recent (30-60 days): Good candidates - still relatively fresh
    • Getting Stale (60-90 days): Verify still relevant before recommending
    • Old (90-120 days): Lower priority - may need verification/grooming
    • Very Old (120+ days): Lowest priority - likely needs re-evaluation before work

    Disqualifying Factors (skip these tickets):

    • Assigned to real people (non-bots) - these tickets should have been filtered out in Step 3, but double-check
    • Status is "Verified", "Release Pending", "ON_QA", "Done" (already complete)
    • Zero comments AND very old (120+ days) - likely abandoned
    • Comments indicate "duplicate", "won't fix", "closed as"
    • Comments show work is blocked or waiting on external dependencies

    Positive Indicators (prioritize these):

    • Unassigned or bot-assigned - available for anyone to pick up
    • Recency matters: Fresher tickets (< 60 days) should be weighted higher
    • Active discussion in comments showing real investigation (but not claimed by someone)
    • Clear, reproducible issue with steps to reproduce
    • Recent comments (< 30 days) saying "needs investigation", "looking for owner", "ready for work"
    • Has must-gather, logs, or reproduction environment attached/linked
    • Well-defined scope and acceptance criteria
    • Clear description with some comments showing interest

    Step 6c: Select Best 2 from Each Priority

    • Based on your analysis, select the 2 MOST SUITABLE tickets from each priority level
    • Selection Criteria (in order of importance):
      1. Recency: Fresher tickets (< 60 days) strongly preferred to ensure relevance
      2. Clarity: Clear reproduction steps, well-defined scope, available resources (must-gather, logs)
      3. Impact: User-facing issues, customer cases, or significant system problems
      4. Activity: Active discussion/comments showing the issue is real and being tracked
    • If a priority level has fewer than 2 suitable tickets, include what's available
    • Document WHY each ticket was selected (your reasoning, including age classification)
    • Flag tickets that need verification before work can start
    • In your recommendation, mention the ticket age using the classifications above
  2. 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
    
  3. Display Report to User

    • Show the formatted report
    • Provide guidance on next steps
    • Suggest using /jira:grooming for tickets lacking clarity
    • Suggest using /jira:solve to start working on selected ticket
  4. Save Report (Optional)

    • Offer to save report to .work/jira-backlog/{project-key}-{timestamp}.md
    • Useful for tracking backlog trends over time

Error Handling:

  • Missing environment variables: If JIRA_URL, JIRA_USERNAME, or JIRA_API_TOKEN are 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 jq on macOS, apt-get install jq on Linux)
  • Rate limiting: If API returns 429, implement exponential backoff (wait 60s, retry)

Performance Considerations:

  • Large batch size: Fetch 1000 tickets per request (JIRA's maximum) for efficiency
  • Direct file storage: Stream responses directly to disk, avoid loading into memory
  • No token consumption: Using curl avoids Claude's context/token limits
  • Parallel-safe: Can process very large backlogs (10,000+ tickets) without issues
  • Field filtering: Only request needed fields to minimize response size
  • Python processing: All filtering/analysis happens in Python, not in Claude context
  • Minimal Claude interaction: Only present final filtered/analyzed results to user

Return Value

  • Console Output: Formatted report showing suggested tickets organized by priority
  • Intermediate Files (created during processing):
    • .work/jira-backlog/{project-key}/batch-*.json - Raw JIRA API responses (one per 1000 tickets)
    • .work/jira-backlog/{project-key}/process_batches.py - Python script for filtering
    • .work/jira-backlog/{project-key}/filtered.json - All filtered tickets grouped by priority
    • .work/jira-backlog/{project-key}/stats.json - Priority distribution statistics
  • Optional Final Report: .work/jira-backlog/{project-key}-{timestamp}.md containing the full report
  • Summary Statistics: Count of available tickets per priority level

Examples

Note: All examples require JIRA_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.

  1. Find unassigned tickets in OCPBUGS project:

    /jira:backlog OCPBUGS
    

    Output: Intelligently analyzes tickets and shows 2 recommended tickets from each priority level (Critical, High, Normal, Low)

    Example performance (tested October 31, 2025):

    • Fetched 2,535 tickets in 3 batches
    • Found 817 available tickets (unassigned or bot-assigned)
    • No 413 errors or token limit issues
  2. Find stale tickets with custom inactivity threshold:

    /jira:backlog OCPBUGS --days-inactive 14
    

    Output: Report showing tickets with no activity for 14+ days, 2 per priority level

  3. Find tickets assigned to a specific user that are stale:

    /jira:backlog OCPBUGS --assignee jsmith --days-inactive 30
    

    Output: Report showing tickets assigned to jsmith with 30+ days of inactivity, 2 per priority level

  4. Find tickets in Hypershift project:

    /jira:backlog HYPE
    

    Output: Analyzes backlog and shows best 2 tickets from each priority in HYPE project

  5. Find tickets in CNV project:

    /jira:backlog CNV
    

    Output: Report showing available backlog tickets across all priorities in CNV project

Performance Note: The curl-based approach can handle large backlogs efficiently. In testing with OCPBUGS (2,535 tickets), the command successfully fetched and processed all tickets without hitting Claude's token limits or encountering 413 errors.

Arguments

  • project-key (required): JIRA project key to search (e.g., OCPBUGS, JIRA, HYPE, CNV)
    • Must be uppercase
    • May contain hyphens (e.g., "MY-PROJECT")
    • If not provided, will prompt user to specify
  • --assignee (optional): Filter by assignee username
    • Default: Search for unassigned tickets (assignee IS EMPTY)
    • If username provided: Find tickets assigned to that user with stale activity
    • Example: --assignee jsmith finds jsmith's stale tickets
  • --days-inactive (optional): Number of days of inactivity to consider a ticket stale
    • Default: 28 days
    • Lower values find more recently inactive tickets
    • Example: --days-inactive 14 finds tickets with 14+ days of no activity

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

  1. Classify all Epics in OCM:

    /jira:batch-categorize-activity-types OCM
    
  2. Classify Stories instead of Epics:

    /jira:batch-categorize-activity-types ARO --type Story
    
  3. Add JQL filter:

    /jira:batch-categorize-activity-types OCM --jql 'AND resolved >= "2025-01-01"'
    
  4. 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 data
  • classifications.json — Classification results with confidence and reasoning
  • report.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_TOKEN and JIRA_USERNAME environment variables set
  • uv (astral.sh/uv) — the gather script is run via uv run --with aiohttp
  • JIRA_URL defaults to https://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-apply flag 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

  1. Basic categorization (manual confirmation):

    /jira:categorize-activity-type ROX-12345
    
  2. Auto-apply for high confidence:

    /jira:categorize-activity-type ROX-12345 --auto-apply
    
  3. Process security vulnerability:

    /jira:categorize-activity-type ROX-28072 --auto-apply
    

    Expected: 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 result
  • report.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:

  1. 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"
    
  2. 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
    
  3. Verify tokens are configured:

    • Check that tokenstore.yaml contains actual tokens (not placeholder values)
    • GitHub token should not contain "YOUR_GITHUB_TOKEN"
    • Jira token should not contain "YOUR_JIRA_API_TOKEN"

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 --profile is not used, --github-project and --jira-project are 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

  1. 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
  2. Handle dryrun output:

    • If --dryrun was 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
  3. 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: 123 or 123 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:

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

  1. Use --dryrun first: Always preview what will be created before bulk cloning
  2. Set up profiles: Create profiles.yaml for projects you clone from frequently
  3. Verify tokens: Ensure your tokens have appropriate permissions
  4. Check issue states: Review GitHub issues before cloning to ensure they're relevant
  5. Batch responsibly: Clone in reasonable batches (10-20 issues at a time)
  6. 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

  1. Fetch bug ticket using getJiraIssue MCP tool:

    • Request all fields to ensure we have complete data
    • Verify the issue is a Bug type
    • Extract issue description, links, and custom fields
  2. Validate issue type:

    • If not a Bug, warn user and ask if they want to continue
    • Release notes are typically for bugs, but may apply to other types
  3. Parse bug description to extract required sections:

    • Cause: The root cause of the problem
    • Consequence: The impact or effect of the problem
  4. Handle missing sections:

    • If Cause or Consequence sections are missing, inform the user
    • Provide template format and ask user to update the bug description
    • Optionally, allow user to provide Cause/Consequence interactively

🔗 Phase 2: Extract Linked GitHub PRs

Extract all linked GitHub PR URLs from multiple sources:

  1. Remote links (Primary source - web links in Jira):

    • Check the Jira issue response for web links/remote links
    • Common field names: remotelinks, issuelinks with outwardIssue.fields.issuetype.name == "GitHub PR"
    • Look for GitHub PR URLs in remote link objects
    • Pattern: https://github.com/{org}/{repo}/pull/{number}
    • Extract PR URLs and parse into {org}/{repo} and {number}
  2. Description text: Scan bug description for GitHub PR URLs

    • Use regex pattern to find PR URLs: https://github\.com/[\w-]+/[\w-]+/pull/\d+
    • Extract and parse all matches
    • IMPORTANT: Do NOT use gh issue view {JIRA-KEY} - Jira keys are not GitHub issues
  3. Comments: Scan bug comments for GitHub PR URLs

    • Iterate through comments
    • Extract PR URLs using same regex pattern
    • IMPORTANT: Only look for full GitHub PR URLs, not issue references
  4. Deduplicate: Create unique set of PR URLs

  5. Search by bug number (Fallback if no PR URLs found):

    • If no PRs found via links, search GitHub for PRs mentioning the bug
    • For OCPBUGS: Search common repos (openshift/hypershift, openshift/cluster-api-provider-*):
      # Try common OpenShift repos
      for repo in "openshift/hypershift" "openshift/cluster-api-provider-aws" "openshift/origin"; do
        gh pr list --repo $repo --search "{issue-key} in:title,body" --state all --limit 10 --json number,url,title
      done
      
    • Ask user to confirm which PRs are relevant
    • IMPORTANT: Never use gh issue view {JIRA-KEY} - this will fail because Jira keys are not GitHub issue numbers
  6. Validate: Ensure at least one PR is found

    • If no PRs found after all attempts, show error: "No GitHub PRs found linked to {issue-key}. Please link at least one PR to generate release notes."
    • Provide instructions on how to link PRs in Jira

📊 Phase 3: Analyze Each GitHub PR

For each linked PR, analyze multiple sources to extract Fix, Result, and Workaround information:

  1. Extract repository and PR number from URL:

    • Parse: https://github.com/{org}/{repo}/pull/{number}
    • Store: {org}/{repo} as REPO, {number} as PR_NUMBER
  2. Fetch PR details using gh CLI:

    gh pr view {PR_NUMBER} --json body,title,commits,url,state --repo {REPO}
    
    • Extract: title, body/description, commits array, state
    • Handle errors: If PR is inaccessible, log warning and skip
  3. Fetch PR diff using gh CLI:

    gh pr diff {PR_NUMBER} --repo {REPO}
    
    • Analyze code changes to understand what was fixed
    • Look for key changes in error handling, validation, etc.
  4. Fetch PR comments using gh CLI:

    gh pr view {PR_NUMBER} --json comments --repo {REPO}
    
    • Extract reviewer comments and author responses
    • Look for clarifications about the fix or workarounds
  5. Analyze all sources:

    • PR Title: Often summarizes the fix
    • PR Body/Description: Usually contains detailed explanation
    • Commit Messages: May provide step-by-step implementation details
    • Code Changes: Shows exactly what was modified
    • PR Comments: May contain clarifications or additional context
  6. Extract key information:

    • Fix: What code/configuration changes were made to address the problem
    • Result: What behavior changed after the fix
    • Workaround: If mentioned, any temporary solutions before the fix

🤖 Phase 4: Synthesize Release Note Content

Combine information from all analyzed PRs into a cohesive release note:

  1. Combine Cause/Consequence from Jira bug:

    • Use the extracted Cause and Consequence sections
    • Clean up formatting (remove Jira markup if needed)
  2. Synthesize Fix from all PRs:

    • If single PR: Use the PR's fix description
    • If multiple PRs: Combine into coherent narrative
    • Focus on "what was changed" rather than "how it was coded"
    • Keep it concise but complete
  3. Synthesize Result from all PRs:

    • Describe the outcome after the fix is applied
    • Focus on user-visible changes
    • Example: "The control plane operator no longer crashes when..."
  4. Extract Workaround (if applicable):

    • Check if PRs mention temporary solutions
    • Only include if a workaround was documented
    • Omit this section if no workaround exists
  5. Format according to template:

    Cause: <extracted from bug description>
    Consequence: <extracted from bug description>
    Fix: <synthesized from PR analysis>
    Result: <synthesized from PR analysis>
    Workaround: <synthesized from PR analysis if applicable>
    

🔒 Phase 5: Security Validation

Scan the generated release note text for sensitive data before submission:

  1. Prohibited content patterns:

    • Credentials: Passwords, API tokens, access keys
    • Cloud keys: AWS access keys (AKIA...), GCP service accounts, Azure credentials
    • Kubeconfigs: Cluster credentials, service account tokens
    • SSH keys: Private keys, authorized_keys content
    • Certificates: PEM files, private key content
    • URLs with credentials: https://user:pass@example.com
  2. Scanning approach:

    • Use regex patterns to detect common credential formats
    • Check for base64-encoded secrets
    • Look for common secret prefixes (sk_, ghp_, etc.)
  3. Action if detected:

    • STOP release note creation immediately
    • Inform user what type of data was detected (without showing it)
    • Example: "Detected what appears to be an API token in the release note text."
    • Ask user to review PR content and redact sensitive information
    • Provide guidance on safe alternatives (use placeholders like <redacted>, YOUR_API_KEY, etc.)

📝 Phase 6: Select Release Note Type

Prompt user to select the appropriate Release Note Type:

  1. Available options (from Jira dropdown):

    • Bug Fix (most common for OCPBUGS)
    • Release Note Not Required
    • Known Issue
    • Enhancement
    • Rebase
    • Technology Preview
    • Deprecated Functionality
    • CVE
  2. Auto-detection (optional):

    • For OCPBUGS: Default to "Bug Fix"
    • Check PR titles/descriptions for keywords
    • Suggest type based on content analysis
  3. User confirmation:

    • Show suggested type
    • Allow user to override
    • Use AskUserQuestion tool for interactive selection

✅ Phase 7: Update Jira Ticket

Update the Jira bug ticket with generated release note:

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
  1. Handle update errors:
    • Permission denied: User may not have rights to update these fields
    • Invalid field value: Release Note Type value not in allowed list
    • Field not found: Custom field IDs may be different in different Jira instances

📤 Phase 8: Display Results

Show the user what was created:

  1. Display generated release note:

    Release Note Created for {issue-key}
    
    Type: Bug Fix
    
    Text:
    ---
    Cause: ...
    Consequence: ...
    Fix: ...
    Result: ...
    Workaround: ...
    ---
    
    Updated: https://redhat.atlassian.net/browse/{issue-key}
    
  2. Provide next steps:

    • Link to the updated Jira ticket
    • Suggest reviewing the release note in Jira
    • Mention that the release note can be edited manually if needed

Arguments

  • $1 – issue-key (required) Jira issue key for the bug (e.g., OCPBUGS-12345). Must be a valid bug ticket with linked GitHub PRs.

Return Value

  • Issue Key: The Jira issue that was updated
  • Release Note Type: The selected release note type
  • Release Note Text: The generated release note content
  • Issue URL: Direct link to the updated Jira ticket

Examples

Basic Usage

Create release note for a bug with linked PRs:

/jira:create-release-note OCPBUGS-38358

The command will:

  1. Fetch the bug from Jira
  2. Extract Cause and Consequence from the description
  3. Find and analyze all linked GitHub PRs
  4. Generate the release note
  5. Prompt for Release Note Type selection
  6. Update the Jira ticket
  7. Display the results

Example Output

Analyzing OCPBUGS-38358...

Found bug: "hostedcontrolplane controller crashes when hcp.Spec.Platform.AWS.CloudProviderConfig.Subnet.ID is undefined"

Extracted from bug description:
  Cause: hostedcontrolplane controller crashes when hcp.Spec.Platform.AWS.CloudProviderConfig.Subnet.ID is undefined
  Consequence: control-plane-operator enters a crash loop

Found 1 linked GitHub PR:
  - https://github.com/openshift/hypershift/pull/4567

Analyzing PR #4567...
  Title: "Fix panic when CloudProviderConfig.Subnet is not specified"
  Commits: 2
  Files changed: 3

Synthesizing release note...

Select Release Note Type:
1. Bug Fix
2. Release Note Not Required
3. Known Issue
4. Enhancement
5. CVE

Selection: 1 (Bug Fix)

Updating Jira ticket...

✓ Release Note Created for OCPBUGS-38358

Type: Bug Fix

Text:
---
Cause: hostedcontrolplane controller crashes when hcp.Spec.Platform.AWS.CloudProviderConfig.Subnet.ID is undefined
Consequence: control-plane-operator enters a crash loop
Fix: Added nil check for CloudProviderConfig.Subnet before accessing Subnet.ID field
Result: The control-plane-operator no longer crashes when CloudProviderConfig.Subnet is not specified
---

Updated: https://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

  1. Link PRs early: Add GitHub PR links to bugs as soon as PRs are created
  2. Use structured bug descriptions: Always include Cause and Consequence sections
  3. Review before submission: Check the generated release note before confirming
  4. Sanitize PR content: Don't include credentials in PR descriptions or commits
  5. One release note per bug: Don't run this command multiple times for the same bug
  6. Update if needed: Release notes can be manually edited in Jira after creation

Prerequisites

Required Tools

  1. MCP Jira Server: Must be configured and accessible

  2. 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
  3. Access to GitHub Repositories: Must have read access to repos where PRs are located

    • PRs in private repos require appropriate GitHub permissions
    • Public repos should work without additional configuration

Required Permissions

  1. Jira Permissions:

    • Read access to bug tickets
    • Write access to Release Note Type field (customfield_10785)
    • Write access to Release Note Text field (customfield_10783)
  2. GitHub Permissions:

    • Read access to pull requests
    • Read access to repository diffs and commits

See Also

  • jira:solve - Analyze and solve Jira issues
  • jira:create - Create Jira issues with guided workflows
  • jira:generate-test-plan - Generate test plans for PRs
  • jira:status-rollup - Create status rollup reports

Technical Notes

Jira Custom Fields

The command uses these Jira custom field IDs:

  • customfield_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 SectionSource
MetadataIssue key, creation date, authors
SummaryEpic/Feature description overview
MotivationProblem statement from description
User StoriesDerived from description or child stories
GoalsEpic/Feature objectives and acceptance criteria
Non-GoalsOut of scope items from description
ProposalImplementation details from child issues
Topology ConsiderationsDetected from components (HyperShift, etc.)
Test PlanUser prompts or child issue details
Graduation CriteriaDerived from acceptance criteria
Support ProceduresUser prompts

Usage Examples

  1. Generate enhancement from feature:

    /jira:generate-enhancement OCPSTRAT-1596
    

    → Fetches feature, generates enhancement proposal

  2. Generate enhancement from epic:

    /jira:generate-enhancement HIVE-2589
    

    → Fetches epic and child issues, generates enhancement proposal

  3. With custom output directory:

    /jira:generate-enhancement CNTRLPLANE-100 --output enhancements/hypershift/
    

    → Generates enhancement in specified directory

  4. Verify PRs match enhancement:

    /jira:generate-enhancement OCPSTRAT-1596 --verify
    

    → Compares enhancement against linked PRs, shows deviations and incomplete items

  5. Update enhancement from actual implementation:

    /jira:generate-enhancement OCPSTRAT-1596 --sync-from-prs
    

    → Updates enhancement with actual API changes, test coverage, implementation approach

  6. 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

  1. Complete the epic/feature first: Ensure the Jira epic or feature has comprehensive content before generating the enhancement
  2. Review and refine: The generated enhancement is a starting point; review and enhance with technical details
  3. Iterate with stakeholders: Share the draft enhancement for feedback before submitting PR
  4. Keep synchronized: Regenerate the enhancement as the epic/feature evolves in Jira
  5. 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

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:

  1. Extract GitHub PRs (via jira:extract-prs skill)

    • Discovers all descendant issues recursively using parent = KEY BFS
    • 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
  2. Generate Documentation (via jira-doc-generator skill)

    • 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.md
  • plugins/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:

  1. Fetch the main feature issue
  2. Recursively discover all related issues (sub-tasks, linked issues, etc.)
  3. Extract all GitHub PR links from Remote Links API and text
  4. Analyze each PR (description, code changes, discussions)
  5. Synthesize all information into a comprehensive document
  6. Save to .work/jira/feature-doc/OCPSTRAT-1612/feature-doc.md
  7. 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

  1. jq - JSON parser

    • Check: which jq
    • Install: brew install jq (macOS) or apt-get install jq (Linux)
  2. 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
  3. JIRA Access - Read permissions for issues

    • Network access to https://redhat.atlassian.net
  4. 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

  1. Link issues in Jira: Ensure sub-tasks and related issues are linked as sub-tasks or parent issues in Jira
  2. Use Remote Links: Add GitHub PRs via "Link Issue" in JIRA UI (not just in descriptions)
  3. Use for completed features: Best results when feature is fully implemented
  4. Review and edit: Generated documentation is a starting point - review and enhance manually
  5. Save the output: Keep generated docs in version control for team reference

See Also

  • jira:solve - Analyze and solve Jira issues
  • jira:create-release-note - Generate release notes from bugs and PRs
  • jira:status-rollup - Create status rollup reports
  • utils: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):

  1. 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
  2. Backup: Text extraction from descriptions and comments
    • Regex: https?://github\.com/[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+/pulls?/[0-9]+

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
  1. 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)
  2. If project key is NOT provided:

    • Use mcp__atlassian-mcp__jira_get_all_projects to 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
  3. Validate project access:

    • Use mcp__atlassian-mcp__jira_search with JQL: project = "{project-key}" AND status != Closed
    • Verify the project exists and is accessible
Step 2. Determine Target Component(s)
  1. If --component parameter is provided:

    • Use the component name directly
  2. If --component is NOT provided:

    • Use mcp__atlassian-mcp__jira_search_fields with keyword "component" to find the component field ID
    • Query component values through mcp__atlassian-mcp__jira_search with fields=components and JQL project = "{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
Step 3. Resolve User Identifiers

For each user filter parameter:

  1. Check if it's an email (contains @): Use as-is for script parameter

  2. If it's a display name (doesn't contain @):

    • Use mcp__atlassian-mcp__jira_get_user_profile with the name as the user_identifier parameter
    • Show found user details and ask for confirmation
    • If confirmed, use the email address; if not, ask for email directly
  3. Handle exclusion prefix (exclamation mark):

    • Strip the prefix before lookup
    • Use --exclude-assignee parameter 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 list
  • issues/{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:

  1. Read the existing Status Summary field (current_status_summary in 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_range for 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
  2. Identify key events from changelog_in_range:

    • Status transitions
    • Assignee changes
    • Priority/scope changes
    • Status Summary field changes (color transitions)
  3. Analyze comments (excluding bots with is_bot: true):

    • Look for blockers, risks, achievements
    • Note significant updates
  4. 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_name fields (not author logins) when attributing contributions. Always use first names, never GitHub handles.
  5. 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):

  1. Features delivered or completing
  2. Features whose status changed to Red or Yellow this week
  3. Features with Red/Yellow status and new activity this week
  4. 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:

  1. Completed/delivered features first
  2. Features whose status changed to Red or Yellow this week
  3. Red/Yellow features with new activity
  4. 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:

  • approve or a: Accept and output
  • modify or m: Modify the section (rewrite entries, skip/reorder features)
  • regenerate or r: Regenerate from cached data with different focus
  • quit or q: 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)
  1. Write the final markdown to /tmp/feature-updates.md

  2. 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.

  1. Convert to styled HTML using the Python markdown library:
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>")
  1. 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.

  1. Start a local HTTP server in the background:
python3 -m http.server 8787 --directory /tmp --bind 127.0.0.1
  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.
  1. Wait for user confirmation, then stop the background server.

Examples

  1. 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

  2. With label filter:

    /jira:generate-feature-updates OCPSTRAT --label strategic-work
    
  3. With specific users:

    /jira:generate-feature-updates OCPSTRAT --component "Hosted Control Planes" user@redhat.com
    
  4. Serve as HTML for Google Docs pasting:

    /jira:generate-feature-updates OCPSTRAT --component "Hosted Control Planes" --serve
    
  5. 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

  1. 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
  2. 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
  3. 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
  4. Significant Activity Filter:

    • Issues with no noteworthy activity are automatically skipped
    • Prevents noise from issues that had only bot updates or trivial changes
  5. 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 aiohttp package installed
  • Jira MCP server configured and accessible
  • Environment variables:
    • JIRA_TOKEN or JIRA_PERSONAL_TOKEN: Jira API bearer token
    • GITHUB_TOKEN or authenticated gh CLI
  • For --serve: Python markdown package (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-points flag 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 --status flag 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
  • 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-points flag 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-points flag 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

  1. Single project weekly review:

    /jira:grooming OCPSTRAT last-week
    
  2. Multiple OpenShift projects:

    /jira:grooming "OCPSTRAT,OCPBUGS,HOSTEDCP" last-2-weeks
    
  3. Filter by component:

    /jira:grooming OCPSTRAT last-week --component "Control Plane"
    
  4. Custom date range:

    /jira:grooming OCPBUGS 2024-10-01:2024-10-15
    
  5. Filter by label:

    /jira:grooming OCPSTRAT last-week --label "technical-debt"
    
  6. Combine component and label filters:

    /jira:grooming OCPSTRAT last-week --component "Control Plane" --label "performance"
    
  7. Query sprint issues with component filter:

    /jira:grooming OCPBUGS "OTA 277" --component "Cluster Version Operator"
    
  8. Filter by issue type:

    /jira:grooming OCPSTRAT last-week --type Bug
    
  9. Filter by multiple issue types:

    /jira:grooming OCPSTRAT last-week --type "Bug,Epic"
    
  10. Combine all filters:

    /jira:grooming OCPSTRAT last-week --component "Control Plane" --label "performance" --type Story
    
  11. Sprint retrospective with closed issues and story points:

/jira:grooming "CORENET" "Sprint 276" --status Closed --story-points
  1. 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
  • --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 reports
  • jira: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:

  1. Overview Mode (no --component flag): Lists all components with high-level statistics
  2. Detail Mode (--component specified): 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:

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-weeks
    • last-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 maxResults value)
  • Use pagination (startAt parameter) 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.sh wrapper 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/jql endpoint with a JSON body containing jql, fields, and maxResults
  • Wrapper automatically adds Authorization: Basic header
  • 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 auth skill

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

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

  1. Basic overview - all components from last week:

    /jira:issues-by-component OCPBUGS last-week
    

    Output: High-level summary of all components with issue counts and top issues

  2. 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

  3. Overview with assignee filter:

    /jira:issues-by-component OCPBUGS last-2-weeks --assignee jsmith
    

    Output: All components showing only issues assigned to jsmith

  4. 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

  1. 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

  2. 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

  3. Component detail with user and status filters:

    /jira:issues-by-component OCPBUGS --component "Storage" --assignee jsmith --status Open
    

    Output: Detailed view of open Storage issues assigned to jsmith

  4. Component detail with search in summary and description:

    /jira:issues-by-component OCPBUGS --component "Networking" --search "DNS timeout" --search-description
    

    Output: Detailed Networking issues containing "DNS" or "timeout" in summary or description

Advanced Examples

  1. 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 CVE
    

    Output: CVE-related issues in CVO component from November that are still active

  2. Reporter-based filtering:

    /jira:issues-by-component OCPBUGS last-month --reporter asmith --status Closed
    

    Output: Overview of all components showing closed issues reported by asmith

  3. 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-weeks
    • last-month
    • YYYY-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
  • --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 --search is also specified
    • Searches both summary and description text
    • May return more results but slower
    • Example: --search "DNS" --search-description

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:

  1. Verify gh2jira binary exists:

    which gh2jira || echo "gh2jira not found. Run /jira:setup-gh2jira to install."
    
  2. Verify configuration files exist:

    • Check for tokenstore.yaml in the gh2jira directory
    • Check for profiles.yaml if using profiles
    • Check for workflows.yaml for state mapping configuration
    • If missing, provide instructions on creating them
  3. 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 (json or yaml, default: json)

Argument validation:

  • If --profile is not used, both --github-project and --jira-project should be provided
  • If --porcelain is used, --output specifies 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

  1. Run the gh2jira command:

    • Execute the constructed command
    • Capture stdout and stderr
    • Monitor exit code
  2. Parse reconciliation output:

    • The command identifies Jira issues with GitHub links
    • Compares states according to workflows.yaml mapping
    • Reports mismatches
  3. 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: --output to 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

  1. Run regularly: Schedule reconciliation checks weekly or after major releases
  2. Use porcelain for automation: Integrate with CI/CD or reporting tools using JSON/YAML output
  3. Customize workflows: Edit workflows.yaml to match your team's Jira workflow states
  4. 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.yaml with your credentials
  • Optionally creates profiles.yaml for project shortcuts
  • Creates default workflows.yaml for 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:

  1. Reconfigure the existing installation
  2. Reinstall from scratch
  3. 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: ~/.bashrc or ~/.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

  1. Secure your tokens: The setup command sets tokenstore.yaml to mode 600 (owner read/write only). Never commit this file to version control.

  2. Use profiles: Create profiles for frequently-used project combinations to simplify commands.

  3. Test connections: After setup, test both GitHub and Jira connections with gh2jira github list and gh2jira jira list.

  4. Backup configuration: Keep a backup of your configuration files (excluding tokenstore.yaml) for easy recovery.

  5. Update regularly: Periodically update gh2jira by running cd $GH2JIRA_DIR && git pull && make.

  6. Token rotation: When rotating tokens, simply edit tokenstore.yaml with new values or run /jira:setup-gh2jira again.

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

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

  1. Verify tokens: Check tokenstore.yaml has valid tokens
  2. Test connections: Run gh2jira github list and gh2jira jira list
  3. Check profiles: Verify profiles.yaml has correct project names
  4. Review errors: Run with verbose output for detailed errors

Workflow reconciliation not working

  1. Check workflows.yaml exists and has valid YAML syntax
  2. Verify state names match your Jira workflow states exactly
  3. 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 = KEY BFS
  • 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 = KEY BFS 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

  1. Extract issue ID from $1
  2. Parse --start-date and --end-date if provided
  3. Validate date format (YYYY-MM-DD)
  4. Default to issue creation date if no start-date provided
  5. 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/:

  1. 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
  2. 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)
  3. Formatting (formatting.md):

    • Generate Jira markdown using markdown_comment format
    • Include sections: Overall Status, This Period, Next Steps, Risks, Metrics

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:

  • post or p: Proceed to post comment
  • modify or m: Request changes, regenerate from cached data
  • cancel or c: 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:

  1. Use addCommentToJiraIssue with contentFormat: "markdown" to post to the root issue
  2. Comment includes footer: _Generated with [Claude Code](https://claude.com/claude-code) via `/jira:status-rollup {issue-id} --start-date {date} --end-date {date}`_
  3. 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}.md containing:
    • 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

  1. Generate status for a Feature for a specific week:

    /jira:status-rollup FEATURE-123 --start-date 2025-01-06 --end-date 2025-01-13
    

    Output: Weekly status comment posted to FEATURE-123

  2. Generate status for an Epic:

    /jira:status-rollup EPIC-456 --start-date 2025-01-06 --end-date 2025-01-13
    

    Output: Epic status summary with all child stories analyzed

  3. Generate status for a Story with subtasks:

    /jira:status-rollup STORY-789
    

    Output: Status from story creation date to today

  4. Generate status from a start date to now:

    /jira:status-rollup CNTRLPLANE-1234 --start-date 2025-01-06
    

    Output: Status from Jan 6 to today

Example Output:

## 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

ErrorHandling
Invalid issue IDDisplay error with verification instructions
No child issuesGenerate summary for single issue (root only)
No activity in date rangeGenerate summary based on current state
Invalid date formatDisplay 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 = KEY JQL 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
  1. 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)
  2. If project key is NOT provided:

    • Use getVisibleJiraProjects to 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
  3. Validate project access:

    • Use searchJiraIssuesUsingJql with JQL: project = "{project-key}" AND status != Closed
    • Verify the project exists and is accessible
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 KeySourceKey Overrides
ARORead ../reference/aro-hcp.mdOnly Features/Initiatives; milestone tiers (HPSTRAT-63/130); prepend format with date stamp
CNTRLPLANERead ../reference/cntrlplane.mdCNTRLPLANE-specific conventions
GCPRead ../reference/gcp-hcp.mdGCP HCP team requirements
OCPBUGSRead ../reference/ocpbugs.mdOCPBUGS bug conventions

Implementation:

  1. Match the resolved project key against the table above
  2. If a match is found, load the conventions using the source method shown (either Read the reference file or invoke the Skill)
  3. 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)
  4. 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)
  1. If --component parameter is provided:

    • Use the component name directly
  2. If --component is NOT provided:

    • Query component values through searchJiraIssuesUsingJql with fields=components and JQL project = "{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
Step 3. Resolve User Identifiers

For each user filter parameter:

  1. Check if it's an email (contains @): Use as-is for script parameter

  2. If it's a display name (doesn't contain @):

    • Use lookupJiraAccountId with 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
  3. Handle exclusion prefix (exclamation mark):

    • Strip the prefix before lookup
    • Use --exclude-assignee parameter 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 list
  • issues/{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:

  1. Identify key events from changelog_in_range:

    • Status transitions
    • Assignee changes
    • Priority changes
  2. Analyze comments (excluding bots with is_bot: true):

    • Look for blockers, risks, achievements
    • Note significant updates
  3. 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
  4. 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:

  • approve or a: Proceed with the proposed update
  • modify or m: Modify the text (prompt for new text)
  • skip or s: Skip this issue and move to next
  • quit or q: 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_field requires valid native ADF JSON with the expected list structure and color; never apply a text-prefix check to an ADF document. ryg_field_markdown requires 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

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

  1. 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

  2. Interactive mode (prompts for project and component):

    /jira:update-weekly-status
    

    Output: Prompts for project selection, then component selection

  3. Specify project, auto-select component:

    /jira:update-weekly-status OCPSTRAT
    

    Output: Prompts for component selection from OCPSTRAT components

  4. With label filter:

    /jira:update-weekly-status OCPSTRAT --label strategic-work
    

    Output: Prompts for component, filters issues with "strategic-work" label

  5. With specific users (by email):

    /jira:update-weekly-status OCPBUGS antoni@redhat.com jdoe@redhat.com
    

    Output: Only processes issues assigned to Antoni or Jane

  6. With excluded users (by email):

    /jira:update-weekly-status OCPSTRAT !manager@redhat.com
    

    Output: Processes all issues except those assigned to manager@redhat.com

  7. 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

  8. Full example with all options:

    /jira:update-weekly-status OCPSTRAT --component "Control Plane" --label strategic-work antoni@redhat.com !dave@redhat.com
    

    Output: 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

  1. 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
  2. Efficiency:

    • Batch data gathering minimizes API calls
    • Pre-filtered data (date range) reduces context size
    • Each issue processed with fresh context for better analysis
  3. 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
  4. 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
  5. Format Validation:

    • Validate Status Summary text format before updating
    • Ensure the value is a valid ADF JSON document with the correct bulletList/listItem structure
    • Check for Color Status line (Red/Yellow/Green)
    • Warn if format doesn't match expected template

Prerequisites

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:

  1. Creating project-specific skills with default label filters
  2. Defining team-specific Status Summary field mappings (modify --status-field parameter)
  3. Customizing color status thresholds based on team velocity
  4. 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

  1. Parse Arguments and Build Filters – Extract arguments (target version, component filter, bug ID). Build JQL query for:

    • Single bug mode (if --bug provided): Query specific bug by issue key (version not required)
    • Component + version mode (if both provided): Query proposed blockers matching target version and component, excluding already-fixed bugs (status not in Closed, Release Pending, Verified, ON_QA)
    • Version only mode (if version provided): Query all proposed blockers for target version, excluding already-fixed bugs
    • Error: If neither --bug nor version provided, show error message
  2. Query Proposed Blockers – Use MCP tools to fetch bugs based on mode:

    • Single bug: Fetch one specific bug with all fields
    • Component + version: Fetch proposed blockers matching version and component filter, excluding already-fixed statuses
    • Version only: Fetch all proposed blockers for target version, excluding already-fixed statuses
  3. Analyze Each Blocker – Apply Red Hat OpenShift release blocker criteria:

    • Strong blockers: Component Readiness regression, Service Delivery blocker, data loss, install/upgrade failures, service unavailability, regressions
    • Never blockers: Severity below Important, new features without regression
    • Workaround assessment: Check if acceptable workaround exists (idempotent, safe at scale, timely)
  4. Generate Recommendations – Create report with APPROVE/REJECT/DISCUSS verdicts and justifications.

Technical Details

The skill file provides complete details on:

  • JQL query construction for proposed blockers
  • Blocker scoring criteria and point values
  • Workaround assessment logic
  • Decision thresholds

Usage Examples

Version-Based Validation

  1. Validate all proposed blockers for a target version:
    /jira:validate-blockers 4.21
    

Component-Based Validation

  1. Validate blockers for a specific component and version:
    /jira:validate-blockers 4.21 "Hypershift"
    

Single Bug Validation

  1. 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.Y and X.Y.0 in Target Version, Target Backport Versions, and Affected Version fields
    • Excludes already-fixed bugs with status: Closed, Release Pending, Verified, ON_QA

    Examples:

    • 4.21 - Validates active proposed blockers for 4.21
    • 4.22 - Validates active proposed blockers for 4.22

    Note: Not required when --bug is provided.

  • $2 – component-filter (optional) Component name(s) to filter proposed blockers. Supports single or multiple (comma-separated) components.

    Examples:

    • "Hypershift" - Single component
    • "Hypershift,Cluster Version Operator" - Multiple components

    Note: Ignored if --bug is provided. Requires target-version to be specified.

    Default: All components for the target version

  • --bug (optional) Validate a single specific bug by its JIRA issue key.

    When provided, analyzes only this bug and ignores both target-version and component-filter.

    Examples:

    • --bug OCPBUGS-36846

    Note: When --bug is provided, target-version and component-filter are ignored.

    Default: Not specified

Return Value

  • Markdown Report: Blocker validation report with recommendations
  • Exit Code:
    • 0 - Success
    • 1 - Error querying JIRA or analyzing bugs

Prerequisites

  • Jira MCP server must be configured (see plugin README)
  • 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

  1. Resolve Input — Parse PR URL/number or JIRA key. Extract JIRA key from PR title and target branch via gh pr view.
  2. Gather Data — Fetch the JIRA bug with all fields via MCP. Follow issue links to find dependent bugs.
  3. Validate — Run all 7 checks against the branch-specific expected values. Produce a pass/fail results table.
  4. Report — Render results matching the jira-lifecycle-plugin bot comment format, with fix instructions for each failure.
  5. 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
  • --branch (optional) Target branch override. Required when input is a JIRA key (no PR context). Format: release-4.X, main, or master.

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

  • gh CLI 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 refresh on 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